yapconf package

Submodules

yapconf.actions module

class yapconf.actions.AppendBoolean(option_strings, dest, const, default=None, required=False, help=None, metavar=None)[source]

Bases: argparse.Action

Action used for appending boolean values on the command-line

class yapconf.actions.AppendReplace(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: argparse.Action

argparse.Action used for appending values on the command-line

class yapconf.actions.MergeAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, child_action=None, separator='.', child_const=None)[source]

Bases: argparse.Action

Merges command-line values into a single dictionary based on separator.

Each MergeAction has a child_action that indicates what should happen for each value. It uses the separator to determine the eventual location for each of its values.

The dest is split up by separator and each string is in turn used to determine the key that should be used to store this value in the dictionary that will get created.

child_action

The action that determines which value is stored

child_const

For booleans, this is the value used

separator

A separator to split up keys in the dictionary

yapconf.docs module

yapconf.docs.build_markdown_table(headers, rows, row_keys=None)[source]

Build a lined up markdown table.

Parameters:
  • headers (dict) – A key -> value pairing fo the headers.
  • rows (list) – List of dictionaries that contain all the keys listed in
  • headers. (the) –
  • row_keys (list) – A sorted list of keys to display
Returns:

A valid Markdown Table as a string.

yapconf.docs.generate_markdown_doc(app_name, spec)[source]

Generate Markdown Documentation for the given spec/app name.

Parameters:
  • app_name (str) – The name of the application.
  • spec (YapconfSpec) – A yapconf specification with sources loaded.
Returns (str):
A valid, markdown string representation of the documentation for the given specification.

yapconf.exceptions module

yapconf.exceptions

This module contains the set of Yapconf’s exceptions.

exception yapconf.exceptions.YapconfDictItemError[source]

Bases: yapconf.exceptions.YapconfItemError

There was an error creating a YapconfDictItem from the specification

exception yapconf.exceptions.YapconfError[source]

Bases: Exception

There was an error while handling your config

exception yapconf.exceptions.YapconfItemError[source]

Bases: yapconf.exceptions.YapconfError

There was an error creating a YapconfItem from the specification

exception yapconf.exceptions.YapconfItemNotFound(message, item)[source]

Bases: yapconf.exceptions.YapconfItemError

We searched through all the overrides and could not find the item

exception yapconf.exceptions.YapconfListItemError[source]

Bases: yapconf.exceptions.YapconfItemError

There was an error creating a YapconfListItem from the specification

exception yapconf.exceptions.YapconfLoadError[source]

Bases: yapconf.exceptions.YapconfError

There was an error while trying to load the overrides provided

exception yapconf.exceptions.YapconfSourceError[source]

Bases: yapconf.exceptions.YapconfError

Error occurred attempting to validate or load a config source.

exception yapconf.exceptions.YapconfSpecError[source]

Bases: yapconf.exceptions.YapconfError

There was an error detected in the specification provided

exception yapconf.exceptions.YapconfValueError[source]

Bases: yapconf.exceptions.YapconfItemError

We found an item in the overrides but it wasn’t what we expected

yapconf.handlers module

class yapconf.handlers.ConfigChangeHandler(current_config, spec, user_handler=None)[source]

Bases: object

Handles config changes.

Expects a watcher to call it when a particular config changes.

handle_config_change(new_config)[source]

Handle the new configuration.

Parameters:new_config (dict) – The new configuration
class yapconf.handlers.FileHandler(filename, handler, file_type='json')[source]

Bases: watchdog.events.RegexMatchingEventHandler

Watchdog handler that only watches a specific file.

on_deleted(event)[source]

Called when a file or directory is deleted.

Parameters:event (DirDeletedEvent or FileDeletedEvent) – Event representing file/directory deletion.
on_modified(event)[source]

Called when a file or directory is modified.

Parameters:event (DirModifiedEvent or FileModifiedEvent) – Event representing file/directory modification.

yapconf.items module

class yapconf.items.YapconfBoolItem(name, **kwargs)[source]

Bases: yapconf.items.YapconfItem

A YapconfItem specifically for Boolean behavior

FALSY_VALUES = ('n', 'no', 'f', 'false', '0', 0, False)
TRUTHY_VALUES = ('y', 'yes', 't', 'true', '1', 1, True)
add_argument(parser, bootstrap=False)[source]

Add boolean item as an argument to the given parser.

An exclusive group is created on the parser, which will add a boolean-style command line argument to the parser.

Examples

A non-nested boolean value with the name ‘debug’ will result in a command-line argument like the following:

‘–debug/–no-debug’

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add this item to.
  • bootstrap (bool) – Flag to indicate whether you only want to mark this item as required or not.
convert_config_value(value, label)[source]

Converts all ‘Truthy’ values to True and ‘Falsy’ values to False.

Parameters:
  • value – Value to convert
  • label – Label of the config which this item was found.

Returns:

class yapconf.items.YapconfDictItem(name, **kwargs)[source]

Bases: yapconf.items.YapconfItem

A YapconfItem for capture dict-specific behavior

add_argument(parser, bootstrap=False)[source]

Add dict-style item as an argument to the given parser.

The dict item will take all the nested items in the dictionary and namespace them with the dict name, adding each child item as their own CLI argument.

Examples

A non-nested dict item with the name ‘db’ and children named ‘port’ and ‘host’ will result in the following being valid CLI args:

[‘–db-host’, ‘localhost’, ‘–db-port’, ‘1234’]

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add this item to.
  • bootstrap (bool) – Flag to indicate whether you only want to mark this item as required or not.
convert_config_value(value, label)[source]
get_config_value(overrides, skip_environment=False)[source]

Get the configuration value from all overrides.

Iterates over all overrides given to see if a value can be pulled out from them. It will convert each of these values to ensure they are the correct type.

Parameters:
  • overrides – A list of tuples where each tuple is a label and a dictionary representing a configuration.
  • skip_environment – Skip looking through the environment.
Returns:

The converted configuration value.

Raises:
  • YapconfItemNotFound – If an item is required but could not be found in the configuration.
  • YapconfItemError – If a possible value was found but the type cannot be determined.
  • YapconfValueError – If a possible value is found but during conversion, an exception was raised.
migrate_config(current_config, config_to_migrate, always_update, update_defaults)[source]

Migrate config value in current_config, updating config_to_migrate.

Given the current_config object, it will attempt to find a value based on all the names given. If no name could be found, then it will simply set the value to the default.

If a value is found and is in the list of previous_defaults, it will either update or keep the old value based on if update_defaults is set.

If a non-default value is set it will either keep this value or update it based on if always_update is true.

Parameters:
  • current_config (dict) – Current configuration.
  • config_to_migrate (dict) – Config to update.
  • always_update (bool) – Always update value.
  • update_defaults (bool) – Update values found in previous_defaults
class yapconf.items.YapconfItem(name, **kwargs)[source]

Bases: object

A simple configuration item for interacting with configurations.

A YapconfItem represent the following types: (str, int, long, float, complex). It also acts as the base class for the other YapconfItem types. It provides several basic functions. It helps create CLI arguments to be used by argparse.ArgumentParser. It also makes getting a particular configuration value simple.

In general this class is expected to be used by the YapconfSpec class to help manage your configuration.

name

str – The name of the config value.

item_type

str – The type of config value you are expecting.

default

The default value if no configuration value can be found.

env_name

The name to search in the environment.

description

The description of your configuration item.

required

Whether or not the item is required to be present.

cli_short_name

A short name (1-character) to identify your item on the command-line.

cli_choices

A list of possible choices on the command-line.

previous_names

A list of names that used to identify this item. This is useful for config migrations.

previous_defaults

A list of previous default values given to this item. Again, useful for config migrations.

children

Any children of this item. Not used by this base class.

cli_expose

A flag to indicate if the item should be exposed from the command-line. It is possible for this value to be overwritten based on whether or not this item is part of a nested list.

separator

A separator used to split apart parent names in the prefix.

prefix

A delimited list of parent names

bootstrap

A flag to determine if this item is required for bootstrapping the rest of your configuration.

format_cli

A flag to determine if we should format the command-line arguments to be kebab-case.

format_env

A flag to determine if environment variables will be all upper-case SNAKE_CASE.

env_prefix

The env_prefix to apply to the environment name.

apply_env_prefix

Apply the env_prefix even if the environment name was set manually. Setting format_env to false will override this behavior.

choices

A list of valid choices for the item.

alt_env_names

A list of alternate environment names.

validator

A custom validation method, should take 1 argument.

fallback

The fully-qualified name from which to pull a value.

watch_target

The method to call when this config value changes.

Raises:YapconfItemError – If any of the information given during initialization results in an invalid item.
add_argument(parser, bootstrap=False)[source]

Add this item as an argument to the given parser.

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add this item to.
  • bootstrap – Flag to indicate whether you only want to mark this item as required or not
all_env_names
cli_names
convert_config_value(value, label)[source]
get_config_value(overrides, skip_environment=False)[source]

Get the configuration value from all overrides.

Iterates over all overrides given to see if a value can be pulled out from them. It will convert each of these values to ensure they are the correct type.

Parameters:
  • overrides – A list of tuples where each tuple is a label and a dictionary representing a configuration.
  • skip_environment – Skip looking through the environment.
Returns:

The converted configuration value.

Raises:
  • YapconfItemNotFound – If an item is required but could not be found in the configuration.
  • YapconfItemError – If a possible value was found but the type cannot be determined.
  • YapconfValueError – If a possible value is found but during conversion, an exception was raised.
migrate_config(current_config, config_to_migrate, always_update, update_defaults)[source]

Migrate config value in current_config, updating config_to_migrate.

Given the current_config object, it will attempt to find a value based on all the names given. If no name could be found, then it will simply set the value to the default.

If a value is found and is in the list of previous_defaults, it will either update or keep the old value based on if update_defaults is set.

If a non-default value is set it will either keep this value or update it based on if always_update is true.

Parameters:
  • current_config (dict) – Current configuration.
  • config_to_migrate (dict) – Config to update.
  • always_update (bool) – Always update value.
  • update_defaults (bool) – Update values found in previous_defaults
update_default(new_default, respect_none=False)[source]

Update our current default with the new_default.

Parameters:
  • new_default – New default to set.
  • respect_none – Flag to determine if None is a valid value.
class yapconf.items.YapconfListItem(name, **kwargs)[source]

Bases: yapconf.items.YapconfItem

A YapconfItem for capture list-specific behavior

add_argument(parser, bootstrap=False)[source]

Add list-style item as an argument to the given parser.

Generally speaking, this works mostly like the normal append action, but there are special rules for boolean cases. See the AppendReplace action for more details.

Examples

A non-nested list value with the name ‘values’ and a child name of ‘value’ will result in a command-line argument that will correctly handle arguments like the following:

[‘–value’, ‘VALUE1’, ‘–value’, ‘VALUE2’]

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add this item to.
  • bootstrap (bool) – Flag to indicate whether you only want to mark this item as required or not.
convert_config_value(value, label)[source]
get_config_value(overrides, skip_environment=True)[source]

Get the configuration value from all overrides.

Iterates over all overrides given to see if a value can be pulled out from them. It will convert each of these values to ensure they are the correct type.

Parameters:
  • overrides – A list of tuples where each tuple is a label and a dictionary representing a configuration.
  • skip_environment – Skip looking through the environment.
Returns:

The converted configuration value.

Raises:
  • YapconfItemNotFound – If an item is required but could not be found in the configuration.
  • YapconfItemError – If a possible value was found but the type cannot be determined.
  • YapconfValueError – If a possible value is found but during conversion, an exception was raised.
yapconf.items.from_specification(specification, env_prefix=None, separator='.', parent_names=None)[source]

Used to create YapconfItems from a specification dictionary.

Parameters:
  • specification (dict) – The specification used to initialize YapconfSpec
  • env_prefix (str) – Prefix to add to environment names
  • separator (str) – Separator for nested items
  • parent_names (list) – Parents names of any given item
Returns:

A dictionary of names to YapconfItems

yapconf.sources module

class yapconf.sources.ConfigSource(label)[source]

Bases: object

Base class for a configuration source.

Config sources will be used to generate overrides during configuration loading. In later iteration, it will also be used to migrate configs based on the configuration type.

The act of loading configurations/migrating those configurations and especially watching those configuration is complicated enough to warrant its own data structure.

label

The label for this config source.

generate_override(separator='.')[source]

Generate an override.

Uses get_data which is expected to be implemented by each child class.

Returns:A tuple of label, dict
Raises:YapconfLoadError – If a known error occurs.
get_data()[source]
validate()[source]

Validate that this ConfigSource can be used.

watch(handler, eternal=False)[source]

Watch a source for changes. When changes occur, call the handler.

By default, watches a dictionary that is in memory.

Parameters:
  • handler – Must respond to handle_config_change
  • eternal – Spawn eternal watch, or just a single watch.
Returns:

The daemon thread that was spawned.

class yapconf.sources.DictConfigSource(label, data)[source]

Bases: yapconf.sources.ConfigSource

A basic config source with just a dictionary as the data.

Keyword Arguments:
 data (dict) – A dictionary that represents the data.
get_data()[source]
validate()[source]

Validate that this ConfigSource can be used.

class yapconf.sources.EnvironmentConfigSource(label)[source]

Bases: yapconf.sources.DictConfigSource

Special dict config which gets its value from the environment.

get_data()[source]
class yapconf.sources.EtcdConfigSource(label, client, key='/')[source]

Bases: yapconf.sources.ConfigSource

Etcd config source (requires python-etcd package).

If your keys have ‘/’s in them, you’re going to have a bad time.

Keyword Arguments:
 
  • client – An etcd client from the python-etcd package.
  • key (str) – The key to fetch in etcd. Defaults to “/”
get_data()[source]
validate()[source]

Validate that this ConfigSource can be used.

class yapconf.sources.JsonConfigSource(label, data=None, filename=None, **kwargs)[source]

Bases: yapconf.sources.ConfigSource

JSON Config source.

Needs either a filename or data keyword arg to work.

Keyword Arguments:
 
  • data (str) – If provided, will be loaded via json.loads
  • filename (str) – If provided, will be loaded via yapconf.load_file
  • kwargs – All other keyword arguments will be provided as keyword args
  • the load calls above. (to) –
get_data()[source]
validate()[source]

Validate that this ConfigSource can be used.

class yapconf.sources.KubernetesConfigSource(label, client, name, **kwargs)[source]

Bases: yapconf.sources.ConfigSource

A kubernetes config data source.

This is meant to load things directly from the kubernetes API. Specifically, it can load things from config maps.

Keyword Arguments:
 
  • client – A kubernetes client from the kubernetes package.
  • name (str) – The name of the ConfigMap to load.
  • namespace (str) – The namespace for the ConfigMap
  • key (str) – A key for the given ConfigMap data object.
  • config_type (str) – Used in conjunction with ‘key’, if ‘key’ points to
  • data blob, this will specify whether to use json or yaml to load (a) –
  • file. (the) –
get_data()[source]
validate()[source]

Validate that this ConfigSource can be used.

class yapconf.sources.YamlConfigSource(label, filename, **kwargs)[source]

Bases: yapconf.sources.ConfigSource

YAML Config source.

Needs a filename to work.

Keyword Arguments:
 
  • filename (str) – Will be loaded via yapconf.load_file
  • encoding (str) – The encoding of the filename.
get_data()[source]
validate()[source]

Validate that this ConfigSource can be used.

yapconf.sources.get_source(label, source_type, **kwargs)[source]

Get a config source based on type and keyword args.

This is meant to be used internally by the spec via add_source.

Parameters:
  • label (str) – The label for this source.
  • source_type – The type of source. See yapconf.SUPPORTED_SOURCES
Keyword Arguments:
 
  • keyword arguments are based on the source_type. Please see the (The) –
  • of the individual sources for a detailed list of all (documentation) –
  • arguments. (possible) –
Returns (yapconf.sources.ConfigSource):
A valid config source which can be used for generating an override.
Raises:
  • YapconfSourceError – If there is some kind of error with this source
  • definition.

yapconf.spec module

class yapconf.spec.YapconfSpec(specification, file_type='json', env_prefix=None, encoding='utf-8', separator='.')[source]

Bases: object

Object which holds your configuration’s specification.

The YapconfSpec item is the main interface into the yapconf package. It will help you load, migrate, update and add arguments for your application.

Examples

>>> from yapconf import YapconfSpec

First define a specification

>>> my_spec = YapconfSpec(
...   {"foo": {"type": "str", "default": "bar"}},
...   env_prefix='MY_APP_'
... )

Then load the configuration in whatever order you want! load_config will automatically look for the ‘foo’ value in ‘/path/to/config.yml’, then the environment, finally falling back to the default if it was not found elsewhere

>>> config = my_spec.load_config('/path/to/config.yml', 'ENVIRONMENT')
>>> print(config.foo)
>>> print(config['foo'])
add_arguments(parser, bootstrap=False)[source]

Adds all items to the parser passed in.

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add all items to.
  • bootstrap (bool) – Flag to indicate whether you only want to mark bootstrapped items as required on the command-line.
add_source(label, source_type, **kwargs)[source]

Add a source to the spec.

Sources should have a unique label. This will help tracing where your configurations are coming from if you turn up the log-level.

The keyword arguments are significant. Different sources require different keyword arguments. Required keys for each source_type are listed below, for a detailed list of all possible arguments, see the individual source’s documentation.

source_type: dict
required keyword arguments:
  • data - A dictionary
source_type: environment
No required keyword arguments.
source_type: etcd
required keyword arguments:
  • client - A client from the python-etcd package.
source_type: json
required keyword arguments:
  • filename - A JSON file.
  • data - A string representation of JSON
source_type: kubernetes
required keyword arguments:
  • client - A client from the kubernetes package
  • name - The name of the ConfigMap to load
source_type: yaml
required keyword arguments:
  • filename - A YAML file.
Parameters:
  • label (str) – A label for the source.
  • source_type (str) – A source type, available source types depend
  • the packages installed. See yapconf.ALL_SUPPORTED_SOURCES (on) –
  • a complete list. (for) –
defaults

dict – All defaults for items in the specification.

find_item(fq_name)[source]

Find an item in the specification by fully qualified name.

Parameters:fq_name (str) – Fully-qualified name of the item.
Returns:The item if it is in the specification. None otherwise
generate_documentation(app_name, **kwargs)[source]

Generate documentation for this specification.

Documentation is generated in Markdown format. An example of the generated documentation can be found at:

https://github.com/loganasherjones/yapconf/blob/master/example/doc.md

Parameters:

app_name (str) – The name of your application.

Keyword Arguments:
 
  • output_file_name (str) – If provided, will write to this file.
  • encoding (str) – The encoding to use for the output file. Default
  • utf-8. (is) –
Returns:

A string representation of the documentation.

get_item(name, bootstrap=False)[source]

Get a particular item in the specification.

Parameters:
  • name (str) – The name of the item to retrieve.
  • bootstrap (bool) – Only search bootstrap items
Returns (YapconfItem):
A YapconfItem if it is found, None otherwise.
items
load_config(*args, **kwargs)[source]

Load a config based on the arguments passed in.

The order of arguments passed in as *args is significant. It indicates the order of precedence used to load configuration values. Each argument can be a string, dictionary or a tuple. There is a special case string called ‘ENVIRONMENT’, otherwise it will attempt to load the filename passed in as a string.

By default, if a string is provided, it will attempt to load the file based on the file_type passed in on initialization. If you want to load a mixture of json and yaml files, you can specify them as the 3rd part of a tuple.

Examples

You can load configurations in any of the following ways:

>>> my_spec = YapconfSpec({'foo': {'type': 'str'}})
>>> my_spec.load_config('/path/to/file')
>>> my_spec.load_config({'foo': 'bar'})
>>> my_spec.load_config('ENVIRONMENT')
>>> my_spec.load_config(('label', {'foo': 'bar'}))
>>> my_spec.load_config(('label', '/path/to/file.yaml', 'yaml'))
>>> my_spec.load_config(('label', '/path/to/file.json', 'json'))

You can of course combine each of these and the order will be held correctly.

Parameters:
  • *args
  • **kwargs – The only supported keyword argument is ‘bootstrap’ which will indicate that only bootstrap configurations should be loaded.
Returns:

A Box object which is subclassed from dict. It should

behave exactly as a dictionary. This object is guaranteed to contain at least all of your required configuration items.

Return type:

box.Box

Raises:
  • YapconfLoadError – If we attempt to load your args and something goes wrong.
  • YapconfItemNotFound – If an item is required but could not be found in the configuration.
  • YapconfItemError – If a possible value was found but the type cannot be determined.
  • YapconfValueError – If a possible value is found but during conversion, an exception was raised.
migrate_config_file(config_file_path, always_update=False, current_file_type=None, output_file_name=None, output_file_type=None, create=True, update_defaults=True, dump_kwargs=None, include_bootstrap=True)[source]

Migrates a configuration file.

This is used to help you update your configurations throughout the lifetime of your application. It is probably best explained through example.

Examples

Assume we have a JSON config file (‘/path/to/config.json’) like the following: {"db_name": "test_db_name", "db_host": "1.2.3.4"}

>>> spec = YapconfSpec({
...    'db_name': {
...        'type': 'str',
...        'default': 'new_default',
...        'previous_defaults': ['test_db_name']
...    },
...    'db_host': {
...        'type': 'str',
...        'previous_defaults': ['localhost']
...    }
... })

We can migrate that file quite easily with the spec object:

>>> spec.migrate_config_file('/path/to/config.json')

Will result in /path/to/config.json being overwritten: {"db_name": "new_default", "db_host": "1.2.3.4"}

Parameters:
  • config_file_path (str) – The path to your current config
  • always_update (bool) – Always update values (even to None)
  • current_file_type (str) – Defaults to self._file_type
  • output_file_name (str) – Defaults to the current_file_path
  • output_file_type (str) – Defaults to self._file_type
  • create (bool) – Create the file if it doesn’t exist (otherwise error if the file does not exist).
  • update_defaults (bool) – Update values that have a value set to something listed in the previous_defaults
  • dump_kwargs (dict) – A key-value pair that will be passed to dump
  • include_bootstrap (bool) – Include bootstrap items in the output
Returns:

The newly migrated configuration.

Return type:

box.Box

sources
spawn_watcher(label, target=None, eternal=False)[source]

Spawns a config watcher in a separate daemon thread.

If a particular config value changes, and the item has a watch_target defined, then that method will be called.

If a target is passed in, then it will call the target anytime the config changes.

Parameters:
  • label (str) – Should match a label added through add_source
  • target (func) – Should be a function that takes two arguments,
  • old configuration and the new configuration. (the) –
  • eternal (bool) – Determines if watcher threads should be restarted
  • they die. (if) –
Returns:

The thread that was spawned.

update_defaults(new_defaults, respect_none=False)[source]

Update items defaults to the values in the new_defaults dict.

Parameters:
  • new_defaults (dict) – A key-value pair of new defaults to be applied.
  • respect_none (bool) – Flag to indicate if None values should constitute an update to the default.

Module contents

Top-level package for Yapconf.

class yapconf.YapconfSpec(specification, file_type='json', env_prefix=None, encoding='utf-8', separator='.')[source]

Bases: object

Object which holds your configuration’s specification.

The YapconfSpec item is the main interface into the yapconf package. It will help you load, migrate, update and add arguments for your application.

Examples

>>> from yapconf import YapconfSpec

First define a specification

>>> my_spec = YapconfSpec(
...   {"foo": {"type": "str", "default": "bar"}},
...   env_prefix='MY_APP_'
... )

Then load the configuration in whatever order you want! load_config will automatically look for the ‘foo’ value in ‘/path/to/config.yml’, then the environment, finally falling back to the default if it was not found elsewhere

>>> config = my_spec.load_config('/path/to/config.yml', 'ENVIRONMENT')
>>> print(config.foo)
>>> print(config['foo'])
add_arguments(parser, bootstrap=False)[source]

Adds all items to the parser passed in.

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add all items to.
  • bootstrap (bool) – Flag to indicate whether you only want to mark bootstrapped items as required on the command-line.
add_source(label, source_type, **kwargs)[source]

Add a source to the spec.

Sources should have a unique label. This will help tracing where your configurations are coming from if you turn up the log-level.

The keyword arguments are significant. Different sources require different keyword arguments. Required keys for each source_type are listed below, for a detailed list of all possible arguments, see the individual source’s documentation.

source_type: dict
required keyword arguments:
  • data - A dictionary
source_type: environment
No required keyword arguments.
source_type: etcd
required keyword arguments:
  • client - A client from the python-etcd package.
source_type: json
required keyword arguments:
  • filename - A JSON file.
  • data - A string representation of JSON
source_type: kubernetes
required keyword arguments:
  • client - A client from the kubernetes package
  • name - The name of the ConfigMap to load
source_type: yaml
required keyword arguments:
  • filename - A YAML file.
Parameters:
  • label (str) – A label for the source.
  • source_type (str) – A source type, available source types depend
  • the packages installed. See yapconf.ALL_SUPPORTED_SOURCES (on) –
  • a complete list. (for) –
defaults

dict – All defaults for items in the specification.

find_item(fq_name)[source]

Find an item in the specification by fully qualified name.

Parameters:fq_name (str) – Fully-qualified name of the item.
Returns:The item if it is in the specification. None otherwise
generate_documentation(app_name, **kwargs)[source]

Generate documentation for this specification.

Documentation is generated in Markdown format. An example of the generated documentation can be found at:

https://github.com/loganasherjones/yapconf/blob/master/example/doc.md

Parameters:

app_name (str) – The name of your application.

Keyword Arguments:
 
  • output_file_name (str) – If provided, will write to this file.
  • encoding (str) – The encoding to use for the output file. Default
  • utf-8. (is) –
Returns:

A string representation of the documentation.

get_item(name, bootstrap=False)[source]

Get a particular item in the specification.

Parameters:
  • name (str) – The name of the item to retrieve.
  • bootstrap (bool) – Only search bootstrap items
Returns (YapconfItem):
A YapconfItem if it is found, None otherwise.
items
load_config(*args, **kwargs)[source]

Load a config based on the arguments passed in.

The order of arguments passed in as *args is significant. It indicates the order of precedence used to load configuration values. Each argument can be a string, dictionary or a tuple. There is a special case string called ‘ENVIRONMENT’, otherwise it will attempt to load the filename passed in as a string.

By default, if a string is provided, it will attempt to load the file based on the file_type passed in on initialization. If you want to load a mixture of json and yaml files, you can specify them as the 3rd part of a tuple.

Examples

You can load configurations in any of the following ways:

>>> my_spec = YapconfSpec({'foo': {'type': 'str'}})
>>> my_spec.load_config('/path/to/file')
>>> my_spec.load_config({'foo': 'bar'})
>>> my_spec.load_config('ENVIRONMENT')
>>> my_spec.load_config(('label', {'foo': 'bar'}))
>>> my_spec.load_config(('label', '/path/to/file.yaml', 'yaml'))
>>> my_spec.load_config(('label', '/path/to/file.json', 'json'))

You can of course combine each of these and the order will be held correctly.

Parameters:
  • *args
  • **kwargs – The only supported keyword argument is ‘bootstrap’ which will indicate that only bootstrap configurations should be loaded.
Returns:

A Box object which is subclassed from dict. It should

behave exactly as a dictionary. This object is guaranteed to contain at least all of your required configuration items.

Return type:

box.Box

Raises:
  • YapconfLoadError – If we attempt to load your args and something goes wrong.
  • YapconfItemNotFound – If an item is required but could not be found in the configuration.
  • YapconfItemError – If a possible value was found but the type cannot be determined.
  • YapconfValueError – If a possible value is found but during conversion, an exception was raised.
migrate_config_file(config_file_path, always_update=False, current_file_type=None, output_file_name=None, output_file_type=None, create=True, update_defaults=True, dump_kwargs=None, include_bootstrap=True)[source]

Migrates a configuration file.

This is used to help you update your configurations throughout the lifetime of your application. It is probably best explained through example.

Examples

Assume we have a JSON config file (‘/path/to/config.json’) like the following: {"db_name": "test_db_name", "db_host": "1.2.3.4"}

>>> spec = YapconfSpec({
...    'db_name': {
...        'type': 'str',
...        'default': 'new_default',
...        'previous_defaults': ['test_db_name']
...    },
...    'db_host': {
...        'type': 'str',
...        'previous_defaults': ['localhost']
...    }
... })

We can migrate that file quite easily with the spec object:

>>> spec.migrate_config_file('/path/to/config.json')

Will result in /path/to/config.json being overwritten: {"db_name": "new_default", "db_host": "1.2.3.4"}

Parameters:
  • config_file_path (str) – The path to your current config
  • always_update (bool) – Always update values (even to None)
  • current_file_type (str) – Defaults to self._file_type
  • output_file_name (str) – Defaults to the current_file_path
  • output_file_type (str) – Defaults to self._file_type
  • create (bool) – Create the file if it doesn’t exist (otherwise error if the file does not exist).
  • update_defaults (bool) – Update values that have a value set to something listed in the previous_defaults
  • dump_kwargs (dict) – A key-value pair that will be passed to dump
  • include_bootstrap (bool) – Include bootstrap items in the output
Returns:

The newly migrated configuration.

Return type:

box.Box

sources
spawn_watcher(label, target=None, eternal=False)[source]

Spawns a config watcher in a separate daemon thread.

If a particular config value changes, and the item has a watch_target defined, then that method will be called.

If a target is passed in, then it will call the target anytime the config changes.

Parameters:
  • label (str) – Should match a label added through add_source
  • target (func) – Should be a function that takes two arguments,
  • old configuration and the new configuration. (the) –
  • eternal (bool) – Determines if watcher threads should be restarted
  • they die. (if) –
Returns:

The thread that was spawned.

update_defaults(new_defaults, respect_none=False)[source]

Update items defaults to the values in the new_defaults dict.

Parameters:
  • new_defaults (dict) – A key-value pair of new defaults to be applied.
  • respect_none (bool) – Flag to indicate if None values should constitute an update to the default.