Metadata-Version: 2.0
Name: env-cmd
Version: 1.0
Summary: A simple wrapper for executing virtualenv commands and passing them environment variables via a config file.
Home-page: https://github.com/brutasse/env-cmd
Author: Bruno Renié
Author-email: UNKNOWN
License: BSD
Platform: any
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3

Env-cmd
=======

A simple wrapper for executing virtualenv commands and passing them environment variables via a config file.

Use case
--------

Let's say you deploy a Django site named "example.com". You follow all
the best practices and deploy it as a Python package, installed in an
isolated virtualenv at ``/usr/share/python/example-com`` (as `dh_virtualenv
<https://github.com/spotify/dh-virtualenv>`_ would do).

Configuration is read from environment variables in the Django settings.

When you want to run a Django management command on your server, you would
type::

    ENV_VAR_1=value ENV_VAR_2=other … /usr/share/python/example-com/bin/django-admin <command>

You could use `envdir <https://cr.yp.to/daemontools/envdir.html>`_ or bash's
``source`` command to expose your environment variables, but **Env-cmd** eases
that further. It allows you to read a configuration file, expose values in
the environment and run a command simply by adding a setuptools entry point
in your ``setup.py``. With the entry point symlinked to ``/usr/bin``, your
command becomes::

    example-com django-admin <command>

Env-cmd:

* Reads a configuration file using the default location provided, or an
  override.
* Exposes configuration values as environment variables.
* Resolves the path of your virtualenv.
* Shells out to the virtualenv command.

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

::

    pip install env-cmd

Usage
-----

In ``<yourproject>/cli.py``:

.. code-block:: python

    import env_cmd

    read_environ = env_cmd.read_environ(
        'PRCONFIG',  # name of the env var that allows overriding of the
                     # config path.
        '/etc/yourproject.conf', # default config path.
        {'SOME_ENV_VARIABLE': 'DEFAULT_VALUE', # Some default environment
         'OTHER_VARIABLE', 'OTHER VALUE'},     # variables.
    )
    main = env_cmd.main(read_environ)

In your ``setup.py``:

.. code-block:: python

    setup(
        …
        entry_points={'console_scripts': ['yourproject=yourproject:main']},
    )

Then symlink ``/path/to/virtualenv/bin/yourproject`` to
``/usr/bin/yourproject``.

You can run a command from your virtualenv with::

    yourproject <command>

Override the default config path with::

    PRCONFIG=/path/to/config.conf yourproject <command>

Configuration syntax is the following::

    KEY=value
    OTHER=some other value
    QUOTED="quotes are stripped."
    ALSO='single quotes too'
    WHITESPACE=    is stripped as well.
    # comments work like this

    # empty lines are skipped

If you run a web server with `Gunicorn <http://gunicorn.org/>`_, you can
use the ``on_reload`` hook to read configuration on server reload, allowing
zero-downtime configuration updates:

.. code-block:: python

    # gunicorn.conf.py
    import os

    from yourproject import read_environ

    def on_reload(server):
        server.log.info("Reading environ")
        os.environ = read_environ()
        server.log.info(os.environ)


