Metadata-Version: 1.1
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
Description: 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)
        
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
