runenv 1.0.0

===============================
runenv
===============================

.. image:: https://img.shields.io/travis/onjin/runenv.svg
:target: https://travis-ci.org/onjin/runenv

.. image:: https://img.shields.io/pypi/v/runenv.svg
:target: https://pypi.python.org/pypi/runenv

.. image:: https://img.shields.io/badge/license-New%20BSD-blue.svg
:target: https://github.com/onjin/runenv/blob/master/LICENSE

.. image:: https://img.shields.io/pypi/dm/runenv.svg
:target: https://pypi.python.org/pypi/runenv


Wrapper to run programs with modified environment variables loaded from given file. You can use *runenv* to manage your
app settings using 12-factor_ principles.

You can use same environment file with **runenv** and with **docker** using `env-file`_ parameter

.. _env-file: https://docs.docker.com/reference/commandline/cli/
.. _12-factor: http://12factor.net/


* Free software: BSD license
* Documentation: https://runenv.readthedocs.org.

--------
Features
--------

CLI:

* command-line tool to load environment variables from given file

Python API:

* load variables from a file (`.env` or passed filename)
* load only variables with given `prefix`
* `prefix` can be stripped during load
* detect whether environment was loaded by `runenv` CLI
* force load even if `runenv` CLI was used
* `search_parent` option which allows to look for `env_file` in parent dirs


------------
Installation
------------

In order to install use `pip`

.. code-block:: console

$ pip install -U runenv

-----
Usage
-----

Run from shell

.. code-block:: console

$ runenv env.development ./manage.py runserver

example `env.development` file

.. code-block:: python


BASE_URL=http://127.0.0.1:8000
DATABASE_URI=postgres://postgres:password@localhost/dbname
SECRET_KEY=y7W8pbRcuPuAmgTHsJtEpKocb7XPcV0u

# email settings
EMAIL_HOST=smtp.mandrillapp.com
EMAIL_PORT=587
EMAIL_HOST_USER=someuser
EMAIL_HOST_PASSWORD=hardpassword
EMAIL_FROM=dev@local.host
EMAIL_USE_TLS=1

----------
Python API
----------

**load_env(env_file='.env', prefix=None, strip_prefix=True, force=False, search_parent=0)**

Loads environment from given ``env_file``` (default `.env`).


Options:

+--------------+---------+--------------------------------------------------------------------------------+
| option | default | description |
+==============+=========+================================================================================+
| env_file | `.env` | relative or absolute path to file with environment variables |
+--------------+---------+--------------------------------------------------------------------------------+
| prefix | `None` | prefix to match variables e.g. `APP_` |
+--------------+---------+--------------------------------------------------------------------------------+
| strip_prefix | `True` | should the prefix be stripped during loa |
+--------------+---------+--------------------------------------------------------------------------------+
| force | `False` | load env_file, even though `runenv` CLI command was used |
+--------------+---------+--------------------------------------------------------------------------------+
| search_parent| `0` | To what level traverse parents in search of file |
+--------------+---------+--------------------------------------------------------------------------------+

If ``prefix`` option is provided only variables starting with it will be loaded to environment, with their keys stripped of that prefix. To preserve prefix, you can set ``strip_prefix`` to ``False``.


Example

.. code-block:: console

$ echo 'APP_SECRET_KEY=bzemAG0xfdMgFrHBT3tJBbiYIoY6EeAj' > .env

.. code-block:: python

$ python
>>> import os
>>> from runenv import load_env
>>> load_env(prefix='APP_')
>>> 'APP_SECRET_KEY' in os.environ
False
>>> 'SECRET_KEY' in os.environ
True
>>> load_env(prefix='APP_', strip_prefix=False)
>>> 'APP_SECRET_KEY' in os.environ
True


**Notice**: Environment will not be loaded if command was fired by `runenv` wrapper, unless you set the **force** parameter to **True**

``load_env`` does not load variables when wrapper ``runenv`` is used. Also ``_RUNENV_WRAPPED`` is set to ``1``

Example

.. code-block:: console

$ echo 'APP_SECRET_KEY=bzemAG0xfdMgFrHBT3tJBbiYIoY6EeAj' > .env

.. code-block:: python

$ python
>>> import os
>>> from runenv import load_env
>>> os.environ['_RUNENV_WRAPPED'] = '1'
>>> load_env()
>>> 'APP_SECRET_KEY' in os.environ
False
>>> load_env(force=True)
>>> 'APP_SECRET_KEY' in os.environ
True


Django/Flask integration
------------------

To use ``load_env`` with `Django`_ or `Flask`_, put the followin in ``manage.py`` and ``wsgi.py``

.. code-block:: python


from runenv import load_env
load_env()


.. _django: http://djangoproject.com/
.. _flask: http://flask.pocoo.org/




Similar projects
----------------

* https://github.com/jezdez/envdir - runs another program with a modified environment according to files in a specified directory
* https://github.com/theskumar/python-dotenv - Reads the key,value pair from .env and adds them to environment variable




History
-------

1.0.0 (2017-02-03)
------------------
* changed version to `1.0.0`

0.4.0 (2016-08-08)
------------------
* add support for `search_parent` option

0.3.1 (2016-06-21)
------------------
* add support for quoted values

0.3.0 (2016-02-14)
------------------
* change `Development Status` to `5 - Production/Stable`

0.2.5 (2015-11-30)
---------------------
* do not look for executable as absolute path

0.2.4 (2015-07-06)
---------------------
* skip `load_env` if env file does not exists

0.2.3 (2015-06-26)
---------------------
* support to run programs from PATH

0.2.2 (2015-06-16)
---------------------
* fix compatibility with python3

0.2.1 (2015-06-16)
---------------------
* add `strip_prefix` option to `load_env`

0.2.0 (2015-06-16)
---------------------
* add `load_env` (python api)

0.1.4 (2015-06-15)
---------------------

* Check if file to run exists and is executable

0.1.3 (2015-06-01)
---------------------

* Support for env file comments by '#'

0.1.2 (2015-06-01)
---------------------

* Return code from runned command

0.1.1 (2015-05-31)
---------------------

* First release on PyPI.