apluggy 0.9.0

A wrapper of "pluggy" to support asyncio and context managers

apluggy

A wrapper of pluggy to support asyncio and context managers.

This package provides a subclass of pluggy.PluginManager that

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

The package also provides asynccontextmanager decorator, which is a wrapper of contextlib.asynccontextmanager to preserve the signature of the decorated function. This decorator is implemented in the same way as contextmanager from the decorator package is implemented.

---

Table of Contents

• apluggy
  • Installation
  • How to use
    • Import packages
    • Create hook specification and implementation decorators
    • Define hook specifications
    • Define plugins
    • Create a plugin manager and register plugins
    • Call hooks
  • Links
  • License
  • Contact

Installation

pip install apluggy

How to use

Import packages

>>> import asyncio
>>> import apluggy as pluggy
>>> from apluggy import asynccontextmanager, contextmanager

(contextmanager is imported from the decorator package.)

Create hook specification and implementation decorators

>>> hookspec = pluggy.HookspecMarker('project')
>>> hookimpl = pluggy.HookimplMarker('project')

(These makers are imported from the pluggy package.)

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()')
...         yield arg1 + arg2
...
...     @hookimpl
...     @asynccontextmanager
...     async def acontext(self, arg1, arg2):
...         print('inside Plugin_1.acontext()')
...         yield arg1 + arg2

>>> 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()')
...         yield arg1 - arg2
...
...     @hookimpl
...     @asynccontextmanager
...     async def acontext(self, arg1, arg2):
...         print('inside Plugin_2.acontext()')
...         yield arg1 - arg2

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.

Call hooks

The following example shows how to call hooks.

>>> 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]

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

>>> 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()
inside Plugin_1.acontext()
[-1, 3]

Links

• pluggy
• decorator

License

• apluggy is licensed under the MIT license.

Contact

• Tai Sakuma