Using Aumbry
============

Dependencies
------------
Many developers are very conscious of the number of dependencies that they
include in their projects. To that end, Aumbry doesn't install the dependencies
for parsing yaml or loading from consul by default. However, Aumbry attempts
to make this relatively easy on users by enabling users to easily install
the extra dependencies using the following convention:

.. code-block:: bash

    # For Consul dependencies
    pip install aumbry['consul']

    # For Etcd2 dependencies
    pip install aumbry['etcd2']

    # For Yaml dependencies
    pip install aumbry['yaml']

    # For Parameter Store dependencies
    pip install aumbry['param_store']

    # For Fernet File dependencies
    pip install aumbry['fernet']

    # Installing multiple dependencies
    pip install aumbry['etcd2','yaml']


Loading from a File
-------------------
One of the simplest and most common way of loading configuration is from a
file. For this example, we'll use a JSON configuration file.

Lets say we have the following JSON configuration that we want to load

.. code-block:: json

    {
        "something": "it works!"
    }


The next steps are to define a configuration class that matches what we're
trying to do and load the config up.

.. code-block:: python

    import aumbry


    class SampleConfig(aumbry.JsonConfig):
        __mapping__ = {
            'something': aumbry.Attr('something', str),
        }


    # You can either specify the options here or via environment variables
    options = {
        'CONFIG_FILE_PATH': './my_config.json',
    }

    # Time to load it up!
    config = aumbry.load(aumbry.FILE, SampleConfig, options)

    print(config.something) # it works!

File Options
^^^^^^^^^^^^^^
Like all options, these can be manually specified when calling ``load()``
or via environment variables.

===================== ========== ============================
       Key             Default   Notes
===================== ========== ============================
CONFIG_FILE_PATH                  Required
===================== ========== ============================

Encryption
^^^^^^^^^^
Encryption and decryption support is provided by using pyca/cryptography's
Fernet module. Installing the required dependencies can be done with:

.. code-block:: shell

    pip install aumbry['fernet']

The usage is nearly identical to a standard file; however, the source type
and options change slightly. The source type becomes ``aumbry.FERNET`` and
you need to provide the ``CONFIG_FILE_FERNET_KEY`` option.


Loading from Consul
-------------------

As mentioned under the Dependencies section, the dependencies to load from
consul are not included by default. As a result, we need to first install
our extra dependencies.

.. code-block:: shell

    pip install aumbry['consul']

Much like our loading from a file example, we need a configuration class and
set our options for the Consul source.

.. code-block:: python

    import aumbry


    class SampleConfig(aumbry.JsonConfig):
        __mapping__ = {
            'something': aumbry.Attr('something', str),
        }


    # You can either specify the options here or via environment variables
    options = {
        'CONSUL_URI': 'http://myhost:8500',
        'CONSUL_KEY': 'test',
    }

    # Time to load it up!
    config = aumbry.load(aumbry.CONSUL, SampleConfig, options)

    print(config.something) # it works!

It is important to note that the Consul source will block until it either
cannot load, reaches max retries, or successfully loads.

Consul Options
^^^^^^^^^^^^^^
Like all options, these can be manually specified when calling ``load()``
or via environment variables.

===================== ========== ============================
       Key             Default   Notes
===================== ========== ============================
CONSUL_URI                       Required
CONSUL_KEY                       Required
CONSUL_TIMEOUT            10     Timeout per-request
CONSUL_RETRY_MAX           1     Number of retries to attempt
CONSUL_RETRY_INTERVAL     10     Wait period between retries
===================== ========== ============================

Loading from Etcd2
------------------

As mentioned under the Dependencies section, the dependencies to load from
etcd2 are not included by default. As a result, we need to first install
our extra dependencies.

.. code-block:: shell

    pip install aumbry['etcd2']

Much like our loading from a file example, we need a configuration class and
set our options for the Etcd2 source.

.. code-block:: python

    import aumbry


    class SampleConfig(aumbry.JsonConfig):
        __mapping__ = {
            'something': aumbry.Attr('something', str),
        }


    # You can either specify the options here or via environment variables
    options = {
        'ETCD2_URI': 'http://myhost:8500',
        'ETCD2_KEY': 'test',
    }

    # Time to load it up!
    config = aumbry.load(aumbry.ETCD2, SampleConfig, options)

    print(config.something) # it works!

It is important to note that the Etcd2 source will block until it either
cannot load, reaches max retries, or successfully loads.

Etcd2 Options
^^^^^^^^^^^^^
Like all options, these can be manually specified when calling ``load()``
or via environment variables.

===================== ========== ============================
       Key             Default   Notes
===================== ========== ============================
ETCD2_URI                        Required
ETCD2_KEY                        Required
ETCD2_TIMEOUT             10     Timeout per-request
ETCD2_RETRY_MAX            1     Number of retries to attempt
ETCD2_RETRY_INTERVAL      10     Wait period between retries
===================== ========== ============================

Loading from AWS Parameter Store
--------------------------------

As mentioned under the Dependencies section, the dependencies to load from
the parameter store are not included by default. As a result, we need to
first install our extra dependencies.

.. code-block:: shell

    pip install aumbry['param_store']

To use the parameter store functionality, we need to use the generic
configuration class or force the usage of the generic handler on ``load()``
and ``save()``.

.. code-block:: python

    import aumbry


    class SampleConfig(aumbry.GenericConfig):
        __mapping__ = {
            'something': aumbry.Attr('something', str),
        }


    # You can either specify the options here or via environment variables
    options = {
        'PARAMETER_STORE_AWS_REGION': 'us-west-2',
        'PARAMETER_STORE_PREFIX': '/prod/my_app',
    }

    # Time to load it up!
    config = aumbry.load(aumbry.PARAM_STORE, SampleConfig, options)

    print(config.something) # it works!

.. note::

    If you need to mix configuration types, such as using a ``YamlConfig``,
    you'll need to tell Aumbry to attempt to coerce the configuration using
    the :class:`aumbry.formats.generic.GenericHandler` when calling
    :meth:`aumbry.load` and :meth:`aumbry.save`.

Parameter Store Options
^^^^^^^^^^^^^^^^^^^^^^^
Like all options, these can be manually specified when calling ``load()``
or via environment variables.

=================================== =============== ============================
       Key                           Default        Notes
=================================== =============== ============================
PARAMETER_STORE_AWS_REGION                          Required
PARAMETER_STORE_PREFIX                              Required
PARAMETER_STORE_AWS_ACCESS_ID                       If empty, the default machine credentials are used
PARAMETER_STORE_AWS_ACCESS_SECRET                   If empty, the default machine credentials are used
PARAMETER_STORE_AWS_SESSION_TOKEN                   If empty, the default machine credentials are used
PARAMETER_STORE_AWS_KMS_KEY_ID      Account Default
=================================== =============== ============================

Building Configuration Models
-----------------------------
Because Aumbry uses Alchemize_ for model de/serialization, it's just a matter
of defining out the models in the Alchemize method.

Example Yaml Configuration

.. code-block:: yaml

    ---
    base-uri: http://localhost
    database:
      servers:
        - localhost:5432
      username: postgres
      password: something
      name: app

Example Code Load and Parse that config

.. code-block:: python

    import aumbry
    from aumbry import Attr


    class DatabaseConfig(aumbry.YamlConfig):
        __mapping__ = {
            'servers': Attr('servers', list),
            'username': Attr('username', str),
            'password': Attr('password', str),
            'database': Attr('database', str),
        }


    class AppConfig(aumbry.YamlConfig):
        __mapping__ = {
            'base-uri': Attr('base_uri', str),
            'database': Attr('database', DatabaseConfig),
        }


    cfg = aumbry.load(
        aumbry.FILE,
        AppConfig,
        {
            'CONFIG_FILE_PATH': '/etc/app/config.yml'
        }
    )

    print(cfg.database.username) # postgres

One of the things you might have noticed is that the explicit mapping allows
for us to take an attribute name such as ``base-uri`` which isn't compatible
with Python, and map it over to ``base_uri``.

More details can be found on building your mappings in the Alchemize_
documentation.

.. _Alchemize: https://alchemize.readthedocs.io/en/latest/