API Reference#

A library for managing and documenting user-supplied configurations

class fica.Config(user_config: Dict[str, Any] = {}, documentation_mode: bool = False, require_valid_keys: bool = False)#

A class defining the structure of configurations expected by an application.

Configuration keys are represented as fields declared in a subclass of this class, whose default values are instances of fica.Key:

class MyConfig(fica.Config):

    foo = fica.Key(description="a value for foo")

When fica creates an instance of your config to document it, it will set documentation_mode to True; this can be useful for disabling any validations in your subclass’s constructor when fica documents it.

Parameters:

  • user_config (dict[str, object]) – a dictionary containing the configurations specified by the user

  • documentation_mode (bool) – indicates that fica is creating an instance with an empty user config to generate the documentation.

  • require_valid_keys (bool) – whether to require that all keys in the user config are valid

get_user_config() → Dict[str, Any]#

Get a user configuration dict that could be used to re-create this config exactly.

Returns a dict mapping keys to their values in this config if the value of the key is different from its default.

Returns:

the user configurations dict

Return type:

dict[str, object]

update(user_config: Dict[str, Any])#

Recursively update the values for keys of this configuration in-place.

Parameters:

user_config (dict[str, object]) – a dictionary of new configuration values

Raises:

  • TypeError – if user_config is of the wrong type or structure

  • Exception – if an error occurs while parsing the specified value for a key

class fica.Key(description: str | None = None, default: Any | None = None, type_: Type | Tuple[Type] | None = None, allow_none: bool = False, validator: _Validator | None = None, subkey_container: Type[Config] | None = None, enforce_subkeys: bool = False, name: str | None = None, factory: Callable[[], Any] | None = None)#

A class representing a key in a configuration.

Keys have a default value, specified with the default argument.

  • If default is fica.EMPTY, then the key is not included in the resulting configuration unless the user specifies a value.

  • If default is fica.SUBKEYS, then the key is defaulted to a dictionary containing each subkey with its default unless the user specifies a value.

  • Otherwise, the key is mapped to the value of default.

If default is fica.EMPTY and subkeys are provided, default is automatically set to fica.SUBKEYS.

To create a new default value for each key value, pass a 0-argument function to factory. This function will be called each time a fica.Config is created to set the value of the key if no value is specified by the user.

Parameters:

  • description (str | None) – a description of the configuration for documentation

  • default (object) – the default value of the key

  • type (type | tuple[type]) – valid type(s) for the value of this configuration

  • allow_none (bool) – whether None is a valid value for the configuration

  • validator (validator or None) – a validator for validating user-specified values

  • subkey_container (subclass of fica.Config) – an (uninstantiated) config class containing the subkeys of this key

  • enforce_subkeys (bool) – whether to enforce the use of the subkey container if any

  • name (str | None) – a name to look for in the user config (if different from the attribute name on the fica.Config object)

  • factory (callable[[], object] | None) – a factory used to create the default value of the key

allow_none: bool#

whether None is a valid value for the configuration

default: Any | None#

the default value of the key

description: str | None#

a description of the configuration for documentation

enforce_subkeys: bool#

whether to enforce the use of the subkey container if any

factory: Callable[[], Any] | None#

a factory used to create the default value

get_default() → Any#

Get the default valu of this key.

If the default is a subkey container instance or a factory function, it is re-instantiated/called, meaning that new instances/return values are returned for each call.

Returns:

the default value of the key.

Return type:

object

get_description() → str | None#

Get the description of the key.

Returns:

the description of the key

Return type:

str | None

get_name(attr_name: str) → str#

Determine the name of this key in the user configuration.

Parameters:

attr_name (str) – the name of the attribute of this key in the fica.Config object

Returns:

the name of the key

Return type:

str

get_subkey_container() → Type[Config] | None#

Get the subkey container class.

Returns:

the uninstantiated subkey container class

Return type:

subclass of fica.Config

get_value(user_value: Any = fica.EMPTY, require_valid_keys: bool = False) → Any#

Get the value of this key taking into account the value specified by the user, if any.

Parameters:

  • user_value (object) – the value specified by the user

  • require_valid_keys (bool) – whether to require that all keys in the user config are valid in the subkey container, if applicable

Returns:

the value of the key, taking into account the user-specified value

Return type:

object

Raises:

  • TypeError – if the user-specified value is not of the correct type

  • ValueError – if the user-specified value fails validation

name: str | None#

the name of this key in the user config (if different from the attribute name)

should_document_subkeys() → bool#

Determine whether this key has subkeys that should be documented.

Returns:

whether this class has subkeys that should be documented

Return type:

bool

subkey_container: Type[Config] | None#

a config class containing the subkeys of this key

type_: Type | Tuple[Type] | None#

valid type(s) for the value of this configuration

use_default(user_value: Any = fica.EMPTY) → bool#

Determine whether the default value for this key will be used given the user-specified value.

Parameters:

user_value (object) – the value specified by the user

Returns:

whether the default value will be used

Return type:

bool

validator: _Validator | None#

a validator for user-specified values

fica.EMPTY = fica.EMPTY#

A singleton object representing an empty value.

fica.SUBKEYS = fica.SUBKEYS#

A singleton object representing that a key’s subkeys should be its default value.

Validators#

User-specified value validators

class fica.validators.choice(choices: List[Any])#

A validator that asserts that a value is one of a pre-defined set of options.

Parameters:

choices (list[object]) – the list of valid options

Raises:

TypeError – if choices is not a list

validate(value: Any) → str | None#

Validate the specified value.

If the value is valid, this method returns None. Otherwise, it returns a string with an error message that is displayed to the user.

Parameters:

value (object) – the value to validate

Returns:

whether the value is valid

Return type:

str | None

class fica.validators.validator(validation_func: Callable[[Any], bool])#

A decorator for custom validation functions.

The decorated function should return None if the value passed to it is valid, otherwise it should return a string with an error message that will be displayed to the user. If the return type of the function is not str | None, a TypeError is raised.

Parameters:

validation_func (callable[[object], bool]) – the validation function

validate(value: Any) → str | None#

Validate the specified value.

If the value is valid, this method returns None. Otherwise, it returns a string with an error message that is displayed to the user.

Parameters:

value (object) – the value to validate

Returns:

whether the value is valid

Return type:

str | None