Metadata-Version: 2.0
Name: pluginlib
Version: 0.6.0
Summary: A framework for creating and importing plugins
Home-page: https://github.com/Rockhopper-Technologies/pluginlib
Author: Avram Lubkin
Author-email: avylove@rockhopper.net
License: MPLv2.0
Keywords: plugin,plugins,pluginlib
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: setuptools

.. start-badges

| |docs| |travis| |codecov|
| |pypi| |supported-versions| |supported-implementations|
| |fedora| |EPEL|

.. |docs| image:: https://img.shields.io/readthedocs/pluginlib.svg?style=plastic
    :target: https://pluginlib.readthedocs.org
    :alt: Documentation Status
.. |travis| image:: https://img.shields.io/travis/Rockhopper-Technologies/pluginlib.svg?style=plastic
    :target: https://travis-ci.org/Rockhopper-Technologies/pluginlib
    :alt: Travis-CI Build Status
.. |codecov| image:: https://img.shields.io/codecov/c/github/Rockhopper-Technologies/pluginlib.svg?style=plastic
    :target: https://codecov.io/gh/Rockhopper-Technologies/pluginlib
    :alt: Coverage Status

.. |pypi| image:: https://img.shields.io/pypi/v/pluginlib.svg?style=plastic
    :alt: PyPI Package latest release
    :target: https://pypi.python.org/pypi/pluginlib
.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/pluginlib.svg?style=plastic
    :alt: Supported versions
    :target: https://pypi.python.org/pypi/pluginlib
.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/pluginlib.svg?style=plastic
    :alt: Supported implementations
    :target: https://pypi.python.org/pypi/pluginlib

.. |fedora| image:: https://img.shields.io/badge/dynamic/json.svg?uri=https://pdc.fedoraproject.org/rest_api/v1/component-branches/?global_component=python-pluginlib;fields=name;active=true;type=rpm&query=$.results[?(@.name.startsWith(%22f%22))].name&label=Fedora&colorB=lightgray&style=plastic
    :alt: Fedora version support
    :target: https://bodhi.fedoraproject.org/updates/?packages=python-pluginlib

.. |EPEL| image:: https://img.shields.io/badge/dynamic/json.svg?uri=https://pdc.fedoraproject.org/rest_api/v1/component-branches/?global_component=python-pluginlib;fields=name;active=true;type=rpm&query=$.results[?(@.name.startsWith(%22e%22))].name&label=EPEL&colorB=lightgray&style=plastic
    :alt: EPEL version support
    :target: https://bodhi.fedoraproject.org/updates/?packages=python-pluginlib



.. end-badges

Overview
========

Pluginlib makes creating plugins for your project simple.

Step 1: Define plugin parent classes
------------------------------------

All plugins are subclasses of parent classes. To create a parent class, use the
@Parent_ decorator.

The @Parent_ decorator can take a plugin type for accessing child plugins
of the parent. If a plugin type isn't given, the class name will be used.

The @Parent_ decorator can also take a ``group`` keyword which
restricts plugins to a specific plugin group. ``group`` should be specified if plugins for
different projects could be accessed in an single program, such as with libraries and frameworks.
For more information, see the `Plugin Groups`_ section.

Methods required in child plugins should be labeled as abstract methods.
Plugins without these methods or with parameters
that don't match, will not be loaded.
For more information, see the `Abstract Methods`_ section.

.. code-block:: python

    """
    sample.py
    """
    import pluginlib

    @pluginlib.Parent('parser')
    class Parser(object):

        @pluginlib.abstractmethod
        def parse(self, string):
            pass

Step 2: Define plugin classes
-----------------------------

To create a plugin, subclass a parent class and include any required methods.

Plugins can be customized through optional class attributes:

    `_alias_`_
        Changes the name of the plugin which defaults to the class name.

    `_version_`_
        Sets the version of the plugin. Defaults to the module ``__version__`` or ``None``
        If multiple plugins with the same type and name are loaded, the plugin with
        the highest version is used. For more information, see the Versions_ section.

    `_skipload_`_
        Specifies the plugin should not be loaded. This is useful when a plugin is a parent class
        for additional plugins or when a plugin should only be loaded under certain conditions.
        For more information see the `Conditional Loading`_ section.


.. code-block:: python

    """
    sample_plugins.py
    """
    import json
    import sample

    class JSON(sample.Parser):

        _alias_ = 'json'

        def parse(self, string):
            return json.loads(string)

Step 3: Load plugins
--------------------

Plugins are loaded when the module they are in is imported. PluginLoader_
will load modules from specified locations and provides access to them.

PluginLoader_ can load plugins from several locations.
    - A program's standard library
    - `Entry points`_
    - A list of modules
    - A list of filesystem paths

Plugins can also be filtered through blacklists and type filters.
See the Blacklists_ and `Type Filters`_ sections for more information.

Plugins are accessible through the PluginLoader.plugins_ property,
a nested dictionary accessible through dot notation. For other ways to access plugins,
see the `Accessing Plugins`_ section.

.. code-block:: python

    import pluginlib
    import sample

    loader = pluginlib.PluginLoader(modules=['sample_plugins'])
    plugins = loader.plugins
    parser = plugins.parser.json()
    print(parser.parse('{"json": "test"}'))

.. _Entry points: https://packaging.python.org/specifications/entry-points/

.. _PluginLoader: http://pluginlib.readthedocs.io/en/latest/api.html#pluginlib.PluginLoader
.. _PluginLoader.plugins: http://pluginlib.readthedocs.io/en/latest/api.html#pluginlib.PluginLoader.plugins
.. _@Parent: http://pluginlib.readthedocs.io/en/latest/api.html#pluginlib.Parent
.. _\_alias\_: http://pluginlib.readthedocs.io/en/latest/api.html#pluginlib.Plugin._alias_
.. _\_version\_: http://pluginlib.readthedocs.io/en/latest/api.html#pluginlib.Plugin._version_
.. _\_skipload\_: http://pluginlib.readthedocs.io/en/latest/api.html#pluginlib.Plugin._skipload_

.. _Versions: http://pluginlib.readthedocs.io/en/latest/concepts.html#versions
.. _Blacklists: http://pluginlib.readthedocs.io/en/latest/concepts.html#blacklists
.. _Type Filters: http://pluginlib.readthedocs.io/en/latest/concepts.html#type-filters
.. _Accessing Plugins: http://pluginlib.readthedocs.io/en/latest/concepts.html#accessing-plugins
.. _Abstract Methods: http://pluginlib.readthedocs.io/en/latest/concepts.html#abstract-methods
.. _Conditional Loading: http://pluginlib.readthedocs.io/en/latest/concepts.html#conditional-loading
.. _Plugin Groups: http://pluginlib.readthedocs.io/en/latest/concepts.html#plugin-groups


