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.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.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.items module

class yapconf.items.YapconfBoolItem(name, item_type='bool', default=None, env_name=None, description=None, required=True, cli_short_name=None, cli_choices=None, previous_names=None, previous_defaults=None, children=None, cli_expose=True, separator='.', prefix=None, bootstrap=False, format_cli=True, format_env=True, env_prefix=None, apply_env_prefix=True, choices=None, alt_env_names=None)[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, item_type='dict', default=None, env_name=None, description=None, required=True, cli_short_name=None, cli_choices=None, previous_names=None, previous_defaults=None, children=None, cli_expose=True, separator='.', prefix=None, bootstrap=False, format_cli=True, format_env=True, env_prefix=None, apply_env_prefix=True, choices=None, alt_env_names=None)[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)[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.

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, item_type='str', default=None, env_name=None, description=None, required=True, cli_short_name=None, cli_choices=None, previous_names=None, previous_defaults=None, children=None, cli_expose=True, separator='.', prefix=None, bootstrap=False, format_cli=True, format_env=True, env_prefix=None, apply_env_prefix=True, choices=None, alt_env_names=None)[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.

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
convert_config_value(value, label)[source]
get_config_value(overrides)[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.

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, item_type='list', default=None, env_name=None, description=None, required=True, cli_short_name=None, cli_choices=None, previous_names=None, previous_defaults=None, children=None, cli_expose=True, separator='.', prefix=None, bootstrap=False, format_cli=True, format_env=True, env_prefix=None, apply_env_prefix=True, choices=None, alt_env_names=None)[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)[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.

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

dict – All defaults for items in the specification.

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.
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)[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
Returns:

The newly migrated configuration.

Return type:

box.Box

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

dict – All defaults for items in the specification.

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.
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)[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
Returns:

The newly migrated configuration.

Return type:

box.Box

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.