satella.configuration.sources package¶
Submodules¶
satella.configuration.sources.base module¶
- class satella.configuration.sources.base.BaseSource¶
Bases:
object
Base class for all configuration sources
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.base.StaticSource(config)¶
Bases:
BaseSource
A static piece of configuration. Returns exactly what is passed
- Parameters:
config (dict) –
- config¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
satella.configuration.sources.derivative module¶
- class satella.configuration.sources.derivative.AlternativeSource(*sources)¶
Bases:
BaseSource
If first source of configuration fails with ConfigurationError, use the next one instead, ad nauseam.
- Ivar:
sources (list[BaseSource]) sources to examine left to right
- Parameters:
sources (BaseSource) –
- provide()¶
- Raises:
ConfigurationError – when backup fails too
- Return type:
dict
- sources: tp.List[BaseSource]¶
- class satella.configuration.sources.derivative.MergingSource(*sources, on_fail=0, fail_if_no_sources_are_correct=True)¶
Bases:
BaseSource
Source that merges configuration from a bunch of sources. The configuration has to be a dictionary!!
- Parameters:
sources (BaseSource) – Sources to examine. Source later in queue will override earlier’s entries, so take care.
on_fail (int) – how to behave when a source fails
fail_if_no_sources_are_correct (bool) – even if on_fail == MergingSource.SILENT, if all sources fail, this will fail as well. Of course this makes sense only if on_fail == MergingSource.SILENT
- RAISE = 0¶
- SILENT = 1¶
- fail_if_no_sources_are_correct¶
- on_fail¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- sources¶
- class satella.configuration.sources.derivative.OptionalSource(source)¶
Bases:
AlternativeSource
This will substitute for empty dict if underlying config would fail.
Apply this to your sources if you expect that they will fail.
Use as
>>> OptionalSource(SomeOtherSource1)
- Parameters:
source (BaseSource) –
- sources: tp.List[BaseSource]¶
satella.configuration.sources.envvars module¶
- class satella.configuration.sources.envvars.EnvVarsSource(env_name)¶
Bases:
JSONSource
Return a dictionary that is the JSON encoded within a particular environment variable
- Parameters:
root (if bytes, will be decoded with given encoding') – content
env_name (str) –
- env_name: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.envvars.EnvironmentSource(env_name, config_name=None, cast_to=None)¶
Bases:
BaseSource
This just returns a dictionary of { env_name => that env’s value }
- Parameters:
env_name (str) – name of the environment variable to check for
config_name (Optional[str]) – name of the env_name in the dictionary to return
cast_to – callable that converts a string to whatever form is desired. Note that this is deprecated. Use schema instead to cast to desired typing.
- cast_to: Callable[[Any], Any]¶
- config_name: str¶
- env_name: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
satella.configuration.sources.file module¶
- class satella.configuration.sources.file.DirectorySource(path, encoding='utf-8', interpret_as=['JSONSource', 'YAMLSource'], fname_filter=<function DirectorySource.<lambda>>, scan_subdirectories=True, on_fail=0)¶
Bases:
FileSource
Load all files from given directory and merge them
- Parameters:
filter – callable that tells whether to use this file (or subdirectory if scan_subdirectories is enabled)
on_fail (int) – what to do in case a resource fails
interpret_as – names or classes of format sources to parse with
encoding (str) –
fname_filter (Callable[[str], bool]) –
scan_subdirectories (bool) –
- RAISE = 0¶
- SILENT = 1¶
- filter: tp.Callable[[tp.List[str]], tp.List[str]]¶
- get_sources_from_directory(directory)¶
- Parameters:
directory (str) –
- Return type:
List[FileSource]
- on_fail: int¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- scan_subdirectories: bool¶
- class satella.configuration.sources.file.FileSource(path, encoding='utf-8', interpret_as=['JSONSource', 'YAMLSource'])¶
Bases:
BaseSource
Try to read a file and parse it with a known format.
- Parameters:
interpret_as (List[Union[Type[FormatSource], str]]) – names or classes of format sources to parse with
path (str) –
encoding (str) –
- encoding: str¶
- path: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- source_classes: tp.List[tp.Type[FormatSource]]¶
- class satella.configuration.sources.file.HTTPJSONSource(url, method='GET', **kwargs)¶
Bases:
BaseSource
Call somwhere, count on a 200-esque code and return a JSON!
- Parameters:
kwargs – these will be passed to requests.request(..)
url (str) –
method (str) –
- kwargs: tp.Dict[str, tp.Any]¶
- method: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- url: str¶
satella.configuration.sources.format module¶
- class satella.configuration.sources.format.FormatSource(root, encoding='utf-8')¶
Bases:
BaseSource
- Parameters:
root (if bytes, will be decoded with given encoding') – content
encoding (str) –
- BASE_EXCEPTIONS = [<class 'TypeError'>, <class 'UnicodeDecodeError'>, <class 'ValueError'>, <class 'binascii.Error'>, <class 'LookupError'>]¶
- EXTRA_EXCEPTIONS = []¶
- TRANSFORM()¶
- encoding: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- root: BaseSource¶
- class satella.configuration.sources.format.JSONSource(root, encoding='utf-8')¶
Bases:
FormatSource
Loads JSON strings
- Parameters:
root (if bytes, will be decoded with given encoding') – content
encoding (str) –
- EXTRA_EXCEPTIONS = [<class 'json.decoder.JSONDecodeError'>]¶
- TRANSFORM(*, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶
Deserialize
s
(astr
,bytes
orbytearray
instance containing a JSON document) to a Python object.object_hook
is an optional function that will be called with the result of any object literal decode (adict
). The return value ofobject_hook
will be used instead of thedict
. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).object_pairs_hook
is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value ofobject_pairs_hook
will be used instead of thedict
. This feature can be used to implement custom decoders. Ifobject_hook
is also defined, theobject_pairs_hook
takes priority.parse_float
, if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).parse_int
, if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).parse_constant
, if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.To use a custom
JSONDecoder
subclass, specify it with thecls
kwarg; otherwiseJSONDecoder
is used.
- encoding: str¶
- root: BaseSource¶
- class satella.configuration.sources.format.YAMLSource(root, encoding='utf-8')¶
Bases:
FormatSource
Loads YAML strings
- Parameters:
root (if bytes, will be decoded with given encoding') – content
encoding (str) –
- EXTRA_EXCEPTIONS = [<class 'yaml.error.YAMLError'>]¶
- TRANSFORM()¶
- encoding: str¶
- root: BaseSource¶
satella.configuration.sources.from_dict module¶
- satella.configuration.sources.from_dict.load_source_from_dict(dct)¶
obj has a form of
- {
“type”: “BaseSource”, “args”: [] # optional … kwargs
}
- Raises:
ConfigurationError – upon failure to instantiate
- Parameters:
dct (dict) –
- Return type:
- satella.configuration.sources.from_dict.load_source_from_list(obj)¶
Builds a MergingSource from dict-ed objects
- Parameters:
obj (list) –
- Return type:
satella.configuration.sources.object_from module¶
- class satella.configuration.sources.object_from.BuildObjectFrom(key, child)¶
Bases:
BaseSource
A source that outputs a single key with given name, and as it’s contents the contents of it’s child.
- Parameters:
key (str) –
child (BaseSource) –
- child¶
- key¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
Module contents¶
- class satella.configuration.sources.AlternativeSource(*sources)¶
Bases:
BaseSource
If first source of configuration fails with ConfigurationError, use the next one instead, ad nauseam.
- Ivar:
sources (list[BaseSource]) sources to examine left to right
- Parameters:
sources (BaseSource) –
- provide()¶
- Raises:
ConfigurationError – when backup fails too
- Return type:
dict
- sources: tp.List[BaseSource]¶
- class satella.configuration.sources.BaseSource¶
Bases:
object
Base class for all configuration sources
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.BuildObjectFrom(key, child)¶
Bases:
BaseSource
A source that outputs a single key with given name, and as it’s contents the contents of it’s child.
- Parameters:
key (str) –
child (BaseSource) –
- child¶
- key¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.DirectorySource(path, encoding='utf-8', interpret_as=['JSONSource', 'YAMLSource'], fname_filter=<function DirectorySource.<lambda>>, scan_subdirectories=True, on_fail=0)¶
Bases:
FileSource
Load all files from given directory and merge them
- Parameters:
filter – callable that tells whether to use this file (or subdirectory if scan_subdirectories is enabled)
on_fail (int) – what to do in case a resource fails
interpret_as – names or classes of format sources to parse with
encoding (str) –
fname_filter (Callable[[str], bool]) –
scan_subdirectories (bool) –
- RAISE = 0¶
- SILENT = 1¶
- filter: tp.Callable[[tp.List[str]], tp.List[str]]¶
- get_sources_from_directory(directory)¶
- Parameters:
directory (str) –
- Return type:
List[FileSource]
- on_fail: int¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- scan_subdirectories: bool¶
- class satella.configuration.sources.EnvVarsSource(env_name)¶
Bases:
JSONSource
Return a dictionary that is the JSON encoded within a particular environment variable
- Parameters:
root (if bytes, will be decoded with given encoding') – content
env_name (str) –
- env_name: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.EnvironmentSource(env_name, config_name=None, cast_to=None)¶
Bases:
BaseSource
This just returns a dictionary of { env_name => that env’s value }
- Parameters:
env_name (str) – name of the environment variable to check for
config_name (str) – name of the env_name in the dictionary to return
cast_to (Callable[[Any], Any]) – callable that converts a string to whatever form is desired. Note that this is deprecated. Use schema instead to cast to desired typing.
- cast_to: Callable[[Any], Any]¶
- config_name: str¶
- env_name: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.FileSource(path, encoding='utf-8', interpret_as=['JSONSource', 'YAMLSource'])¶
Bases:
BaseSource
Try to read a file and parse it with a known format.
- Parameters:
interpret_as (List[Union[Type[FormatSource], str]]) – names or classes of format sources to parse with
path (str) –
encoding (str) –
- encoding: str¶
- path: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- source_classes: tp.List[tp.Type[FormatSource]]¶
- class satella.configuration.sources.FormatSource(root, encoding='utf-8')¶
Bases:
BaseSource
- Parameters:
root (if bytes, will be decoded with given encoding') – content
encoding (str) –
- BASE_EXCEPTIONS = [<class 'TypeError'>, <class 'UnicodeDecodeError'>, <class 'ValueError'>, <class 'binascii.Error'>, <class 'LookupError'>]¶
- EXTRA_EXCEPTIONS = []¶
- TRANSFORM()¶
- encoding: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- root: BaseSource¶
- class satella.configuration.sources.HTTPJSONSource(url, method='GET', **kwargs)¶
Bases:
BaseSource
Call somwhere, count on a 200-esque code and return a JSON!
- Parameters:
kwargs – these will be passed to requests.request(..)
url (str) –
method (str) –
- kwargs: tp.Dict[str, tp.Any]¶
- method: str¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- url: str¶
- class satella.configuration.sources.JSONSource(root, encoding='utf-8')¶
Bases:
FormatSource
Loads JSON strings
- Parameters:
root (if bytes, will be decoded with given encoding') – content
encoding (str) –
- EXTRA_EXCEPTIONS = [<class 'json.decoder.JSONDecodeError'>]¶
- TRANSFORM(*, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶
Deserialize
s
(astr
,bytes
orbytearray
instance containing a JSON document) to a Python object.object_hook
is an optional function that will be called with the result of any object literal decode (adict
). The return value ofobject_hook
will be used instead of thedict
. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).object_pairs_hook
is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value ofobject_pairs_hook
will be used instead of thedict
. This feature can be used to implement custom decoders. Ifobject_hook
is also defined, theobject_pairs_hook
takes priority.parse_float
, if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).parse_int
, if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).parse_constant
, if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.To use a custom
JSONDecoder
subclass, specify it with thecls
kwarg; otherwiseJSONDecoder
is used.
- encoding: str¶
- root: BaseSource¶
- class satella.configuration.sources.MergingSource(*sources, on_fail=0, fail_if_no_sources_are_correct=True)¶
Bases:
BaseSource
Source that merges configuration from a bunch of sources. The configuration has to be a dictionary!!
- Parameters:
sources (BaseSource) – Sources to examine. Source later in queue will override earlier’s entries, so take care.
on_fail (int) – how to behave when a source fails
fail_if_no_sources_are_correct (bool) – even if on_fail == MergingSource.SILENT, if all sources fail, this will fail as well. Of course this makes sense only if on_fail == MergingSource.SILENT
- RAISE = 0¶
- SILENT = 1¶
- fail_if_no_sources_are_correct¶
- on_fail¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- sources¶
- class satella.configuration.sources.OptionalSource(source)¶
Bases:
AlternativeSource
This will substitute for empty dict if underlying config would fail.
Apply this to your sources if you expect that they will fail.
Use as
>>> OptionalSource(SomeOtherSource1)
- Parameters:
source (BaseSource) –
- sources: tp.List[BaseSource]¶
- class satella.configuration.sources.StaticSource(config)¶
Bases:
BaseSource
A static piece of configuration. Returns exactly what is passed
- Parameters:
config (dict) –
- config¶
- provide()¶
Return your configuration, as a dict
- Raises:
ConfigurationError – on invalid configuration
- Return type:
dict
- class satella.configuration.sources.YAMLSource(root, encoding='utf-8')¶
Bases:
FormatSource
Loads YAML strings
- Parameters:
root (if bytes, will be decoded with given encoding') – content
encoding (str) –
- EXTRA_EXCEPTIONS = [<class 'yaml.error.YAMLError'>]¶
- TRANSFORM()¶
- encoding: str¶
- root: BaseSource¶
- satella.configuration.sources.load_source_from_dict(dct)¶
obj has a form of
- {
“type”: “BaseSource”, “args”: [] # optional … kwargs
}
- Raises:
ConfigurationError – upon failure to instantiate
- Parameters:
dct (dict) –
- Return type:
- satella.configuration.sources.load_source_from_list(obj)¶
Builds a MergingSource from dict-ed objects
- Parameters:
obj (list) –
- Return type: