apluggy 1.0.1

Description:

apluggy 1.0.1

apluggy





A wrapper of pluggy to support asyncio and context managers.
This package provides a subclass of
pluggy.PluginManager
which

allows async functions, context managers, and async context managers to be hooks
and accepts plugin factories in addition to plugin instances for registration.


Table of Contents

Installation
How to use

Start Python
Import packages
Create hook specification and implementation decorators
Define hook specifications
Define plugins
Create a plugin manager and register plugins
Call hooks

Async function
Context manager
Async context manager




Links
License


Installation
You can install apluggy with pip:
pip install apluggy


How to use
Here, we show a simple example of how to use apluggy.
We only describe the usage of additional features provided by apluggy. For the
usage of pluggy itself, please refer to the pluggy
documentation.
Start Python
You can try this example in a Python interpreter.
$ python
Python 3.10.13 (...)
...
...
>>>

Import packages
Import necessary packages of this example.
>>> import asyncio
>>> import apluggy as pluggy
>>> from apluggy import asynccontextmanager, contextmanager

In this example, apluggy is imported with the alias pluggy.
The decorators asynccontextmanager and contextmanager are imported from
apluggy. They are wrappers of the decorators of the same names in the
contextlib package. The
wrappers preserve the signatures of decorated functions, which are necessary for
pluggy to pass arguments to hook implementations correctly. (The decorator
contextmanger in apluggy is the same object as the decorator
contextmanager in the decorator
package. The decorator package does not
provide asynccontextmanager decorator as of version 5.1. The decorator
asynccontextmanger in apluggy is implemented in a similar way as the
decorator contextmanager in the decorator package.)
Create hook specification and implementation decorators
>>> hookspec = pluggy.HookspecMarker('project')
>>> hookimpl = pluggy.HookimplMarker('project')

Define hook specifications
In this example, we define three hooks: async function, context manager, and
async context manager.
>>> class Spec:
... """A hook specification namespace."""
...
... @hookspec
... async def afunc(self, arg1, arg2):
... pass
...
... @hookspec
... @contextmanager
... def context(self, arg1, arg2):
... pass
...
... @hookspec
... @asynccontextmanager
... async def acontext(self, arg1, arg2):
... pass

Define plugins
We define two plugins as classes. Each plugin implements the three hooks
defined above.
>>> class Plugin_1:
... """A hook implementation namespace."""
...
... @hookimpl
... async def afunc(self, arg1, arg2):
... print('inside Plugin_1.afunc()')
... return arg1 + arg2
...
... @hookimpl
... @contextmanager
... def context(self, arg1, arg2):
... print('inside Plugin_1.context(): before')
... yield arg1 + arg2
... print('inside Plugin_1.context(): after')
...
... @hookimpl
... @asynccontextmanager
... async def acontext(self, arg1, arg2):
... print('inside Plugin_1.acontext(): before')
... yield arg1 + arg2
... print('inside Plugin_1.acontext(): after')

>>> class Plugin_2:
... """A 2nd hook implementation namespace."""
...
... @hookimpl
... async def afunc(self, arg1, arg2):
... print('inside Plugin_2.afunc()')
... return arg1 - arg2
...
... @hookimpl
... @contextmanager
... def context(self, arg1, arg2):
... print('inside Plugin_2.context(): before')
... yield arg1 - arg2
... print('inside Plugin_2.context(): after')
...
... @hookimpl
... @asynccontextmanager
... async def acontext(self, arg1, arg2):
... print('inside Plugin_2.acontext(): before')
... yield arg1 - arg2
... print('inside Plugin_2.acontext(): after')

Create a plugin manager and register plugins
Plugins can be registered as instances or factories. In the following
example, we register two plugins: Plugin_1 as an instance, and Plugin_2
as a factory.
>>> pm = pluggy.PluginManager('project')
>>> pm.add_hookspecs(Spec)
>>> _ = pm.register(Plugin_1()) # instantiation is optional.
>>> _ = pm.register(Plugin_2) # callable is considered a plugin factory.

Pluggy accepts a class or
module as a
plugin. However, it actually accepts a class instance, not a class itself.
Consequently, when plugins are loaded with
load_setuptools_entrypoints(),
the entry points must be class instances or modules. Classes themselves cannot
be used as entry points (if understood correctly).
So that classes themselves can be entry points, apluggy accepts a class itself for
a plugin registration. When apluggy receives a callable object, apluggy considers
the object as a plugin factory.
Call hooks
The following example shows how to call hooks.
Async function
>>> async def call_afunc():
... results = await pm.ahook.afunc(arg1=1, arg2=2) # ahook instead of hook
... print(results)

>>> asyncio.run(call_afunc())
inside Plugin_2.afunc()
inside Plugin_1.afunc()
[-1, 3]

Context manager
>>> with pm.with_.context(arg1=1, arg2=2) as y: # with_ instead of hook
... print(y)
inside Plugin_2.context(): before
inside Plugin_1.context(): before
[-1, 3]
inside Plugin_1.context(): after
inside Plugin_2.context(): after

In the reverse order:
>>> with pm.with_reverse.context(arg1=1, arg2=2) as y: # with_reverse instead of hook
... print(y)
inside Plugin_1.context(): before
inside Plugin_2.context(): before
[3, -1]
inside Plugin_2.context(): after
inside Plugin_1.context(): after

Async context manager
>>> async def call_acontext():
... async with pm.awith.acontext(arg1=1, arg2=2) as y: # awith instead of hook
... print(y)

>>> asyncio.run(call_acontext())
inside Plugin_2.acontext(): before
inside Plugin_1.acontext(): before
[-1, 3]
inside Plugin_1.acontext(): after
inside Plugin_2.acontext(): after

In the reverse order:
>>> async def call_acontext():
... async with pm.awith_reverse.acontext(arg1=1, arg2=2) as y: # awith_reverse instead of hook
... print(y)

>>> asyncio.run(call_acontext())
inside Plugin_1.acontext(): before
inside Plugin_2.acontext(): before
[3, -1]
inside Plugin_2.acontext(): after
inside Plugin_1.acontext(): after


Links

pluggy
decorator


License

apluggy is licensed under the MIT license.