API

This is the internal API reference for ibek

ibek

ibek.__version__: str

Version number as calculated by pypa/setuptools_scm

ibek.globals

A few global definitions

class ibek.globals.BaseSettings

A Base class for setting consistent Pydantic model configuration

ibek.globals.render_with_utils(context: Dict, template_text: str) → str

Render a Jinja template with the global __utils__ object in the context

ibek.support

The Support Class represents a deserialized <MODULE_NAME>.ibek.support.yaml file.

class ibek.support.When(value)

An enumeration.

class ibek.support.Arg(*, type: str, name: str, description: str)

Base class for all Argument Types

class ibek.support.FloatArg(*, type: Literal['float'] = 'float', name: str, description: str, default: float | None = None)

An argument with a float value

class ibek.support.StrArg(*, type: Literal['str'] = 'str', name: str, description: str, default: str | None = None)

An argument with a str value

class ibek.support.IntArg(*, type: Literal['int'] = 'int', name: str, description: str, default: int | None = None)

An argument with an int value

class ibek.support.BoolArg(*, type: Literal['bool'] = 'bool', name: str, description: str, default: bool | None = None)

An argument with an bool value

class ibek.support.ObjectArg(*, type: Literal['object'] = 'object', name: str, description: str, default: str | None = None)

A reference to another entity defined in this IOC

class ibek.support.IdArg(*, type: Literal['id'] = 'id', name: str, description: str, default: str | None = None)

Explicit ID argument that an object can refer to

class ibek.support.Database(*, file: str, args: Dict[str, str | None])

A database file that should be loaded by the startup script and its args

class ibek.support.EnvironmentVariable(*, name: str, value: str)

An environment variable that should be set in the startup script

class ibek.support.Function(*, name: str, args: Dict[str, Any], header: str = '', when: When = 'every', type: Literal['function'] = 'function')

A script snippet that defines a function to call

class ibek.support.Comment(*, type: Literal['comment'] = 'comment', when: When = 'every', value: str = '')

A script snippet that will have ‘# ‘ prepended to every line for insertion into the startup script

class ibek.support.Text(*, type: Literal['text'] = 'text', when: str = 'every', value: str = '')

A script snippet to insert into the startup script

class ibek.support.Value(*, name: str, description: str, value: str)

A calculated string value for a definition

class ibek.support.Definition(*, name: str, description: str, args: Sequence[FloatArg | StrArg | IntArg | BoolArg | ObjectArg | IdArg] = (), values: Sequence[Value] = (), databases: Sequence[Database] = (), pre_init: Sequence[Function | Comment | Text] = (), post_init: Sequence[Function | Comment | Text] = (), env_vars: Sequence[EnvironmentVariable] = ())

A single definition of a class of Entity that an IOC instance may instantiate

class ibek.support.Support(*, module: str, defs: Sequence[Definition])

Lists the definitions for a support module, this defines what Entities it supports

Provides the deserialize entry point.

ibek.ioc

Functions for generating an IocInstance derived class from a support module definition YAML file

class ibek.ioc.Entity(*, type: str, entity_enabled: bool = True)

A baseclass for all generated Entity classes.

classmethod add_ibek_attributes(entity: Entity)

Whole Entity model validation

TODO at present an object reference to an ID where the referred object violates schema is seen as “KeyError: “object XXX not found in […]” which hides the schema violation error.

This could potentially be fixed by doing the validation here instead (removing extra:forbid from the model_config). BUT, at present passing the info arg to this function receives a dict of the IOC instance that created this entity, not the entity itself. This may be a pydantic bug?

ibek.ioc.make_entity_model(definition: Definition, support: Support) → Type[Entity]

Create an Entity Model from a Definition instance and a Support instance.

ibek.ioc.make_entity_models(support: Support)

Create Entity subclasses for all Definition instances in the given Support instance. Returns a list of the Entity subclasses Models.

ibek.ioc.make_ioc_model(entity_models: Sequence[Type[Entity]]) → Type[IOC]

Create an IOC derived model, by setting its entities attribute to be of type ‘list of Entity derived classes’.

ibek.ioc.clear_entity_model_ids()

Resets the global id_to_entity dict.

class ibek.ioc.IOC(*, ioc_name: str, description: str, generic_ioc_image: str, entities: Sequence[Entity])

Used to load an IOC instance entities yaml file into a Pydantic Model.

ibek.modules

Blank module to be populated with modules, which contain Entity subclasses made with make_entity_models

ibek.render

Functions for rendering lines in the boot script using Jinja2

class ibek.render.Render

A class for generating snippets of startup script / EPICS DB by using Jinja to combine snippet templates from support module definition yaml with substitution values supplied in ioc entity yaml

render_text(instance: Entity, text: str, when=When.every, suffix='') → str

Add in the next line of text, honouring the once flag which will only add the line once per IOC.

Jinja rendering of values/args has already been done in Entity.__post_init__ but we pass all strings though jinja again to render any other jinja in the IOC (e.g. database and function entries)

once uses the name of the definition + suffix to track which lines have been rendered already. The suffix can be used where a given Entity has more than one element to render once (e.g. functions)

render_function(instance: Entity, function: Function) → str

render a Function object that represents a function call in the IOC startup script

render_pre_ioc_init(instance: Entity) → str | None

render the startup script by combining the jinja template from an entity with the arguments from an Entity

render_post_ioc_init(instance: Entity) → str | None

render the post-iocInit entries by combining the jinja template from an entity with the arguments from an Entity

render_database(instance: Entity) → str | None

render the lines required to instantiate database by combining the templates from the Entity’s database list with the arguments from an Entity

render_environment_variables(instance: Entity) → str | None

render the environment variable elements by combining the jinja template from an entity with the arguments from an Entity

render_elements(ioc: IOC, method: Callable[[Entity], str | None]) → str

Render elements of a given IOC instance based on calling the correct method

render_pre_ioc_init_elements(ioc: IOC) → str

Render all of the startup script entries for a given IOC instance

render_post_ioc_init_elements(ioc: IOC) → str

Render all of the post-iocInit elements for a given IOC instance

render_database_elements(ioc: IOC) → str

Render all of the DBLoadRecords entries for a given IOC instance

render_environment_variable_elements(ioc: IOC) → str

Render all of the environment variable entries for a given IOC instance

ibek.utils

A class containing utility functions for passing into the Jinja context.

This allows us to provide simple functions that can be called inside Jinja templates with {{ __utils__.function_name() }}. It also allows us to maintain state between calls to the Jinja templates because we pass a single instance of this class into all Jinja contexts.

class ibek.utils.Counter(start: int, current: int, stop: int)

Provides the ability to supply unique numbers to Jinja templates

class ibek.utils.Utils

A Utility class for adding functions to the Jinja context

set_var(key: str, value: Any)

create a global variable for our jinja context

get_var(key: str) → Any

get the value a global variable for our jinja context

counter(name: str, start: int = 0, stop: int = 65535, inc: int = 1) → int

get a named counter that increments by inc each time it is called

creates a new counter if it does not yet exist

class apischema.types.UndefinedType

A sentinel value that allows detection that a value has not been passed at init