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 defintions

class ibek.globals.T

A generic Type for use in type hints

alias of TypeVar(‘T’)

ibek.globals.desc(description: str)

a description Annotation to add to our Entity derived Types

ibek.support

The Support Class represents a deserialized <MODULE_NAME>.ibek.support.yaml file. It contains a hierarchy of Entity dataclasses.

class ibek.support.Arg(name, description, type, default)

Base class for all Argument Types

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (str) –

• default (Any) –

class ibek.support.FloatArg(name, description, type='float', default=Undefined)

An argument with a float value

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (Literal) –

• default (Union) – If given, and instance doesn’t supply argument, what value should be used

class ibek.support.StrArg(name, description, type='str', default=Undefined)

An argument with a str value

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (Literal) –

• default (Union) – If given, and instance doesn’t supply argument, what value should be used

class ibek.support.IntArg(name, description, type='int', default=Undefined)

An argument with an int value

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (Literal) –

• default (Union) – If given, and instance doesn’t supply argument, what value should be used

class ibek.support.BoolArg(name, description, type='bool', default=Undefined)

An argument with an bool value

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (Literal) –

• default (Union) – If given, and instance doesn’t supply argument, what value should be used

class ibek.support.ObjectArg(name, description, type='object', default=Undefined)

A reference to another entity defined in this IOC

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (Literal) –

• default (Union) – If given, and instance doesn’t supply argument, what value should be used

class ibek.support.IdArg(name, description, type='id', default=Undefined)

Explicit ID argument that an object can refer to

Parameters:

• name (str) – Name of the argument that the IOC instance should pass

• description (str) – Description of what the argument will be used for

• type (Literal) –

• default (Union) – If given, and instance doesn’t supply argument, what value should be used

class ibek.support.Database(file, include_args=(), define_args='')

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

Parameters:

• file (str) – Filename of the database template in <module_root>/db

• include_args (Sequence) – List of args to pass through to database

• define_args (str) – Arg string list to be generated as Jinja template

class ibek.support.EnvironmentVariable(name, value)

An environment variable that should be set in the startup script

Parameters:

• name (str) – Name of environment variable

• value (str) – Value to set

class ibek.support.Function(name, args, header='', once=False, type='function')

A script snippet that defines a function to call

Parameters:

• name (str) – Name of the function to call

• args (Dict) – The arguments IOC instance should supply

• header (str) – commands/comments to appear before the function

• once (bool) – If true, only call the function once

• type (Literal) –

class ibek.support.Once(type='once', value='')

A script snippet that should for the first occurrence only

Parameters:

• type (Literal) –

• value (str) – Startup script snippets defined as Jinja template

class ibek.support.Value(name, description, value)

A calculated string value for a definition

Parameters:

• name (str) – Name of the value that the IOC instance will expose

• description (str) – Description of what the value will be used for

• value (str) – The contents of the value

class ibek.support.Definition(name, description, args=(), values=(), databases=(), script=(), env_vars=(), post_ioc_init=())

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

Parameters:

• name (str) – Publish Definition as type <module>.<name> for IOC instances

• description (str) – Describes the purpose of the definition

• args (Sequence) – The arguments IOC instance should supply

• values (Sequence) – The values IOC instance should supply

• databases (Sequence) – Databases to instantiate

• script (Sequence) – Startup script snippets defined as Jinja template or function

• env_vars (Sequence) – Environment variables to set in the boot script

• post_ioc_init (Sequence) – Entries to add post iocInit(), such as dbpf

class ibek.support.Support(module, defs)

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

Parameters:

• module (str) – Support module name, normally the repo name

• defs (Sequence) – The definitions an IOC can create using this module

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

A baseclass for all generated Entity classes. Provides the deserialize entry point.

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

We can get a set of Definitions by deserializing an ibek support module definition YAML file.

This function then creates an Entity derived class from each Definition.

See Modules, Definitions and Entities

ibek.ioc.make_entity_classes(support: Support) → SimpleNamespace

Create Entity subclasses for all Definition objects in the given Support instance, put them in a namespace in ibek.modules and return it

ibek.ioc.clear_entity_classes()

Reset the modules namespaces, deserializers and caches of defined Entity subclasses

class ibek.ioc.IOC(ioc_name, description, entities, generic_ioc_image)

Used to load an IOC instance entities yaml file into memory using IOC.deserialize(YAML().load(ioc_instance_yaml)).

Parameters:

• ioc_name (str) – Name of IOC instance

• description (str) – Description of what the IOC does

• entities (Sequence) – List of entities this IOC instantiates

• generic_ioc_image (str) – The generic IOC container image registry URL

Before loading the entities file all Entity classes that it contains must be defined in modules.py. This is achieved by deserializing all support module definitions yaml files used by this IOC and calling make_entity_classes(support_module).

ibek.modules

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

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, once=False, 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_script(instance: Entity) → str | None

render the startup script 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_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_elements(ioc: IOC, method: Callable[[Entity], str | None]) → str

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

render_script_elements(ioc: IOC) → str

Render all of the startup script entries 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

render_post_ioc_init_elements(ioc: IOC) → str

Render all of the post-iocInit elements 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