Metadata-Version: 1.1
Name: oops_dictconfig
Version: 0.0.4
Summary: Create an oops Config from a definition encoded as a dict
Home-page: http://launchpad.net/python-oops-dictconfig
Author: Launchpad developers
Author-email: launchpad-devs@lists.launchpad.net
License: LGPLv3
Download-URL: https://launchpad.net/python-oops-dictconfig/+download
Description: python-oops-dictconfig
        ======================
        
        Create an `oops.Config` object from a definition encoded as a dictionary.
        
        Dependencies
        ------------
        
          * python-oops (http://pypi.python.org/pypi/oops)
        
        Also the following dependencies are required depending on the configs
        you will use:
        
          * python-oops-datedir-repo (http://pypi.python.org/pypi/oops_datedir_repo)
          * python-oops-amqp (http://pypi.python.org/pypi/oops_datedir_repo)
        
        For testing all of the above are needed, along with:
        
          * python-testtools
        
        Use
        ---
        
        To use run::
        
           from oops_dictconfig import config_from_dict
        
           oops_config = config_from_dict(dict_config)
        
        where `dict_config` is a `dict` describing the `oops.Config` that is
        wanted.
        
        The empty dict is valid, and will get you an `oops.Config` with
        no publishers, however, you will usually want at least one publisher.
        
        To do that have a `publishers` key in `dict_config` whose value is a list
        of dicts. Each of those dicts will add a publisher to the `oops.Config`.
        
        There is one mandatory key for all publisher types:
        
          * type: the type of publisher, currently `"datedir"` and `"amqp"` are
                  supported.
        
        All publishers support the following optional key:
        
          * new_only: if this is `True` then the publisher will be wrapped in
                      `oops.publish_only_new`, meaning that the oops will only
                      be sent to this publisher if no previous publisher in the
                      chain published it.
        
        Each publisher type also has further options detailed below.
        
        datedir
        ```````
        
        There is one further mandatory key for the datedir publisher:
        
          * error_dir: the path on filesystem where the oops should be written.
                       It doesn't need to already exist.
        
        The following optional keys are also supported:
        
          * inherit_id: If True, use the oops ID (if present) supplied in
                        the report, rather than always assigning a new one.
          * stash_path: If True, the filename that the OOPS was written to
                        is stored in the OOPS report under the key 'datedir_repo_filepath'.
                        It is not stored in the OOPS written to disk, only the in-memory
                        model.
        
        amqp
        ````
        
        There are several other mandatory keys for the amqp publisher:
        
          * host: the hostname of the AMQP broker to connect to. If a port
                  is needed then specify it after the hostname, separated by
                  a colon. Examples: `example.com`, `1.2.3.4:5022`.
        
          * user: the username to use when connecting to the AMQP broker.
        
          * password: the password to use when connecting to the AMQP broker.
        
          * vhost: the vhost to send messages on the AMQP broker.
        
          * exchange_name: The name of the exchange to publish to.
        
          * routing_key: The routing key for messages.
        
        There is one other optional key for the amqp publisher:
        
          * inherit_id If True any 'True' 'id' in an OOPS report is
                       preserved. Handy if an id that has already been shown
                       to a user is being published (but uniqueness cannot be
                       guaranteed).
        
        Examples
        --------
        
        The following would create a DateDirRepo as the only publisher::
        
            {
                'publishers': [
                    {
                        'type': 'datedir',
                        'error_dir': '/var/log/oopses/',
                    },
                ],
            }
        
        The following is a simple config for an AMQP publisher::
        
            {
                'publishers': [
                    {
                        'type': 'amqp',
                        'host': 'amqp.example.com:5302',
                        'user': 'oopsuser',
                        'password': 'oopspassword',
                        'vhost': 'oopses',
                        'exchange_name': 'oopses',
                        'routing_key': 'oopses',
                    },
                ],
            }
        
        The following is an example that publishes to AMQP with a fallback
        to DateDirRepo if AMQP is not availble::
        
            {
                'publishers': [
                    {
                        'type': 'amqp',
                        'host': 'amqp.example.com:5302',
                        'user': 'oopsuser',
                        'password': 'oopspassword',
                        'vhost': 'oopses',
                        'exchange_name': 'oopses',
                        'routing_key': 'oopses',
                    },
                    {
                        'type': 'datedir',
                        'error_dir': '/var/log/oopses/',
                        'new_only': True,
                    },
                ],
            }
        
        
        Template
        --------
        
        You can set the template for oopses by adding a 'template' key to
        the dict. This should itself be a dict mapping keys to default values.
        The template will then be used by the config when creating oopses.
        
        The most common use of this is to set the publisher for oopses
        coming from that config::
        
            {
                'template': {
                    'publisher': 'myapp',
                },
            }
        
        
        configglue
        ----------
        
        If you are using configglue to manage your configuration an Option
        subclass is supplied that can be used in your schema as appropriate::
        
            from configglue import schema
            from oops_dictconfig.configglue import OopsOption
        
            class MySchema(schema.Schema):
        
                oopses = OopsOption()
        
        
        Once that is defined you can produce the config described above
        using your configglue config file::
        
            oopses = oopses_config
        
            [oopses_config]
            publishers = amqp_publisher
                         datedir_publisher
        
            [amqp_publisher]
            type = amqp
            host = amqp.example.com:6832
            user = oopsuser
            password = oopspassword
            vhost = oopses
            exchange_name = oopses
            routing_key = oopses
        
            [datedir_publisher]
            type = datedir
            error_dir = /var/log/oopses
            only_new = True
        
        
        Running Tests
        -------------
        
        Install `testrepository` and `python-subunit` and run::
        
           testr init
           testr run
        
        or run::
        
           python -m testools.run oops_dictconfig.tests.test_suite
        
        
        ..
        
                Copyright (c) 2012, Canonical Ltd
        
                This program is free software: you can redistribute it and/or modify
                it under the terms of the GNU Lesser General Public License as published by
                the Free Software Foundation, version 3 only.
        
                This program is distributed in the hope that it will be useful,
                but WITHOUT ANY WARRANTY; without even the implied warranty of
                MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
                GNU Lesser General Public License for more details.
        
                You should have received a copy of the GNU Lesser General Public License
                along with this program.  If not, see <http://www.gnu.org/licenses/>.
                GNU Lesser General Public License version 3 (see the file LICENSE).
        
Platform: UNKNOWN
