bsb.config package

Subpackages

• bsb.config.parsers package
  • Module contents
    • ConfigurationParser
      • ConfigurationParser.generate()
      • ConfigurationParser.parse()
    • ParsesReferences
    • get_configuration_parser()

Submodules

bsb.config.refs module

This module contains shorthand reference definitions. References are used in the configuration module to point to other locations in the Configuration object.

Minimally a reference is a function that takes the configuration root and the current node as arguments, and returns another node in the configuration object:

def some_reference(root, here):
    return root.other.place

More advanced usage of references will include custom reference errors.

class bsb.config.refs.Reference

Bases: object

up(here, to=None)

bsb.config.types module

class bsb.config.types.PackageRequirement

Bases: TypeHandler

class bsb.config.types.TypeHandler

Bases: ABC

Base class for any type handler that cannot be described as a single function.

Declare the __call__(self, value) method to convert the given value to the desired type, raising a TypeError if it failed in an expected manner.

Declare the __name__(self) method to return a name for the type handler to display in messages to the user such as errors.

Declare the optional __inv__ method to invert the given value back to its original value, the type of the original value will usually be lost but the type of the returned value can still serve as a suggestion.

class bsb.config.types.WeakInverter(*args, **kwargs)

Bases: object

store_value(value, result)

bsb.config.types.any_()

class bsb.config.types.class_(module_path=None)

Bases: object_

Type validator. Attempts to import the value as the name of a class, relative to the module_path entries, absolute or just returning it if it is already a class.

Parameters:

module_path (list[str]) – List of the modules that should be searched when doing a relative import.

Raises:

TypeError when value can’t be cast.

Returns:

Type validator function

Return type:

Callable

class bsb.config.types.deg_to_radian

Bases: TypeHandler

Type validator. Type casts the value from degrees to radians.

bsb.config.types.dict(type=<class 'str'>)

Type validator for dicts. Type casts each element to the given type.

Parameters:

type (Callable) – Type validator of the elements.

Returns:

Type validator function

Return type:

Callable

class bsb.config.types.distribution

Bases: TypeHandler

Type validator. Type casts the value or node to a distribution.

class bsb.config.types.evaluation

Bases: TypeHandler

Type validator. Provides a structured way to evaluate a python statement from the config. The evaluation context provides numpy as np.

Returns:

Type validator function

Return type:

Callable

get_original(value)

Return the original configuration node associated with the given evaluated value.

Parameters:

value (Any) – A value that was produced by this type handler.

Raises:

NoneReferenceError when value is None, InvalidReferenceError when there is no config associated to the object id of this value.

bsb.config.types.float(min=None, max=None)

Type validator. Attempts to cast the value to an float, optionally within some bounds.

Parameters:

• min (float) – Minimum valid value

• max (float) – Maximum valid value

Returns:

Type validator function

Raises:

TypeError when value can’t be cast.

Return type:

Callable

bsb.config.types.fraction()

Type validator. Type casts the value into a rational number between 0 and 1 (inclusive).

Returns:

Type validator function

Return type:

Callable

class bsb.config.types.function_(module_path=None)

Bases: object_

Type validator. Attempts to import the value, absolute, or relative to the module_path entries, and verifies that it is callable.

Parameters:

module_path (list[str]) – List of the modules that should be searched when doing a relative import.

Raises:

TypeError when value can’t be cast.

Returns:

Type validator function

Return type:

Callable

bsb.config.types.in_(container)

Type validator. Checks whether the given value occurs in the given container. Uses the in operator.

Parameters:

container (list) – List of possible values

Returns:

Type validator function

Return type:

Callable

bsb.config.types.in_classmap()

Type validator. Checks whether the given string occurs in the class map of a dynamic node.

Returns:

Type validator function

Return type:

Callable

bsb.config.types.int(min=None, max=None)

Type validator. Attempts to cast the value to an int, optionally within some bounds.

Parameters:

• min (int) – Minimum valid value

• max (int) – Maximum valid value

Returns:

Type validator function

Raises:

TypeError when value can’t be cast.

Return type:

Callable

bsb.config.types.key()

Type handler for keys in configuration trees. Keys can be either int indices of a config list, or string keys of a config dict.

Returns:

Type validator function

Return type:

Callable

bsb.config.types.list(type=<class 'str'>, size=None)

Type validator for lists. Type casts each element to the given type and optionally validates the length of the list.

Parameters:

• type (Callable) – Type validator of the elements.

• size (int) – Mandatory length of the list.

Returns:

Type validator function

Return type:

Callable

bsb.config.types.list_or_scalar(scalar_type, size=None)

Type validator that accepts a scalar or list of said scalars.

Parameters:

• scalar_type (type) – Type of the scalar

• size (int) – Expand the scalar to an array of a fixed size.

Returns:

Type validator function

Return type:

Callable

class bsb.config.types.method(class_name)

Bases: function_

class bsb.config.types.method_shortcut(class_name)

Bases: method, function_

bsb.config.types.mut_excl(*mutuals, required=True, max=1, shortform=False)

Requirement handler for mutually exclusive attributes.

Parameters:

• mutuals (str) – The keys of the mutually exclusive attributes.

• required (bool) – Whether at least one of the keys is required

• max (int) – The maximum amount of keys that may occur together.

• shortform (bool) – Allow the short form alternative.

Returns:

Requirement function

Return type:

Callable

class bsb.config.types.ndarray(shape: tuple[int, ...] | None = None, dtype=None)

Bases: TypeHandler

Type validator numpy arrays.

Returns:

Type validator function

Return type:

Callable

Parameters:

• shape (tuple[int, ...]) – shape of the array, optional.

• dtype – data-type, optional

bsb.config.types.none()

bsb.config.types.number(min=None, max=None)

Type validator. If the given value is an int returns an int, tries to cast to float otherwise

Parameters:

• min (float) – Minimum valid value

• max (float) – Maximum valid value

Returns:

Type validator function

Raises:

TypeError when value can’t be cast.

Return type:

Callable

class bsb.config.types.object_(module_path=None)

Bases: TypeHandler

Type validator. Attempts to import the value, absolute, or relative to the module_path entries.

Parameters:

module_path (list[str]) – List of the modules that should be searched when doing a relative import.

Raises:

TypeError when value can’t be cast.

Returns:

Type validator function

Return type:

Callable

bsb.config.types.or_(*type_args)

Type validator. Attempts to cast the value to any of the given types in order.

Parameters:

type_args (Callable) – Another type validator

Returns:

Type validator function

Raises:

TypeError if none of the given type validators can cast the value.

Return type:

Callable

bsb.config.types.scalar_expand(scalar_type, size=None, expand=None)

Create a method that expands a scalar into an array with a specific size or uses an expansion function.

Parameters:

• scalar_type (type) – Type of the scalar

• size (int) – Expand the scalar to an array of a fixed size.

• expand (Callable) – A function that takes the scalar value as argument and returns the expanded form.

Returns:

Type validator function

Return type:

Callable

bsb.config.types.shortform()

bsb.config.types.str(strip=False, lower=False, upper=False, safe=True)

Type validator. Attempts to cast the value to a str, optionally with some sanitation.

Parameters:

• strip (bool) – Trim whitespaces

• lower (bool) – Convert value to lowercase

• upper (bool) – Convert value to uppercase

• safe (bool) – If False, checks that the type of value is string before cast.

Returns:

Type validator function

Raises:

TypeError when value can’t be cast.

Return type:

Callable

bsb.config.types.voxel_size()

Module contents

bsb.config module

Contains the dynamic attribute system; Use @bsb.config.root/node/dynamic/pluggable to decorate your classes and add class attributes using x = config.attr/dict/list/ref/reflist to populate your classes with powerful attributes.

class bsb.config.Configuration(*args, _parent=None, _key=None, **kwargs)

The main Configuration object containing the full definition of a scaffold model.

classmethod default(**kwargs)

class bsb.config.ConfigurationAttribute(type=None, default=None, call_default=None, required=False, key=False, unset=False, hint=<object object>)

Bases: object

Base implementation of all the different configuration attributes. Call the factory function attr() instead.

flag_dirty(instance)

flag_pristine(instance)

fset(instance, value)

get_default()

get_hint()

get_node_name(instance)

get_type()

is_dirty(instance)

is_node_type()

should_call_default()

tree(instance)

tree_of(value)

class bsb.config.Distribution(*args, _parent=None, _key=None, **kwargs)

Bases: object

distribution: str

Base implementation of all the different configuration attributes. Call the factory function attr() instead.

draw(n)

get_node_name()

parameters: dict[str, Any]

scaffold: Scaffold

bsb.config.after(hook, cls, essential=False)

Register a class hook to run after the target method.

Parameters:

• hook (str) – Name of the method to hook.

• cls (type) – Class to hook.

• essential (bool) – If the hook is essential, it will always be executed even in child classes that override the hook. Essential hooks are only lost if the method on cls is replaced.

bsb.config.attr(**kwargs)

Create a configuration attribute.

Only works when used inside a class decorated with the node, dynamic, root or pluggable decorators.

Parameters:

• type (Callable) – Type of the attribute’s value.

• required (bool) – Should an error be thrown if the attribute is not present?

• default (Any) – Default value.

• call_default (bool) – Should the default value be used (False) or called (True). Use this to prevent mutable default values.

• key – If set, the key of the parent is stored on this attribute.

bsb.config.before(hook, cls, essential=False)

Register a class hook to run before the target method.

Parameters:

• hook (str) – Name of the method to hook.

• cls (type) – Class to hook.

• essential (bool) – If the hook is essential, it will always be executed even in child classes that override the hook. Essential hooks are only lost if the method on cls is replaced.

bsb.config.catch_all(**kwargs)

Catches any unknown key with a value that can be cast to the given type and collects them under the attribute name.

bsb.config.compose_nodes(*node_classes)

Create a composite mixin class of the given classes. Inherit from the returned class to inherit from more than one node class.

bsb.config.copy_configuration_template(template, output='network_configuration.json', path=None)

bsb.config.dict(**kwargs)

Create a configuration attribute that holds a key value pairs of configuration values. Best used only for configuration nodes. Use an attr() in combination with a types.dict type for simple values.

bsb.config.dynamic(node_cls=None, attr_name='cls', classmap=None, auto_classmap=False, classmap_entry=None, **kwargs)

Decorate a class to be castable to a dynamically configurable class using a class configuration attribute.

Example: Register a required string attribute class (this is the default):

@dynamic
class Example:
    pass

Example: Register a string attribute type with a default value ‘pkg.DefaultClass’ as dynamic attribute:

@dynamic(attr_name='type', required=False, default='pkg.DefaultClass')
class Example:
    pass

Parameters:

• attr_name (str) – Name under which to register the class attribute in the node.

• kwargs – All keyword arguments are passed to the constructor of the attribute.

bsb.config.file(**kwargs)

Create a file dependency attribute.

bsb.config.format_configuration_content(parser_name: str, config: Configuration, **kwargs)

Convert a configuration object to a string using the given parser.

Parameters:

• parser_name (str)

• config (Configuration)

bsb.config.get_config_attributes(cls)

bsb.config.get_config_path()

bsb.config.has_hook(instance, hook)

Checks the existence of a method or essential method on the instance.

Parameters:

• instance (object) – Object to inspect.

• hook (str) – Name of the hook to look for.

bsb.config.list(**kwargs)

Create a configuration attribute that holds a list of configuration values. Best used only for configuration nodes. Use an attr() in combination with a types.list type for simple values.

bsb.config.make_configuration_diagram(config)

bsb.config.node(node_cls, root=False, dynamic=False, pluggable=False)

Decorate a class as a configuration node.

bsb.config.on(hook, cls, essential=False, before=False)

Register a class hook.

Parameters:

• hook (str) – Name of the method to hook.

• cls (type) – Class to hook.

• essential (bool) – If the hook is essential, it will always be executed even in child classes that override the hook. Essential hooks are only lost if the method on cls is replaced.

• before (bool) – If before the hook is executed before the method, otherwise afterwards.

bsb.config.parse_configuration_content(content, parser=None, path=None, **kwargs)

bsb.config.parse_configuration_file(file, parser=None, path=None, **kwargs)

bsb.config.pluggable(key, plugin_name=None)

Create a node whose configuration is defined by a plugin.

Example: If you want to use the attr to chose from all the installed dbbs_scaffold.my_plugin plugins:

@pluggable('attr', 'my_plugin')
class PluginNode:
    pass

This will then read attr, load the plugin and configure the node from the node class specified by the plugin.

Parameters:

plugin_name (str) – The name of the category of the plugin endpoint

bsb.config.property(val=None, /, type=None, **kwargs)

Create a configuration property attribute. You may provide a value or a callable. Call setter on the return value as you would with a regular property.

bsb.config.provide(value)

Provide a value for a parent class’ attribute. Can be a value or a callable, a readonly configuration property will be created from it either way.

bsb.config.ref(reference, **kwargs)

Create a configuration reference.

Configuration references are attributes that transform their value into the value of another node or value in the document:

{
  "keys": {
      "a": 3,
      "b": 5
  },
  "simple_ref": "a"
}

With simple_ref = config.ref(lambda root, here: here["keys"]) the value a will be looked up in the configuration object (after all values have been cast) at the location specified by the callable first argument.

bsb.config.reflist(reference, **kwargs)

Create a configuration reference list.

bsb.config.root(root_cls)

Decorate a class as a configuration root node.

bsb.config.run_hook(obj, hook, *args, **kwargs)

Execute the hook hook of obj.

Runs the hook method obj but also looks through the class hierarchy for essential hooks with the name __<hook>__.

Note

Essential hooks are only ran if the method is called using run_hook while non-essential hooks are wrapped around the method and will always be executed when the method is called (see https://github.com/dbbs-lab/bsb/issues/158).

bsb.config.slot(**kwargs)

Create an attribute slot that is required to be overriden by child or plugin classes.

bsb.config.unset()

Override and unset an inherited configuration attribute.

bsb.config.walk_node_attributes(node)

Walk over all of the child configuration nodes and attributes of node.

Returns:

attribute, node, parents

Return type:

Tuple[ConfigurationAttribute, Any, Tuple]

bsb.config.walk_nodes(node)

Walk over all of the child configuration nodes of node.

Returns:

node generator

Return type:

Any

Dev

class bsb.config._config.NetworkNode(*args, _parent=None, _key=None, **kwargs)

class bsb.config._attrs.cfgdict

Extension of the builtin dictionary to manipulate dicts of configuration nodes.

class bsb.config._attrs.cfglist(iterable=(), /)

Extension of the builtin list to manipulate lists of configuration nodes.