.. start-badges
| |docs| |gh_actions| |codecov|
| |pypi| |supported-versions| |supported-implementations|
| |fedora| |EPEL|
.. |docs| image:: https://img.shields.io/readthedocs/pluginlib.svg?style=plastic&logo=read-the-docs
:target: https://pluginlib.readthedocs.org
:alt: Documentation Status
.. |gh_actions| image:: https://img.shields.io/github/actions/workflow/status/Rockhopper-Technologies/pluginlib/tests.yml?event=push&logo=github-actions&style=plastic
:target: https://github.com/Rockhopper-Technologies/pluginlib/actions/workflows/tests.yml
:alt: GitHub Actions Status
.. |travis| image:: https://img.shields.io/travis/com/Rockhopper-Technologies/pluginlib.svg?style=plastic&logo=travis
:target: https://travis-ci.com/Rockhopper-Technologies/pluginlib
:alt: Travis-CI Build Status
.. |codecov| image:: https://img.shields.io/codecov/c/github/Rockhopper-Technologies/pluginlib.svg?style=plastic&logo=codecov
:target: https://codecov.io/gh/Rockhopper-Technologies/pluginlib
:alt: Coverage Status
.. |pypi| image:: https://img.shields.io/pypi/v/pluginlib.svg?style=plastic&logo=pypi
: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&logo=pypi
:alt: Supported versions
:target: https://pypi.python.org/pypi/pluginlib
.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/pluginlib.svg?style=plastic&logo=pypi
: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&logo=fedora
: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&logo=epel
:alt: EPEL version support
:target: https://bodhi.fedoraproject.org/updates/?packages=python-pluginlib
.. end-badges
Overview
========
Pluginlib makes creating plugins for your project simple.
Features
--------
- Plugins are validated when they are imported
- Plugins can be loaded through different mechanisms (modules, filesystem paths, `entry points`_)
- Multiple versions_ of the same plugin are supported (The newest one is used by default)
- Plugins can be `blacklisted`_ by type, name, or version
- Multiple `plugin groups`_ are supported so one program can use multiple sets of plugins that won't conflict
- Plugins support `conditional loading`_ (examples: os, version, installed software, etc)
- Once loaded, plugins can be accessed_ through dictionary or dot notation
Installation
============
PIP
---
.. code-block:: console
$ pip install pluginlib
Fedora and EL (RHEL/CentOS/Rocky/Alma)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(EPEL_ repositories must be configured_ for EL8)
.. code-block:: console
$ dnf install python3-pluginlib
EL7 (RHEL/CentOS)
^^^^^^^^^^^^^^^^^
(EPEL_ repositories must be configured_)
.. code-block:: console
$ yum install python2-pluginlib
$ yum install python36-pluginlib
Usage
=====
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/stable/api.html#pluginlib.PluginLoader
.. _PluginLoader.plugins: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.PluginLoader.plugins
.. _@Parent: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Parent
.. _\_alias\_: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Plugin._alias_
.. _\_version\_: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Plugin._version_
.. _\_skipload\_: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Plugin._skipload_
.. _Versions: http://pluginlib.readthedocs.io/en/stable/concepts.html#versions
.. _Blacklists: http://pluginlib.readthedocs.io/en/stable/concepts.html#blacklists
.. _blacklisted: http://pluginlib.readthedocs.io/en/stable/concepts.html#blacklists
.. _Type Filters: http://pluginlib.readthedocs.io/en/stable/concepts.html#type-filters
.. _Accessing Plugins: http://pluginlib.readthedocs.io/en/stable/concepts.html#accessing-plugins
.. _accessed: http://pluginlib.readthedocs.io/en/stable/concepts.html#accessing-plugins
.. _Abstract Methods: http://pluginlib.readthedocs.io/en/stable/concepts.html#abstract-methods
.. _Conditional Loading: http://pluginlib.readthedocs.io/en/stable/concepts.html#conditional-loading
.. _Plugin Groups: http://pluginlib.readthedocs.io/en/stable/concepts.html#plugin-groups
.. _EPEL: https://fedoraproject.org/wiki/EPEL
.. _configured: https://docs.fedoraproject.org/en-US/epel/#how_can_i_use_these_extra_packages
Raw data
{
"_id": null,
"home_page": "https://github.com/Rockhopper-Technologies/pluginlib",
"name": "pluginlib",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "plugin, plugins, pluginlib",
"author": "Avram Lubkin",
"author_email": "avylove@rockhopper.net",
"download_url": "https://files.pythonhosted.org/packages/3a/18/ffd8119bc2fe08fd1b1e7e203f059425ebfb6784add006be0867c088bfdb/pluginlib-0.9.2.tar.gz",
"platform": null,
"description": ".. start-badges\n\n| |docs| |gh_actions| |codecov|\n| |pypi| |supported-versions| |supported-implementations|\n| |fedora| |EPEL|\n\n.. |docs| image:: https://img.shields.io/readthedocs/pluginlib.svg?style=plastic&logo=read-the-docs\n :target: https://pluginlib.readthedocs.org\n :alt: Documentation Status\n\n.. |gh_actions| image:: https://img.shields.io/github/actions/workflow/status/Rockhopper-Technologies/pluginlib/tests.yml?event=push&logo=github-actions&style=plastic\n :target: https://github.com/Rockhopper-Technologies/pluginlib/actions/workflows/tests.yml\n :alt: GitHub Actions Status\n\n.. |travis| image:: https://img.shields.io/travis/com/Rockhopper-Technologies/pluginlib.svg?style=plastic&logo=travis\n :target: https://travis-ci.com/Rockhopper-Technologies/pluginlib\n :alt: Travis-CI Build Status\n\n.. |codecov| image:: https://img.shields.io/codecov/c/github/Rockhopper-Technologies/pluginlib.svg?style=plastic&logo=codecov\n :target: https://codecov.io/gh/Rockhopper-Technologies/pluginlib\n :alt: Coverage Status\n\n.. |pypi| image:: https://img.shields.io/pypi/v/pluginlib.svg?style=plastic&logo=pypi\n :alt: PyPI Package latest release\n :target: https://pypi.python.org/pypi/pluginlib\n.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/pluginlib.svg?style=plastic&logo=pypi\n :alt: Supported versions\n :target: https://pypi.python.org/pypi/pluginlib\n.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/pluginlib.svg?style=plastic&logo=pypi\n :alt: Supported implementations\n :target: https://pypi.python.org/pypi/pluginlib\n\n.. |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&logo=fedora\n :alt: Fedora version support\n :target: https://bodhi.fedoraproject.org/updates/?packages=python-pluginlib\n\n.. |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&logo=epel\n :alt: EPEL version support\n :target: https://bodhi.fedoraproject.org/updates/?packages=python-pluginlib\n\n\n\n.. end-badges\n\nOverview\n========\n\nPluginlib makes creating plugins for your project simple.\n\nFeatures\n--------\n\n- Plugins are validated when they are imported\n\n- Plugins can be loaded through different mechanisms (modules, filesystem paths, `entry points`_)\n\n- Multiple versions_ of the same plugin are supported (The newest one is used by default)\n\n- Plugins can be `blacklisted`_ by type, name, or version\n\n- Multiple `plugin groups`_ are supported so one program can use multiple sets of plugins that won't conflict\n\n- Plugins support `conditional loading`_ (examples: os, version, installed software, etc)\n\n- Once loaded, plugins can be accessed_ through dictionary or dot notation\n\nInstallation\n============\n\nPIP\n---\n\n.. code-block:: console\n\n $ pip install pluginlib\n\nFedora and EL (RHEL/CentOS/Rocky/Alma)\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n(EPEL_ repositories must be configured_ for EL8)\n\n.. code-block:: console\n\n $ dnf install python3-pluginlib\n\nEL7 (RHEL/CentOS)\n^^^^^^^^^^^^^^^^^\n\n(EPEL_ repositories must be configured_)\n\n.. code-block:: console\n\n $ yum install python2-pluginlib\n $ yum install python36-pluginlib\n\nUsage\n=====\n\nStep 1: Define plugin parent classes\n------------------------------------\n\nAll plugins are subclasses of parent classes. To create a parent class, use the\n`@Parent`_ decorator.\n\nThe `@Parent`_ decorator can take a plugin type for accessing child plugins\nof the parent. If a plugin type isn't given, the class name will be used.\n\nThe `@Parent`_ decorator can also take a ``group`` keyword which\nrestricts plugins to a specific plugin group. ``group`` should be specified if plugins for\ndifferent projects could be accessed in an single program, such as with libraries and frameworks.\nFor more information, see the `Plugin Groups`_ section.\n\nMethods required in child plugins should be labeled as abstract methods.\nPlugins without these methods or with parameters\nthat don't match, will not be loaded.\nFor more information, see the `Abstract Methods`_ section.\n\n.. code-block:: python\n\n \"\"\"\n sample.py\n \"\"\"\n import pluginlib\n\n @pluginlib.Parent('parser')\n class Parser(object):\n\n @pluginlib.abstractmethod\n def parse(self, string):\n pass\n\nStep 2: Define plugin classes\n-----------------------------\n\nTo create a plugin, subclass a parent class and include any required methods.\n\nPlugins can be customized through optional class attributes:\n\n `_alias_`_\n Changes the name of the plugin which defaults to the class name.\n\n `_version_`_\n Sets the version of the plugin. Defaults to the module ``__version__`` or ``None``\n If multiple plugins with the same type and name are loaded, the plugin with\n the highest version is used. For more information, see the Versions_ section.\n\n `_skipload_`_\n Specifies the plugin should not be loaded. This is useful when a plugin is a parent class\n for additional plugins or when a plugin should only be loaded under certain conditions.\n For more information see the `Conditional Loading`_ section.\n\n\n.. code-block:: python\n\n \"\"\"\n sample_plugins.py\n \"\"\"\n import json\n import sample\n\n class JSON(sample.Parser):\n\n _alias_ = 'json'\n\n def parse(self, string):\n return json.loads(string)\n\nStep 3: Load plugins\n--------------------\n\nPlugins are loaded when the module they are in is imported. PluginLoader_\nwill load modules from specified locations and provides access to them.\n\nPluginLoader_ can load plugins from several locations.\n - A program's standard library\n - `Entry points`_\n - A list of modules\n - A list of filesystem paths\n\nPlugins can also be filtered through blacklists and type filters.\nSee the Blacklists_ and `Type Filters`_ sections for more information.\n\nPlugins are accessible through the PluginLoader.plugins_ property,\na nested dictionary accessible through dot notation. For other ways to access plugins,\nsee the `Accessing Plugins`_ section.\n\n.. code-block:: python\n\n import pluginlib\n import sample\n\n loader = pluginlib.PluginLoader(modules=['sample_plugins'])\n plugins = loader.plugins\n parser = plugins.parser.json()\n print(parser.parse('{\"json\": \"test\"}'))\n\n.. _Entry points: https://packaging.python.org/specifications/entry-points/\n\n.. _PluginLoader: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.PluginLoader\n.. _PluginLoader.plugins: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.PluginLoader.plugins\n.. _@Parent: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Parent\n.. _\\_alias\\_: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Plugin._alias_\n.. _\\_version\\_: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Plugin._version_\n.. _\\_skipload\\_: http://pluginlib.readthedocs.io/en/stable/api.html#pluginlib.Plugin._skipload_\n\n.. _Versions: http://pluginlib.readthedocs.io/en/stable/concepts.html#versions\n.. _Blacklists: http://pluginlib.readthedocs.io/en/stable/concepts.html#blacklists\n.. _blacklisted: http://pluginlib.readthedocs.io/en/stable/concepts.html#blacklists\n.. _Type Filters: http://pluginlib.readthedocs.io/en/stable/concepts.html#type-filters\n.. _Accessing Plugins: http://pluginlib.readthedocs.io/en/stable/concepts.html#accessing-plugins\n.. _accessed: http://pluginlib.readthedocs.io/en/stable/concepts.html#accessing-plugins\n.. _Abstract Methods: http://pluginlib.readthedocs.io/en/stable/concepts.html#abstract-methods\n.. _Conditional Loading: http://pluginlib.readthedocs.io/en/stable/concepts.html#conditional-loading\n.. _Plugin Groups: http://pluginlib.readthedocs.io/en/stable/concepts.html#plugin-groups\n\n.. _EPEL: https://fedoraproject.org/wiki/EPEL\n.. _configured: https://docs.fedoraproject.org/en-US/epel/#how_can_i_use_these_extra_packages\n",
"bugtrack_url": null,
"license": "MPLv2.0",
"summary": "A framework for creating and importing plugins",
"version": "0.9.2",
"project_urls": {
"Homepage": "https://github.com/Rockhopper-Technologies/pluginlib"
},
"split_keywords": [
"plugin",
" plugins",
" pluginlib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2793192a798f2c89f88eea74eb071ce8ddf367d16b8ac6c32903c853f6942474",
"md5": "b5b11deef5107f0e7e3d89d6dc022913",
"sha256": "d45d0e3fda6ce5c4bf9eac57c6b94eff5f5ca52424869de5c6b5c89bf323b717"
},
"downloads": -1,
"filename": "pluginlib-0.9.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5b11deef5107f0e7e3d89d6dc022913",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 25365,
"upload_time": "2024-04-15T18:42:40",
"upload_time_iso_8601": "2024-04-15T18:42:40.410354Z",
"url": "https://files.pythonhosted.org/packages/27/93/192a798f2c89f88eea74eb071ce8ddf367d16b8ac6c32903c853f6942474/pluginlib-0.9.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3a18ffd8119bc2fe08fd1b1e7e203f059425ebfb6784add006be0867c088bfdb",
"md5": "d3bf0e70ce888b5f3e8652f76ab5dbc4",
"sha256": "2ad332b6f0115baa9f9e98765c2f325601ef0ec2c60ec37031c2262c2ac611fd"
},
"downloads": -1,
"filename": "pluginlib-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "d3bf0e70ce888b5f3e8652f76ab5dbc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 46748,
"upload_time": "2024-04-15T18:42:41",
"upload_time_iso_8601": "2024-04-15T18:42:41.632997Z",
"url": "https://files.pythonhosted.org/packages/3a/18/ffd8119bc2fe08fd1b1e7e203f059425ebfb6784add006be0867c088bfdb/pluginlib-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-15 18:42:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Rockhopper-Technologies",
"github_project": "pluginlib",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "pluginlib"
}
JSON
