Configuration

Types

class datagrowth.configuration.types.ConfigurationProperty(namespace: str | list[str] = 'global', private: Sequence[str] | None = None, defaults: dict[str, Any] | None = None, storage_attribute: str | None = None)

Initialize this class to place a configuration property upon another class. The property will be of the ConfigurationType described below.

By default an attribute named _config will get added to the owner class. You can change this by passing a name to the storage_attribute parameter All other parameters get passed to the ConfigurationType class.

Parameters:

• namespace – (string or list[string]) prefix(es) to search default configurations with

• private – (list) keys that are considered as private for this property

• defaults – (dict) should hold default configurations as items or None to load defaults from settings at runtime (the default)

• storage_attribute – (string) name of the attribute used to store configurations on the owner class. By default this is an attribute named _config

Returns:

ConfigurationType

class datagrowth.configuration.types.ConfigurationType(defaults: dict[str, Any] | None = None, namespace: str | list[str] = 'global', private: Sequence[str] = ('_private', '_defaults', '_namespace'))

This type is the interface to configurations. Configurations are accessible as attributes. So a configuration named my_config will be accessible with config.my_config.

You can check if a configuration exists by using the in operator. The defaults get returned when configurations are not explicitly set. There are two types of defaults:

• Any configuration with a prefixes of global will be a default for all configuration properties

• Any configuration with a prefix equal to namespace will be a default for configuration properties that share the namespace

If you for example add my_scoped_config to the defaults. Then configuration properties with the namespace set to my will return the my_scoped_config value if scoped_config is not set.

Parameters:

• defaults – (dict) that should hold default configurations as items or None to load defaults from settings at runtime

• namespace – (string or list[string]) prefix(es) to search default configurations with

• private – (list) keys that are considered as private

Returns:

None

static clean_key(key: str) → str

Strips characters from the input key that have a special meaning to the configuration type. Namely ‘$’ and ‘_’.

Parameters:

key – (string) the key to strip special characters from

Returns:

(string) the original or stripped key

classmethod from_dict(config: dict[str, Any], defaults: dict[str, Any] | None = None) → ConfigurationType

Creates a configuration using a dictionary. The dictionary should hold the appropriate _private and _namespace values. The _private value specifies which configurations should not be passed on to configuration that use this configuration as a base. The _namespace value specifies which prefix should be used to search default configurations, when a key can not be found in the configuration.

Parameters:

• config – (dict) the configuration keys and values to create a configuration with

• defaults – (dict) the configuration keys and values that act as a fallback or None to load defaults from settings at runtime

Returns:

a configuration instance

get(item: str, *args: Any, **kwargs: Any) → Any

Getter for configuration item. When the configuration key is not found it raises a ConfigurationNotFoundError unless default is specified. If this is the case it returns the default instead.

Parameters:

• item – (string) key to get a configuration value for

• default – (mixed) value to return if configuration does not exist

Returns:

(mixed) the configuration value or the default value

items(protected: bool = False, private: bool = False) → Iterator[tuple[str, Any]]

Iterates over all configurations in a (key, value,) manner. It allows to skip over protected and private configurations, which happens by default.

Parameters:

• protected – (boolean) flag to include protected configurations

• private – (boolean) flag to include private configurations

Returns:

supplement(other: dict[str, Any]) → None

This method updates the configuration with keys from other if the configuration key does not exist in the configuration already. This allows configurations to update with only new values.

Parameters:

other – (dict) the configuration keys and values to possibly update the configuration with

Returns:

None

to_dict(protected: bool = False, private: bool = False) → dict[str, Any]

Will return the current configuration in dict form. By default it will return all attributes except those that are considered protected or private. Any configuration whose name starts with an _ is considered protected. Configurations are considered private when they start with _ and are listed as private during initialisation of the configuration property.

Parameters:

• protected – (boolean) flag to include protected configurations

• private – (boolean) flag to include private configurations

Returns:

(dict) current configuration other than default

update(new: dict[str, Any] | None) → None

Will update any configurations given through new. This method sets attributes on itself named after the configurations. Therefore be careful with using _private, _namespace, _defaults and _global_prefix as configurations. They will override attributes that the ConfigurationType needs internally.

Parameters:

new – (dictionary) to update attributes on self with

Returns:

None

datagrowth.configuration.types.create_config(namespace: str, configuration: dict[str, Any]) → ConfigurationType

Use this function to quickly create a configuration. You need to specify under which namespace the configuration should search for defaults. The configuration names and their values need to be supplied as well as a simple dictionary.

Apart from that the configuration needs no setup and the most common use cases will be supported.

Parameters:

• namespace – (str) the namespace under which missing configurations should be searched when defaulting

• values – (dict) the configuration keys and values that should be set on the configuration instance

Returns:

ConfigurationType

datagrowth.configuration.types.register_defaults(namespace: str, configuration: Mapping[str, Any]) → None

This function updates a global configuration defaults object with your own defaults. That way an application can set defaults at runtime during a configure stage like the Django apps ready hook.

You need to specify under which namespace the configuration should become available. This should be the same as the namespace you create configurations with. You can provide the default configuration for that namespace as a simple dictionary.

Parameters:

• namespace – (str) the namespace under which the defaults will be registered.

• configuration – (dict) the configuration keys and values that should be set as defaults

Returns:

None

Fields

class datagrowth.configuration.fields.ConfigurationField(namespace: str = 'global', private: tuple[str, ...] = ('_private', '_namespace', '_defaults'), config_defaults: dict[str, Any] | None = None, *args: Any, **kwargs: Any)

This field creates a property of ConfigurationType on Django models. All values will be saved in the database upon save of a model.

All initialization parameters are optional and act as defaults. By setting CONFIG_NAMESPACE, CONFIG_PRIVATE or CONFIG_DEFAULTS on inheriting classes these defaults get overridden.

The use of config_defaults or CONFIG_DEFAULTS is discouraged. Because setting this value makes it impossible to change the defaults at runtime. If you want to set defaults for a field it’s recommended to use the DATAGROWTH_DEFAULT_CONFIGURATION setting or register_defaults if you want to set defaults at runtime.

Parameters:

• namespace – (string) prefix to search default configurations with if a configuration is missing

• private – (list) keys that are considered as private

• config_defaults – (dict) should hold default configurations as items

• args – additional TextField arguments

• kwargs – additional TextField keyword arguments

contribute_to_class(cls: type, name: str, private_only: bool = False, **kwargs: Any) → None

Register the field with the model class it belongs to.

If private_only is True, create a separate instance of this field for every subclass of cls, even if cls is not an abstract model.

form_class

alias of ConfigurationFormField

formfield(**kwargs: Any) → Any

Return a django.forms.Field instance for this field.

get_prep_value(value: Any) → str

Perform preliminary non-db specific value checks and conversions.

to_python(value: Any) → Any

Convert the input value into the expected Python data type, raising django.core.exceptions.ValidationError if the data can’t be converted. Return the converted value. Subclasses should override this.

value_from_object(obj: Any) → str | None

Return the value of this field in the given model instance.

class datagrowth.configuration.fields.ConfigurationFormField(*, max_length=None, min_length=None, strip=True, empty_value='', **kwargs)

This form field correctly serializes the configuration inside of text area’s when saving an (admin) form.

to_python(value: Any) → Any

Return a string.

Serializers

class datagrowth.configuration.serializers.DecodeConfigAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

This class can be used as action for any argsparse command line option (like Django management command options). It will parse a URL like parameter string into a dictionary. This dictionary can then be used to initialize a configuration.

datagrowth.configuration.serializers.load_config() → Callable[[F], F]

This decorator will turn the value of any keyword arguments named “config” into a ConfigurationType. The decorated function will get the configuration as its first argument.

Returns:

Wrapped function