cinnamon package

Subpackages

• cinnamon.utility package
  • Submodules
  • cinnamon.utility.configuration module
    • batched()
  • cinnamon.utility.exceptions module
    • AlreadyExpandedException
    • AlreadyRegisteredException
    • DisconnectedGraphException
    • InvalidDirectoryException
    • NamespaceNotFoundException
    • NotADAGException
      • NotADAGException.build_edge_view()
    • NotBoundException
    • NotExpandedException
    • NotRegisteredException
    • ValidationFailureException
    • ValidationResult
      • ValidationResult.error_message
      • ValidationResult.passed
      • ValidationResult.source
      • ValidationResult.stack_trace
  • cinnamon.utility.inquirer module
  • cinnamon.utility.registration module
    • NamespaceExtractor
      • NamespaceExtractor.process()
      • NamespaceExtractor.visit_Call()
      • NamespaceExtractor.visit_FunctionDef()
    • import_class_from_string()
    • match_name()
    • match_namespace()
    • match_tags()
  • cinnamon.utility.sanity module
    • check_directory()
    • check_external_json_path()
    • time_it()
  • Module contents

Submodules

cinnamon.command_line module

cinnamon.component module

cinnamon.configuration module

class cinnamon.configuration.Configuration(**data)

Bases: BaseModel

A Configuration specifies the parameters of a Component. Configurations store parameters and allow flow control via conditions.

add_condition(condition, name, description=None, tags=None)

Adds a condition to be validated.

Parameters:

• condition (Callable[[Configuration], bool]) – a function that receives as input the current Configuration instance and returns a boolean.

• name (str) – unique identifier.

• description (Optional[str]) – a string description for readability purposes.

• tags (Optional[Set[str]]) – a set of string tags to mark the condition with metadata.

Raises:

AlreadyExistingParameterException – if the provided name already exists in the Configuration instance.

classmethod default()

Returns the default Configuration instance.

Return type:

TypeVar(C, bound= Configuration)

Returns:

Configuration instance.

property dependencies: Dict[str, RegistrationKey | Configuration]

property expanded: bool

property fields: Dict[str, FieldInfo]

property has_at_least_two_variants: bool

property has_variants: bool

is_dependency(field_name, field)

Return type:

bool

meta: ClassVar[MetaDescriptor] = <cinnamon.configuration.FieldMetaProxy object>

model_config: ClassVar[ConfigDict] = {'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_copy(*, update=None, deep=False)

!!! abstract “Usage Documentation”

[model_copy](../concepts/models.md#model-copy)

Returns a copy of the model.

!!! note

The underlying instance’s [__dict__][object.__dict__] attribute is copied. This might have unexpected side effects if you store anything in it, on top of the model fields (e.g. the value of [cached properties][functools.cached_property]).

Parameters:

• update (Optional[Mapping[str, Any]]) – Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.

• deep (bool) – Set to True to make a deep copy of the model.

Return type:

Self

Returns:

New model instance.

model_post_init(_Configuration__context)

Runs automatically right after Pydantic instantiates an object.

Return type:

None

classmethod retrieve(registration_key=None, name=None, namespace=None, tags=None)

Syntactic sugar for retrieving a Configuration from a

RegistrationKey in implicit format.

Parameters:

• registration_key (cinnamon.registry.Registration | None) – the RegistrationKey used to register the Configuration class.

• name (str | None) – the name field of RegistrationKey

• tags (Tags) – the tags field of RegistrationKey

• namespace (str | None) – the namespace field of RegistrationKey

Return type:

C

Returns:

A Configuration instance

Raises:

• InvalidConfigurationTypeException – if there’s a mismatch between the Configuration class used

• during registration and the type of the built Configuration – instance using the registered

• constructor` method (see ConfigurationInfo arguments) –

validate_conditions(strict=True)

Validates all provided conditions related to the Configuration instance. :rtype: ValidationResult

Args:

strict: if True, a failed validation process will raise

InvalidConfigurationException

Returns:

A ValidationResult that stores the boolean result of the validation

process along with an error message if the result is False.

Raises:

ValidationFailureException: if strict = True and the validation

process failed

validate_variants()

Return type:

TypeVar(C, bound= Configuration)

property values: Dict[str, Any]

property variants: List[Dict[str, Dict[str, Any]]]

Computes all unique combinations of a configuration’s fields along

with their indices.

The baseline/default value always gets index 0. Subsequent unique variants get an increasing index (1, 2, …).

cinnamon.configuration.Param(default=PydanticUndefined, *, description=None, tags=None, variants=None, **kwargs)

Return type:

Any

cinnamon.registry module

class cinnamon.registry.RegistrationKey(name, namespace=None, tags=None, description=None, metadata=None, special_tags=None)

Bases: Generic[T]

Compound key used for registration.

ATTRIBUTE_SEPARATOR: str = '--'

HIERARCHY_SEPARATOR: str = '.'

KEY_VALUE_SEPARATOR: str = '='

MAX_TAGS_PER_LINE: int = 6

check_name(name)

check_namespace(namespace)

check_tags(tags)

property compound_tags

classmethod from_string(string_format)

Parses a RegistrationKey instance from its string format.

Parameters:

string_format (str) – the string format of a RegistrationKey instance.

Return type:

RegistrationKey[Any]

Returns:

The corresponding parsed RegistrationKey instance

from_tags_simplification(tags)

Builds a new RegistrationKey from current instance

by removing provided tags.

Parameters:

tags (Optional[Set[str]]) – a Tag set containing tags to remove

Return type:

RegistrationKey[TypeVar(T)]

Returns:

A RegistrationKey instance that is the same as the current instance

but with tags removed.

from_variant(variant_kwargs, variant_indexes=None)

Return type:

RegistrationKey[TypeVar(T)]

property hierarchy_tags

match(key, tags)

Return type:

bool

classmethod parse(registration_key=None, name=None, namespace=None, tags=None)

Parses a given RegistrationKey instance. If the given registration_key is in its string format, it is converted

to RegistrationKey instance

Parameters:

• registration_key (Union[RegistrationKey, str, None]) – a RegistrationKey instance in its class instance or string format

• name (Optional[str]) – the name field of RegistrationKey

• namespace (Optional[str]) – the namespace field of RegistrationKey

• tags (Optional[Set[str]]) – the tags field of RegistrationKey

Return type:

RegistrationKey[Any]

Returns:

The parsed RegistrationKey instance

sanitize_variant_tag(param_name, param_index, param_value)

Return type:

str

toJSON()

to_pretty_string()

class cinnamon.registry.Registry

Bases: object

The registration registry. The registry has three main functionalities: - Storing/Retrieving registered Configuration: via the ConfigurationInfo

internal wrapper.

• Storing/Retrieving Configuration to Component bindings: the binding

operation allows to build a Component instance from its

registered Configuration.

• Storing/Retrieving registered built Component instances: a Component

instance can be registered as well to mimic Singleton behaviors. This functionality is useful is a single Component instance

is used multiple times in a program.

All the above functionalities require to specify a RegistrationKey

(either directly or indirectly).

REGISTRATION_CONTEXT: RegistrationContext

REGISTRATION_METHODS: Dict[str, Union[Callable, BufferedRegistration]]

classmethod build(cls, directory, external_directories=None)

Main entrypoint of cinnamon. The registry checks provided directories for configurations to populate its

internal registry and build the dependency DAG.

Eventually, the dependency DAG is expanded to account for variants

and invalid configurations.

Parameters:

• directory (Union[Path, AnyStr]) – the main directory of the project containing configurations.

• external_directories (Optional[List[Union[AnyStr, Path]]]) – external directories containing configurations.

Returns:

a ResolutionInfo` containing valid ``RegistrationKey invalid_keys: a ResolutionInfo` containing invalid ``RegistrationKey

Return type:

valid_keys

Raises:

• RuntimeWarning – if duplicate namespaces are found.

• InvalidDirectoryException – if one of the provided directories does not exist or is not a directory.

• AlreadyExpandedException – if the dependency DAG has been expanded.

• NotADAGException – if the dependency DAG is not a DAG.

• DisconnectedGraphException – if, for some reason, the dependency DAG contains disconnected nodes.

• This should never happen via cinnamon APIs, unless some manual intervention – on the dependency DAG is carried out.

classmethod check_registration_graph()

Checks if the dependency DAG is valid.

Raises:

• AlreadyExpandedException – if the dependency DAG has been expanded.

• NotADAGException – if the dependency DAG is not a DAG.

• DisconnectedGraphException – if, for some reason, the dependency DAG contains disconnected nodes.

• This should never happen via cinnamon APIs, unless some manual intervention – on the dependency DAG is carried out.

Return type:

bool

classmethod dag_resolution(cls)

Expands and resolves dependencies in registration DAG. The dependency traversal is done bottom-up by recursively expanding top nodes (i.e., RegistrationKey instances). Expanded keys are retrieved, and built for full validation.

Returns:

the set of valid registration keys invalid_keys:the set of invalid registration keys

Return type:

valid_keys

classmethod expand_configuration(key, valid_key_buffer=None, invalid_key_buffer=None)

Return type:

Set[RegistrationKey[Any]]

expanded: bool = False

classmethod from_key(registration_key, **build_args)

Return type:

TypeVar(T)

classmethod in_graph(registration_key=None, name=None, namespace=None, tags=None)

Return type:

bool

classmethod in_registry(registration_key)

Return type:

bool

classmethod initialize()

classmethod instantiate(registration_key=None, name=None, namespace=None, tags=None, expected_type=None, **build_args)

Builds a Component instance from its bounded Configuration

via the implicit RegistrationKey.

Parameters:

• registration_key (Union[RegistrationKey, str, None]) – the RegistrationKey used to register the Configuration class.

• name (Optional[str]) – the name attribute of RegistrationKey

• tags (Optional[Set[str]]) – the tags attribute of RegistrationKey

• namespace (Optional[str]) – the namespace attribute of RegistrationKey

• expected_type (Optional[type]) – type of the component to be cast

• build_args – additional custom component constructor args

Return type:

Any

Returns:

The built component instance

Raises:

• InvalidConfigurationTypeException – if there’s a mismatch between the Configuration class used during registration and the type of the built Configuration instance using the registered

• constructor` method (see ConfigurationInfo arguments) –

• NotBoundException – if the Configuration is not bound to any component.

classmethod is_namespace_covered(registration_key)

Return type:

bool

classmethod load_registrations(cls, directory)

Imports a Python’s module for registration. The Registry looks for register() and register_method() decorators. These functions are the entry points for registrations: that is, where the

Registry APIs are invoked to issue registrations.

Parameters:

directory (Union[AnyStr, Path]) – path of the module

Raises:

InvalidDirectoryException – if the provided directory is not a directory or does not exist.

classmethod parse_configuration_files(cls, directories)

Runs a static code analyzer to inspect code scripts containing

cinnamon registrations with the goal of determining unique namespaces.

Parameters:

directories (List[Path]) – list of directories containing cinnamon registrations.

Returns:

unique list of namespaces mapping: mapping from namespace to pathlib.Path directories.

Return type:

namespaces

classmethod register_configuration(config, name, namespace, tags=None, component=None, run_method=None)

Registers a Configuration in the registry. In particular, a ConfigurationInfo wrapper is stored in the Registry.

Parameters:

• config (Configuration) – Configuration` instance

• name (str) – the name field of RegistrationKey

• namespace (str) – the namespace field of RegistrationKey

• tags (Optional[Set[str]]) – the tags field of RegistrationKey,

• component (Optional[str]) – Component module path as string

• run_method (Optional[str]) – Component method to run when instantiating the Component as runnable

Returns:

The built RegistrationKey instance that can be used to retrieve

the registered ConfigurationInfo.

Raises:

• NotExpandedException – if the dependency DAG has not been expanded yet.

• AlreadyRegisteredException – if the RegistrationKey is already used

• NamespaceNotFoundException – if one of the dependencies of RegistrationKey belongs to a namespace not covered.

classmethod resolve_configuration(config)

Return type:

Configuration

classmethod resolve_external_directories(cls, external_directories)

Checks if provided directories are valid directories and exist.

Parameters:

external_directories (List[Union[AnyStr, Path]]) – directories to validate.

Returns:

validated directories as pathlib.Path instances

Return type:

resolved_directories

Raises:

InvalidDirectoryException – if any of the provided directories is not a directory or does not exist.

classmethod retrieve_configuration(registration_key=None, name=None, namespace=None, tags=None)

Retrieves a Configuration instance from the registry

via its RegistrationKey.

Parameters:

• registration_key (Union[RegistrationKey, str, None]) – key used to register the configuration

• name (Optional[str]) – the name field of RegistrationKey

• namespace (Optional[str]) – the namespace field of RegistrationKey

• tags (Optional[Set[str]]) – the tags field of RegistrationKey

Returns:

the built configuration instance

Return type:

config

classmethod retrieve_configuration_info(registration_key=None, name=None, namespace=None, tags=None)

Retrieves a Configuration instance from the registry

via its RegistrationKey.

Parameters:

• registration_key (Union[RegistrationKey, str, None]) – key used to register the configuration

• name (Optional[str]) – the name field of RegistrationKey

• namespace (Optional[str]) – the namespace field of RegistrationKey

• tags (Optional[Set[str]]) – the tags field of RegistrationKey

Returns:

the built configuration instance

Return type:

config

classmethod retrieve_keys(names=None, namespaces=None, tags=None, special_tags=None, keys=None)

Retrieves RegistrationKey via given name, tags, namespaces filters. The search can be limited to a fixed set of keys, optionally given in input.

Parameters:

• names (Union[List[str], str, None]) – a name or a list of names to filter registration keys.

• namespaces (Union[List[str], str, None]) – a namespace or a list of namespaces to filter registration keys.

• tags (Optional[Set[str]]) – a tag set to filter registration keys.

• special_tags (Optional[Set[str]]) – a special tag set to filter registration keys.

• keys (Optional[List[RegistrationKey[TypeVar(T)]]]) – an optional list of RegistrationKey on which to apply the search.

Return type:

List[RegistrationKey[Any]]

Returns:

classmethod retrieve_runnable_keys()

Return type:

List[RegistrationKey[Any]]

classmethod update_namespaces(cls, namespaces, module_mapping)

cinnamon.registry.register(func)

Return type:

Callable

cinnamon.registry.register_method(name, namespace, tags=None, component=None, run_method=None)

Return type:

Callable

Module contents