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.
-
class
yapconf.handlers.
FileHandler
(filename, handler, file_type='json')[source]¶ Bases:
watchdog.events.RegexMatchingEventHandler
Watchdog handler that only watches a specific file.
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.
-
-
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.
-
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 otherYapconfItem
types. It provides several basic functions. It helps create CLI arguments to be used byargparse.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
¶ The name of the config value.
Type: str
-
item_type
¶ The type of config value you are expecting.
Type: str
-
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
¶
-
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.
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.
-
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
- specification (dict) – The specification used to
initialize
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.
-
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.
-
class
yapconf.sources.
EnvironmentConfigSource
(label)[source]¶ Bases:
yapconf.sources.DictConfigSource
Special dict config which gets its value from the environment.
-
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 “/”
-
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) –
- data (str) – If provided, will be loaded via
-
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) –
-
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.
- filename (str) – Will be loaded via
-
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 sourcedefinition.
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
¶ All defaults for items in the specification.
Type: dict
-
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 thetarget
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.
- label (str) – Should match a label added through
-
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
¶ All defaults for items in the specification.
Type: dict
-
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 thetarget
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.
- label (str) – Should match a label added through
-
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.
-