settei.base
— Basic app object¶
New in version 0.2.0.
-
exception
settei.base.
ConfigError
¶ The base exception class for errors releated to
Configuration
andconfig_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
andKeyError
.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 raiseConfigKeyError
, a subtype ofKeyError
, instead.-
classmethod
from_file
(file) → settei.base.Configuration¶ Load settings from the given
file
and instantiate anConfiguration
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 anConfiguration
instance from that.Parameters: path ( pathlib.Path
) – the file path that contains TOML settingsReturns: an instantiated configuration Return type: Configuration
-
classmethod
-
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 exampleabc.def
looks upconfig['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 anApp
mapping, and return a default value. cannot be used withdefault
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 whendefault
value is provided
New in version 0.4.0.
New in version 0.5.0: The
recurse
option.- key (
-
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 exampleabc.def
looks upconfig['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 anApp
mapping, and return a default value. cannot be used withdefault
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 whendefault
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 raiseConfigKeyError
, a subtype ofKeyError
, 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 raiseConfigTypeError
instead.ConfigTypeError
is also a subtype ofTypeError
.- key (