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.support

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

ibek.support.default(T: type)

defines a default type which may be

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.EnumArg(*, type: Literal['enum'] = 'enum', name: str, description: str, default: Any | None = None, values: Dict[str, Any])

An argument with an enum value

class ibek.support.Database(*, file: str, args: Mapping[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.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.EntityPVI(*, yaml_path: str, index: bool = True, prefix: str, pva_template: bool = False)

Entity PVI definition

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

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.EnumVal(value)

An enum that is printed as its name only

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

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, entities: Sequence[Entity])

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

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_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_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_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_file_name(file: Path)

Set the ioc name based on the file name of the instance definition

set_ioc_name(name: str)

Set the ioc name based on the file name of the instance definition

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

render(context: Any, template_text: str) → str

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

class apischema.types.UndefinedType

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