settei.base — Basic app object

New in version 0.2.0.

exception settei.base.ConfigError

The base exception class for errors releated to Configuration and config_property().

New in version 0.4.0.

exception settei.base.ConfigKeyError

An exception class rises when there’s no a configuration key. A subtype of ConfigError and KeyError.

New in version 0.4.0.

exception settei.base.ConfigTypeError

An exception class rises when the configured value is not of a type the field expects.

New in version 0.4.0.

class settei.base.Configuration(config: Mapping[str, object] = {}, **kwargs)

Application instance with its settings e.g. database. It implements read-only Mapping protocol as well, so you can treat it as a dictionary of string keys.

Changed in version 0.4.0: Prior to 0.4.0, it had raised Python’s built-in KeyError on missing keys, but since 0.4.0 it became to raise ConfigKeyError, a subtype of KeyError, instead.

classmethod from_file(file) → settei.base.Configuration

Load settings from the given file and instantiate an Configuration instance from that.

Parameters:file – the file object that contains TOML settings
Returns:an instantiated configuration
Return type:Configuration
classmethod from_path(path: pathlib.Path) → Configuration

Load settings from the given path and instantiate an Configuration instance from that.

Parameters:path (pathlib.Path) – the file path that contains TOML settings
Returns:an instantiated configuration
Return type:Configuration
exception settei.base.ConfigValueError

An execption class rises when the configured value is somewhat invalid.

New in version 0.4.0.

exception settei.base.ConfigWarning

Warning category which raised when a default configuration is used instead due to missing required configuration.

class settei.base.config_object_property(key: str, cls, docstring: str = None, recurse: bool = False, **kwargs)

Similar to config_property except it purposes to reprsent more complex objects than simple values. It can be utilized as dependency injector.

Suppose a field declared as:

from werkzeug.contrib.cache import BaseCache

class App(Configuration):
    cache = config_object_property('cache', BaseCache)

Also a configuration:

[cache]
class = "werkzeug.contrib.cache:RedisCache"
host = "a.nodes.redis-cluster.local"
port = 6379
db = 0

The above instantiates the following object:

from werkzeug.contrib.cache import RedisCache
RedisCache(host='a.nodes.redis-cluster.local', port=6380, db=0)

There’s a special field named * which is for positional arguments as well:

[cache]
class = "werkzeug.contrib.cache:RedisCache"
"*" = [
    "a.nodes.redis-cluster.local",
    6379,
]
db = 0

The above configuration is equivalent to the following Python code:

from werkzeug.contrib.cache import RedisCache
RedisCache('a.nodes.redis-cluster.local', 6380, db=0)

By default it doesn’t recursively evaluate. For example, the following configuration:

[field]
class = "a:ClassA"
[field.value]
class = "b:ClassB"
[field.value.value]
class = "c:ClassC"

is evaluated to:

from a import ClassA
ClassA(value={'class': 'b:ClassB', 'value': {'class': 'c:ClassC'}})

If recurse=True option is provided, it evaluates nested tables too:

from a import ClassA
from b import ClassB
from c import ClassC

ClassA(value=ClassB(value=ClassC()))
Parameters:
  • key (str) – the dotted string of key path. for example abc.def looks up config['abc']['def']
  • cls (type) – the allowed type of the configuration
  • docstring (str) – optional documentation about the configuration. it will be set to __doc__ attribute
  • recurse (bool) – whether to evaluate nested tables as well. False by default
  • default – keyword only argument. optional default value used for missing case. cannot be used with default_func at a time
  • default_func (collections.abc.Callable) – keyword only argument. optional callable which returns a default value for missing case. it has to take an App mapping, and return a default value. cannot be used with default at a time
  • default_warning (bool) – keyword only argument. whether to warn when default value is used. does not warn by default. this option is only available when default value is provided

New in version 0.4.0.

New in version 0.5.0: The recurse option.

class settei.base.config_property(key: str, cls, docstring: str = None, **kwargs)

Declare configuration key with type hints, default value, and docstring.

Parameters:
  • key (str) – the dotted string of key path. for example abc.def looks up config['abc']['def']
  • cls (type) – the allowed type of the configuration
  • docstring (str) – optional documentation about the configuration. it will be set to __doc__ attribute
  • default – keyword only argument. optional default value used for missing case. cannot be used with default_func at a time
  • default_func (collections.abc.Callable) – keyword only argument. optional callable which returns a default value for missing case. it has to take an App mapping, and return a default value. cannot be used with default at a time
  • default_warning (bool) – keyword only argument. whether to warn when default value is used. does not warn by default. this option is only available when default value is provided

Changed in version 0.4.0: Prior to 0.4.0, it had raised Python’s built-in KeyError on missing keys, but since 0.4.0 it became to raise ConfigKeyError, a subtype of KeyError, instead.

In the same manner, while prior to 0.4.0, it had raised Python’s built-in TypeError when a configured value is not of a type it expects, but since 0.4.0 it became to raise ConfigTypeError instead. ConfigTypeError is also a subtype of TypeError.

docstring

(str) The propertly indented __doc__ string.