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 (a str, bytes or bytearray 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 (a dict). The return value of object_hook will be used instead of the dict. 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 of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_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 the cls kwarg; otherwise JSONDecoder 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:

BaseSource

satella.configuration.sources.from_dict.load_source_from_list(obj)

Builds a MergingSource from dict-ed objects

Parameters:

obj (list) –

Return type:

MergingSource

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:
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:
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 (a str, bytes or bytearray 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 (a dict). The return value of object_hook will be used instead of the dict. 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 of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_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 the cls kwarg; otherwise JSONDecoder 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:

BaseSource

satella.configuration.sources.load_source_from_list(obj)

Builds a MergingSource from dict-ed objects

Parameters:

obj (list) –

Return type:

MergingSource