README.rst
1====================================================
2pluggy - A minimalist production ready plugin system
3====================================================
4
5|pypi| |conda-forge| |versions| |travis| |appveyor| |gitter| |black| |codecov|
6
7This is the core framework used by the `pytest`_, `tox`_, and `devpi`_ projects.
8
9Please `read the docs`_ to learn more!
10
11A definitive example
12====================
13.. code-block:: python
14
15 import pluggy
16
17 hookspec = pluggy.HookspecMarker("myproject")
18 hookimpl = pluggy.HookimplMarker("myproject")
19
20
21 class MySpec(object):
22 """A hook specification namespace.
23 """
24
25 @hookspec
26 def myhook(self, arg1, arg2):
27 """My special little hook that you can customize.
28 """
29
30
31 class Plugin_1(object):
32 """A hook implementation namespace.
33 """
34
35 @hookimpl
36 def myhook(self, arg1, arg2):
37 print("inside Plugin_1.myhook()")
38 return arg1 + arg2
39
40
41 class Plugin_2(object):
42 """A 2nd hook implementation namespace.
43 """
44
45 @hookimpl
46 def myhook(self, arg1, arg2):
47 print("inside Plugin_2.myhook()")
48 return arg1 - arg2
49
50
51 # create a manager and add the spec
52 pm = pluggy.PluginManager("myproject")
53 pm.add_hookspecs(MySpec)
54
55 # register plugins
56 pm.register(Plugin_1())
57 pm.register(Plugin_2())
58
59 # call our ``myhook`` hook
60 results = pm.hook.myhook(arg1=1, arg2=2)
61 print(results)
62
63
64Running this directly gets us::
65
66 $ python docs/examples/toy-example.py
67 inside Plugin_2.myhook()
68 inside Plugin_1.myhook()
69 [-1, 3]
70
71
72.. badges
73
74.. |pypi| image:: https://img.shields.io/pypi/v/pluggy.svg
75 :target: https://pypi.org/pypi/pluggy
76
77.. |versions| image:: https://img.shields.io/pypi/pyversions/pluggy.svg
78 :target: https://pypi.org/pypi/pluggy
79
80.. |travis| image:: https://img.shields.io/travis/pytest-dev/pluggy/master.svg
81 :target: https://travis-ci.org/pytest-dev/pluggy
82
83.. |appveyor| image:: https://img.shields.io/appveyor/ci/pytestbot/pluggy/master.svg
84 :target: https://ci.appveyor.com/project/pytestbot/pluggy
85
86.. |conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/pluggy.svg
87 :target: https://anaconda.org/conda-forge/pytest
88
89.. |gitter| image:: https://badges.gitter.im/pytest-dev/pluggy.svg
90 :alt: Join the chat at https://gitter.im/pytest-dev/pluggy
91 :target: https://gitter.im/pytest-dev/pluggy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
92
93.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
94 :target: https://github.com/ambv/black
95
96.. |codecov| image:: https://codecov.io/gh/pytest-dev/pluggy/branch/master/graph/badge.svg
97 :target: https://codecov.io/gh/pytest-dev/pluggy
98 :alt: Code coverage Status
99
100.. links
101.. _pytest:
102 http://pytest.org
103.. _tox:
104 https://tox.readthedocs.org
105.. _devpi:
106 http://doc.devpi.net
107.. _read the docs:
108 https://pluggy.readthedocs.io/en/latest/
109
