Skip to main content

plugin and hook calling mechanisms for python

Project description

pluggy - A minimalist production ready plugin system

pypi anaconda versions travis appveyor Join the chat at https://gitter.im/pytest-dev/pluggy black

This is the core framework used by the pytest, tox, and devpi projects.

Please read the docs to learn more!

A definitive example

import pluggy

hookspec = pluggy.HookspecMarker("myproject")
hookimpl = pluggy.HookimplMarker("myproject")


class MySpec(object):
    """A hook specification namespace.
    """

    @hookspec
    def myhook(self, arg1, arg2):
        """My special little hook that you can customize.
        """


class Plugin_1(object):
    """A hook implementation namespace.
    """

    @hookimpl
    def myhook(self, arg1, arg2):
        print("inside Plugin_1.myhook()")
        return arg1 + arg2


class Plugin_2(object):
    """A 2nd hook implementation namespace.
    """

    @hookimpl
    def myhook(self, arg1, arg2):
        print("inside Plugin_2.myhook()")
        return arg1 - arg2


# create a manager and add the spec
pm = pluggy.PluginManager("myproject")
pm.add_hookspecs(MySpec)

# register plugins
pm.register(Plugin_1())
pm.register(Plugin_2())

# call our ``myhook`` hook
results = pm.hook.myhook(arg1=1, arg2=2)
print(results)

pluggy 0.8.0 (2018-10-15)

Features

  • #177: Add get_hookimpls() method to hook callers.

Trivial/Internal Changes

  • #165: Add changelog in long package description and documentation.
  • #172: Add a test exemplifying the opt-in nature of spec defined args.
  • #57: Encapsulate hook specifications in a type for easier introspection.

Changelog

pluggy 0.7.1 (2018-07-28)

Deprecations and Removals

  • #116: Deprecate the implprefix kwarg to PluginManager and instead expect users to start using explicit HookimplMarker everywhere.

Features

  • #122: Add .plugin member to PluginValidationError to access failing plugin during post-mortem.
  • #138: Add per implementation warnings support for hookspecs allowing for both deprecation and future warnings of legacy and (future) experimental hooks respectively.

Bug Fixes

  • #110: Fix a bug where _HookCaller.call_historic() would call the proc arg even when the default is None resulting in a TypeError.
  • #160: Fix problem when handling VersionConflict errors when loading setuptools plugins.

Improved Documentation

  • #123: Document how exceptions are handled and how the hook call loop terminates immediately on the first error which is then delivered to any surrounding wrappers.
  • #136: Docs rework including a much better introduction and comprehensive example set for new users. A big thanks goes out to @obestwalter for the great work!

Trivial/Internal Changes

  • #117: Break up the main monolithic package modules into separate modules by concern
  • #131: Automate setuptools wheels building and PyPi upload using TravisCI.
  • #153: Reorganize tests more appropriately by modules relating to each internal component/feature. This is in an effort to avoid (future) duplication and better separation of concerns in the test set.
  • #156: Add HookImpl.__repr__() for better debugging.
  • #66: Start using towncrier and a custom tox environment to prepare releases!

pluggy 0.7.0 (Unreleased)

  • #160: We discovered a deployment issue so this version was never released to PyPI, only the tag exists.

pluggy 0.6.0 (2017-11-24)

  • Add CI testing for the features, release, and master branches of pytest (PR #79).
  • Document public API for _Result objects passed to wrappers (PR #85).
  • Document and test hook LIFO ordering (PR #85).
  • Turn warnings into errors in test suite (PR #89).
  • Deprecate _Result.result (PR #88).
  • Convert _Multicall to a simple function distinguishing it from the legacy version (PR #90).
  • Resolve E741 errors (PR #96).
  • Test and bug fix for unmarked hook collection (PRs #97 and #102).
  • Drop support for EOL Python 2.6 and 3.3 (PR #103).
  • Fix inspect based arg introspection on py3.6 (PR #94).

pluggy 0.5.2 (2017-09-06)

  • fix bug where firstresult wrappers were being sent an incorrectly configured _Result (a list was set instead of a single value). Add tests to check for this as well as _Result.force_result() behaviour. Thanks to @tgoodlet for the PR #72.
  • fix incorrect getattr of DeprecationWarning from the warnings module. Thanks to @nicoddemus for the PR #77.
  • hide pytest tracebacks in certain core routines. Thanks to @nicoddemus for the PR #80.

pluggy 0.5.1 (2017-08-29)

  • fix a bug and add tests for case where firstresult hooks return None results. Thanks to @RonnyPfannschmidt and @tgoodlet for the issue (#68) and PR (#69) respectively.

pluggy 0.5.0 (2017-08-28)

  • fix bug where callbacks for historic hooks would not be called for already registered plugins. Thanks @vodik for the PR and @hpk42 for further fixes.
  • fix #17 by considering only actual functions for hooks this removes the ability to register arbitrary callable objects which at first glance is a reasonable simplification, thanks @RonnyPfannschmidt for report and pr.
  • fix #19: allow registering hookspecs from instances. The PR from @tgoodlet also modernized the varnames implementation.
  • resolve #32: split up the test set into multiple modules. Thanks to @RonnyPfannschmidt for the PR and @tgoodlet for the initial request.
  • resolve #14: add full sphinx docs. Thanks to @tgoodlet for PR #39.
  • add hook call mismatch warnings. Thanks to @tgoodlet for the PR #42.
  • resolve #44: move to new-style classes. Thanks to @MichalTHEDUDE for PR #46.
  • add baseline benchmarking/speed tests using pytest-benchmark in PR #54. Thanks to @tgoodlet.
  • update the README to showcase the API. Thanks to @tgoodlet for the issue and PR #55.
  • deprecate __multicall__ and add a faster call loop implementation. Thanks to @tgoodlet for PR #58.
  • raise a comprehensible error when a hookimpl is called with positional args. Thanks to @RonnyPfannschmidt for the issue and @tgoodlet for PR #60.
  • fix the firstresult test making it more complete and remove a duplicate of that test. Thanks to @tgoodlet for PR #62.

pluggy 0.4.0 (2016-09-25)

  • add has_plugin(name) method to pluginmanager. thanks @nicoddemus.
  • fix #11: make plugin parsing more resilient against exceptions from __getattr__ functions. Thanks @nicoddemus.
  • fix issue #4: specific HookCallError exception for when a hook call provides not enough arguments.
  • better error message when loading setuptools entrypoints fails due to a VersionConflict. Thanks @blueyed.

pluggy 0.3.1 (2015-09-17)

  • avoid using deprecated-in-python3.5 getargspec method. Thanks @mdboom.

pluggy 0.3.0 (2015-05-07)

initial release

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pluggy-0.8.0-py2.py3-none-any.whl (17.2 kB) Copy SHA256 hash SHA256 Wheel py2.py3
pluggy-0.8.0.tar.gz (53.3 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page