prybar: Create temporary pkg_resources
entry points at runtime¶
Use prybar to temporarily define pkg_resources
entry points
at runtime. The primary use case is testing code which works with entry points.
Entry points?¶
Entry points are Python’s way of advertising and consuming plugins. Python packages can advertise an object (function, class, data, etc) which can be discovered and loaded by another package.
Entry points are normally statically defined in package metadata (e.g. via
setup.py
). The static nature of entry points makes thoroughly testing code
that loads entry points awkward.
prybar allows entry points to be created and removed on the fly, making it easy to test your plugin loading code.
Installing¶
prybar is available from PyPi as prybar
:
$ pip install prybar
prybar requires Python 3.6 or greater.
Using prybar¶
prybar provides dynamic_entrypoint()
— a context manager which
creates an entry point when entered and removes it when left. It can also be
used as a function decorator, or via explicit .start()
and .stop()
calls.
Brief Example¶
pkg_resources.iter_entry_points
is the normal way to discover entry points.
We’ll define a function to load the first named entry point in a group
(category).
>>> from pkg_resources import iter_entry_points
>>> def load_entrypoint(group, name):
... return next((ep.load() for ep in
... iter_entry_points(group, name=name)), None)
Initially no entry point will exist:
>>> load_entrypoint('example.hash_types', 'sha256') is None
True
We can create it at runtime with prybar:
>>> from prybar import dynamic_entrypoint
>>> with dynamic_entrypoint('example.hash_types',
... name='sha256', module='hashlib'):
... hash = load_entrypoint('example.hash_types', 'sha256')
... hash(b'foo').hexdigest()[:6]
'2c26b4'
It’s gone again after leaving the with
block:
>>> load_entrypoint('example.hash_types', 'sha256') is None
True
More examples¶
Multiple entry points can be registered by nesting with
blocks, or using
contextlib.ExitStack
:
>>> from contextlib import ExitStack
>>> epoints = [dynamic_entrypoint('example.types',
... name=name, module='builtins')
... for name in ['int', 'float', 'str', 'bool']]
>>> with ExitStack() as stack:
... for ep in epoints:
... stack.enter_context(ep)
...
... for ep in iter_entry_points('example.types'):
... t = ep.load()
... t('12')
12
12.0
'12'
True
dynamic_entrypoint
can also be used as a decorator:
>>> @dynamic_entrypoint('example.hash_types',
... name='sha256', module='hashlib')
... def example_function():
... hash = load_entrypoint('example.hash_types', 'sha256')
... return hash(b'foo').hexdigest()[:6]
>>> load_entrypoint('example.hash_types', 'sha256') is None
True
>>> example_function()
'2c26b4'
And via start()
and stop()
methods:
>>> sha256_dep = dynamic_entrypoint(
... 'example.hash_types', name='sha256', module='hashlib')
>>> load_entrypoint('example.hash_types', 'sha256') is None
True
>>> sha256_dep.start()
>>> hash = load_entrypoint('example.hash_types', 'sha256')
>>> hash(b'foo').hexdigest()[:6]
'2c26b4'
>>> sha256_dep.stop()
>>> load_entrypoint('example.hash_types', 'sha256') is None
True
The entry point can be specified in several ways in addition to the name
and
module
seen above.
attribute
can be used if the desired entry point name differs from the
target’s name in the module:
>>> from collections import Counter
>>> with dynamic_entrypoint('example', name='thing',
... module='collections',
... attribute='Counter'):
... thing = load_entrypoint('example', 'thing')
... thing is Counter
True
A function or class can be passed as entrypoint
, from which the name
,
module
and attribute
are inferred:
>>> with dynamic_entrypoint('example', entrypoint=Counter):
... thing = load_entrypoint('example', 'Counter')
... thing is Counter
True
The name
attribute can be used to override the entry point’s name:
>>> with dynamic_entrypoint('example', name='foo',
... entrypoint=Counter):
... thing = load_entrypoint('example', 'foo')
... thing == Counter
True
Nested functions can be specified:
>>> with dynamic_entrypoint('example', module='collections',
... name='fromkeys',
... attribute=('Counter', 'fromkeys')):
... thing = load_entrypoint('example', 'fromkeys')
... thing == Counter.fromkeys
True
>>> with dynamic_entrypoint('example', entrypoint=Counter.fromkeys):
... thing = load_entrypoint('example', 'fromkeys')
... thing == Counter.fromkeys
True
>>> with dynamic_entrypoint('example', name='foo',
... entrypoint=Counter.fromkeys):
... thing = load_entrypoint('example', 'foo')
... thing == Counter.fromkeys
True
A string using the entry point syntax from setup.py
can be used:
>>> with dynamic_entrypoint(
... 'example',
... entrypoint='thing = collections:Counter.fromkeys'):
... thing = load_entrypoint('example', 'thing')
... thing == Counter.fromkeys
True
Or a pkg_resources.EntryPoint
object can be passed:
>>> from pkg_resources import EntryPoint
>>> ep = EntryPoint('thing', 'collections', attrs=('Counter', 'fromkeys'))
>>> with dynamic_entrypoint('example', entrypoint=ep):
... thing = load_entrypoint('example', 'thing')
... thing == Counter.fromkeys
True