Metadata-Version: 2.0
Name: climatecontrol
Version: 0.7
Summary: Python library for loading app configurations from files and/or namespaced environment variables
Home-page: https://github.com/daviskirk/climatecontrol
Author: Davis Kirkendall
Author-email: davis.e.kirkendall@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Keywords: climatecontrol
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: typing

|Build Status| |Coverage Status| |PyPi Status|


CLIMATECONTROL
==============

CLIMATECONTROL controls your apps configuration environment. It is a Python
library for loading app configurations from files and/or namespaced environment
variables.


Install
-------

::

    pip install climatecontrol



Usage
-----

Set some environment variables in your shell

.. code:: sh

   export MY_APP_VALUE1=test1
   export MY_APP_VALUE2=test2

Then use them in your python modules:

.. code:: python

   from climatecontrol.settings_parser import Settings
   settings_map = Settings(prefix='MY_APP')
   print(dict(settings_map))

   {
       'value1': 'test1',
       'value2': 'test2'
   }

In case you want to update your settings or your environment variables have
changed and you want to reload them, the `update` method will reload your
settings:

.. code:: python

   import os
   os.environ['MY_APP_VALUE3'] = 'new_env_data'
   settings_map.update()
   print(dict(settings_map))

   {
       'value1': 'test1',
       'value2': 'test2',
       'value3': 'new_env_data'
   }


Now you've noticed that you want more complex configurations and need nested
settings. For this situation we can delimit sections using a double underscore:

.. code:: sh

   export MY_APP_SECTION1__VALUE1=test1
   export MY_APP_SECTION2__VALUE2=test2
   export MY_APP_SECTION2__VALUE3=test3
   export MY_APP_SECTION2__SUB_SECTION__VALUE4=test4

.. code:: python

   settings_map = Settings(prefix='MY_APP')
   print(dict(settings_map))

   {
       'section1': {
           'value1': 'test1'
       },
       'section2': {
           'value2': 'test2',
           'value3': 'test3',
           'sub_section': {
               'value4': 'test4'
           }
       }
   }


Finally if you decide that your settings are simpler and you know that your
section names do not have underscores, you can use the ``implicit_depth``
option, which allows you to add a new section at every single underscore (up to
the depth you specify).

.. code:: sh

   export MY_APP_SECTION1_VALUE1=test1
   export MY_APP_SECTION2_VALUE2=test2
   export MY_APP_SECTION2_VALUE3=test3
   export MY_APP_SECTION2_SUBSECTION_VALUE4=test4

.. code:: python

   settings_map = Settings(prefix='MY_APP', implicit_depth=2)
   print(dict(settings_map))

   {
       'section1': {
           'value1': 'test1'
       },
       'section2': {
           'value2': 'test2',
           'value3': 'test3',
           'subsection': {
               'value4': 'test4'
           }
       }
   }


Settings file support
---------------------

If you don't want to use an environment variable for every single setting and
want to put your settings in a single file instead you can to this as well.
Settings files can be toml_ files (`.toml`), yaml files (`.yml`) or json files (`.json`).

.. code:: sh

   export MY_APP_SETTINGS_FILE=./my_settings_file.toml


The file could look like this:

.. code::

   [section1]
   subsection1 = "test1"

   [section2]
   subsection2 = "test2"
   subsection3 = "test3"


Setting variables whos values are saved in files
------------------------------------------------

Sometimes we don't want to save values in plain text in environment files or in
the settings file itself. Instead we have a file that contains the value of the
setting we want. A good example for this behaviour are docker _secrets that
store secrets in temporary files.

To read a variable from a file, simply add a `"_from_file"` to the variable
name and give it the path to the file that contains the variable as a value.

Using:

.. code::

   [section1]
   subsection1_from_file = /home/myuser/supersecret.txt

or

.. code:: sh

   export MY_APP_SECTION1_SUBSECTION1_FROM_FILE="/home/myuser/supersecret.txt"

will both write the content of the file at `"/home/myuser/supersecret.txt"`
into the variable `section1 -> sebsection1`.


Command line support using click
--------------------------------

The click_ library is a great tool for creating command line applications. If
you don't want to have to use an environment to set your configuration file.
Write your command line application like this:

.. code:: python

   import click

   @click.command()
   @settings_map.click_settings_file_option()
   def cli():
      print(dict(settings_parser))

save it to a file like "cli.py" and then call it after installing click:

.. code:: sh

   pip install click
   python cli.py --settings ./my_settings_file.toml

whithout needing to set any env vars.

Multiple files are supported. They will be automatically recursively merged
with the last file overriting any overlapping keys of the first file.

.. code:: sh

   pip install click
   python cli.py --settings ./my_settings_file.toml  --settings ./my_settings_file.yaml


Testing
-------

When testing your application, different behaviours often depend on settings
taking on different values. Assuming that you are using a single `Settings`
object accross multiple functions or modules, handling these settings changes
in tests can be tricky.

The settings object provides a simple method for modifying your settings object
temporarily:

.. code:: python

   settings_map.update({'a': 1})
   # Enter a temporary changes context block:
   with settings_map.temporary_changes():
       settings_map.update({'a': 1})
       # Inside the context, the settings can be modified and used as you choose
       print(settings_map['a'])  # outputs: 2
   # After the context exits the settings map
   print(settings_map['a'])  # outputs: 1


Limitations
-----------

Do to the use of modern python features, only python 3.5 and above are supported.


.. |Build Status| image:: https://travis-ci.org/daviskirk/climatecontrol.svg?branch=master
   :target: https://travis-ci.org/daviskirk/climatecontrol
.. |Coverage Status| image:: https://coveralls.io/repos/github/daviskirk/climatecontrol/badge.svg?branch=master
   :target: https://coveralls.io/github/daviskirk/climatecontrol?branch=master
.. |PyPi Status| image:: https://badge.fury.io/py/climatecontrol.svg
   :target: https://badge.fury.io/py/climatecontrol
.. _click: http://click.pocoo.org/
.. _toml: https://github.com/toml-lang/toml
.. _secrets: https://docs.docker.com/engine/swarm/secrets


