`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.

settei.base — Basic app object¶

`settei.base` — Basic app object¶