===================
plaster_pastedeploy
===================

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

.. image:: https://img.shields.io/travis/Pylons/plaster_pastedeploy/master.svg
        :target: https://travis-ci.org/Pylons/plaster_pastedeploy

``plaster_pastedeploy`` is a plaster_ plugin that provides a ``plaster.Loader``
that can parse ini files according to the standard set by PasteDeploy_. It
supports the ``wsgi`` plaster protocol, implementing the
``plaster.protocols.IWSGIProtocol`` interface.

Usage
=====

Applications should use ``plaster_pastedeploy`` to load settings from named
sections in a configuration source (usually a file).

- Please look at the documentation for plaster_ on how to integrate this
  loader into your application.

- Please look at the documentation for PasteDeploy_ on the specifics of the
  supported INI file format.

Most applications will want to use
``plaster.get_loader(uri, protocols=['wsgi'])`` to get this loader. It then
exposes ``get_wsgi_app``, ``get_wsgi_app_settings``, ``get_wsgi_filter`` and
``get_wsgi_server``.

.. code-block:: python

    import plaster

    loader = plaster.get_loader('development.ini', protocols=['wsgi'])
    # to get any section out of the config file
    settings = loader.get_settings('app:main')

    # to get settings for a WSGI app
    app_config = loader.get_wsgi_app_settings()  # defaults to main

    # to get an actual WSGI app
    app = loader.get_wsgi_app()  # defaults to main

    # to get a filter and compose it with an app
    filter = loader.get_wsgi_filter('filt')
    app = filter(app)

    # to get a WSGI server
    server = loader.get_wsgi_server()  # defaults to main

    # to start the WSGI server
    server(app)

Any ``plaster.PlasterURL`` options are forwarded as defaults to the loader.
Some examples are below:

- ``development.ini#myapp``

- ``development.ini?http_port=8080#main``

- ``pastedeploy+ini:///path/to/development.ini``

- ``pastedeploy+ini://development.ini#foo``

- ``egg:MyApp?debug=false#foo``

Environment Variables
---------------------

**This feature is not supported on Python 2.**

This binding extends ``pastedeploy`` to inject environ variables as defaults
which are available to use in the INI file. Each ``os.environ`` key is prefixed
with ``ENV_`` and added as a default.

For example:

.. code-block:: ini

   [app:main]
   debug = %(ENV_APP_DEBUG)s

The only thing to be aware of here is that there is no fallback. The INI file
will fail to parse if the environment variable is not set. The app may be run
like so:

.. code-block:: bash

   $ APP_DEBUG=true env/bin/pserve development.ini

.. _PasteDeploy: https://pastedeploy.readthedocs.io/en/latest/
.. _plaster: https://docs.pylonsproject.org/projects/plaster/en/latest/