cyra package

cyra.core module

class cyra.core.DictUtil

A few useful functions for handling nested dicts

static iterate(d, fun)

Iterate through a nested dictionary, calling the function fun on every key/value.

Parameters

  • d (Dict) – Nested dictionary

  • fun (Callable[[Any, Any], None]) – Function/Lambda fun(key, value)

Return type

None

static get_element(d, path)

Get element from a nested dictionary

Parameters

  • d (Dict) – Nested dictionary

  • path (Tuple) – Path tuple (for example ('DATABASE', 'server') or ('msg',)

Return type

Any

Returns

element or None

Raises

ValueError – if Path is empty

static set_element(d, path, value, default_dict=None)

Set element in a nested dictionary, creating additional sub-dictionaries if necessary

Parameters

  • d (Dict) – Nested dictionary

  • path (Tuple) – Path tuple (for example ('DATABASE', 'server') or ('msg',)

  • value (Any) – Value to be set

  • default_dict (Optional[Dict]) – Empty dictionary to be created if missing

Raises

  • ValueError – if Path is empty

  • ValueError – if Path is empty

Return type

None

class cyra.core.ConfigEntry(comment='', docstring='')

Base class for config entries (both value-less nodes and ConfigValues). Used as a data element for the config dictionary.

The base class holds comment and docstring.

class cyra.core.ConfigValue(comment='', docstring='', default='', path=(), validator=None, hook=None, strict=False)

Configuration value data element.

Holds config value and handles validation.

class cyra.core.ConfigBuilder

Use the ConfigBuilder to specify your configuration.

define(key, default, validator=None, hook=None, strict=False)

Add a value to your config.

Parameters

  • key (str) – Key for the new value. Must not be empty or contain dots.

  • default (Any) – Default value. Determines the type.

  • validator (Optional[Callable]) – Validation function/lambda. Return true if valid value.

  • hook (Optional[Callable]) – Hook function. Return modified value. Raise exception if invalid value.

  • strict (bool) – Disable auto-casting and fall back to default value if type does not match.

Raises

ValueError – if the key collides with an existing config value/section or the validator does not accept the default value

Return type

ConfigValue

Returns

ConfigValue

comment(comment)

Add a comment to your config. Comment will be applied to the value or section added next.

Parameters

comment (str) – Comment string

Return type

None

docstring(docstring)

Add a docstring to your config.

When generating your documentation using the .. cyradoc:: directive, the config file will be split at this location and the docstring will be inserted.

Parameters

docstring (str) – Docstring

Return type

None

push(key)

Add a section to your config. Use pop() to exit the section.

Parameters

key (str) – Key for the new section. Must not be empty or contain dots.

Raises

ValueError – if the key collides with an existing config value

Return type

None

pop(n=1)

Exit a config section created by push().

Parameters

n (int) – Number of sections to exit (default: 1)

Raises

ValueError – if attempted to pop

Return type

None

build()

Return a copy of the built config dict

Return type

OrderedDict

Returns

Built config

class cyra.core.Config(file='config.toml', cfg_builder=None)

Cyra configuration class

builder = <cyra.core.ConfigBuilder object>
load_toml(toml_str)

Import config values from a TOML string

Parameters

toml_str (str) – TOML string

Return type

None

load_flat_dict(flat_dict)

Import config values from a flat dictionary.

Parameters

flat_dict (Dict) – Flat dictionary. Keys are either tuples or strings with dots as separators.

Return type

None

export_toml()

Export the configuration as a toml-formatted string. Styling and comments of the imported toml file are preserved

Return type

str

Returns

TOML string

load_file(update=True)

Load the configuration from the file.

Parameters

update (bool) – If set to true, config values missing in the file will be added automatically with their default values and comments.

Return type

None

save_file(force=False)

If modified, save the configuration to disk.

Parameters

force (bool) – Force save, even if not modified.

Return type

bool

Returns

True if saved successfully.

get_docblocks()

Output the config data blockwise with the respective docstrings.

Return type

List[Tuple[str, str]]

Returns

List of tuples: (Docstring, TOML string)

cyra.cyradoc module

class cyra.cyradoc.CyradocDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
required_arguments = 1

Number of required directive arguments.

option_spec = {'no-docstrings': <function flag>}

Mapping of option names to validator functions.

run()
Return type

List[Node]

cyra.cyradoc.setup(app)
Return type

None