From 54e00429e4368d3241da5ba5decfca4d32c024f3 Mon Sep 17 00:00:00 2001 From: Anatoly Bubenkov Date: Wed, 20 Aug 2014 00:52:40 +0200 Subject: [PATCH 1/3] plugin organization proposal --HG-- branch : contributing-community --- doc/en/plugins.txt | 47 ++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index a6c57a430..4aaea206a 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -1,7 +1,7 @@ .. _plugins: Working with plugins and conftest files -============================================= +======================================= ``pytest`` implements all aspects of configuration, collection, running and reporting by calling `well specified hooks`_. Virtually any Python module can be registered as a plugin. It can implement any number of hook functions (usually two or three) which all have a ``pytest_`` prefix, making hook functions easy to distinguish and find. There are three basic location types: @@ -16,7 +16,7 @@ Working with plugins and conftest files .. _`conftest`: conftest.py: local per-directory plugins --------------------------------------------------------------- +---------------------------------------- local ``conftest.py`` plugins contain directory-specific hook implementations. Session and test running activities will @@ -55,7 +55,7 @@ Here is how you might run it:: .. _`extplugins`: Installing External Plugins / Searching ------------------------------------------------------- +--------------------------------------- Installing a plugin happens through any usual Python installation tool, for example:: @@ -119,6 +119,16 @@ You may also discover more plugins through a `pytest- pypi.python.org search`_. .. _`available installable plugins`: .. _`pytest- pypi.python.org search`: http://pypi.python.org/pypi?%3Aaction=search&term=pytest-&submit=search + +External plugin development +--------------------------- + +Pytest community cares about pytest users, in particular, it's important for the community +to keep all pieces of the pytest ecosystem supported. External plugins are important for +pytest users, as they implement many useful, and sometimes critical features which the pytest core does +not implement. + + Writing a plugin by looking at examples ------------------------------------------------------ @@ -138,7 +148,7 @@ to extend and add functionality. .. _`setuptools entry points`: Making your plugin installable by others ------------------------------------------------ +---------------------------------------- If you want to make your plugin externally available, you may define a so-called entry point for your distribution so @@ -169,10 +179,11 @@ If a package is installed this way, ``pytest`` will load ``myproject.pluginmodule`` as a plugin which can define `well specified hooks`_. + .. _`pluginorder`: Plugin discovery order at tool startup --------------------------------------------- +-------------------------------------- ``pytest`` loads plugin modules at tool startup in the following way: @@ -187,8 +198,8 @@ Plugin discovery order at tool startup invocation: - if no test paths are specified use current dir as a test path - - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative - to the directory part of the first test path. + - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative + to the directory part of the first test path. Note that pytest does not find ``conftest.py`` files in deeper nested sub directories at tool startup. It is usually a good idea to keep @@ -199,7 +210,7 @@ Plugin discovery order at tool startup Requiring/Loading plugins in a test module or conftest file -------------------------------------------------------------- +----------------------------------------------------------- You can require plugins in a test module or a conftest file like this:: @@ -214,7 +225,7 @@ which will import the specified module as a ``pytest`` plugin. Accessing another plugin by name --------------------------------------------- +-------------------------------- If a plugin wants to collaborate with code from another plugin it can obtain a reference through @@ -230,7 +241,7 @@ the ``--traceconfig`` option. .. _`findpluginname`: Finding out which plugins are active ----------------------------------------------------------------------------- +------------------------------------ If you want to find out which plugins are active in your environment you can type:: @@ -244,7 +255,7 @@ and their names. It will also print local plugins aka .. _`cmdunregister`: Deactivating / unregistering a plugin by name ----------------------------------------------------------------------------- +--------------------------------------------- You can prevent plugins from loading or unregister them:: @@ -257,7 +268,7 @@ how to obtain the name of a plugin. .. _`builtin plugins`: pytest default plugin reference -==================================== +=============================== You can find the source code for the following plugins @@ -305,7 +316,7 @@ by simply not specifying them. If you mistype argument names or the hook name itself you get an error showing the available arguments. Initialization, command line and configuration hooks --------------------------------------------------------------------- +---------------------------------------------------- .. currentmodule:: _pytest.hookspec @@ -319,7 +330,7 @@ Initialization, command line and configuration hooks .. autofunction:: pytest_unconfigure Generic "runtest" hooks ------------------------------- +----------------------- All runtest related hooks receive a :py:class:`pytest.Item` object. @@ -339,7 +350,7 @@ The :py:mod:`_pytest.terminal` reported specifically uses the reporting hook to print information about a test run. Collection hooks ------------------------------- +---------------- ``pytest`` calls the following hooks for collecting files and directories: @@ -359,7 +370,7 @@ items, delete or otherwise amend the test items: .. autofunction:: pytest_collection_modifyitems Reporting hooks ------------------------------- +--------------- Session related reporting hooks: @@ -375,7 +386,7 @@ test execution: Debugging/Interaction hooks --------------------------------------- +--------------------------- There are few hooks which can be used for special reporting or interaction with exceptions: @@ -385,7 +396,7 @@ reporting or interaction with exceptions: .. autofunction:: pytest_exception_interact Reference of objects involved in hooks -=========================================================== +====================================== .. autoclass:: _pytest.config.Config() :members: From 8844d9d04f37f911105f5160ddc7e0fd7c77a19f Mon Sep 17 00:00:00 2001 From: Anatoly Bubenkov Date: Sat, 6 Sep 2014 02:37:48 +0200 Subject: [PATCH 2/3] detalize the plugin development proposal --HG-- branch : contributing-community --- doc/en/plugins.txt | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 4aaea206a..18aec7cc0 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -123,14 +123,38 @@ You may also discover more plugins through a `pytest- pypi.python.org search`_. External plugin development --------------------------- -Pytest community cares about pytest users, in particular, it's important for the community -to keep all pieces of the pytest ecosystem supported. External plugins are important for +Pytest community cares about pytest users, in particular, it's crucial for the community +to keep all pieces of the pytest ecosystem well supported. External plugins are important for pytest users, as they implement many useful, and sometimes critical features which the pytest core does not implement. +To simplify the plugin development and/or support, it was decided to create teams(companies) on popular code hosting +services (at the moment it's github and bitbucket): + +* ``_: + probably the most popular hosting for pytest plugins + the name ``pytestorg`` is choosen because ``pytest`` was already taken by + some unknown person, who's not active on the github or just doesn't check the email used to register + that organization. +* ``_: + pytest is hosted on the bitbucket, also a lot of pytest plugins are hosted there. + +More code hosting services can be added in the future. + +Community encourages pytest plugin developers to move their plugins under those organizations (eg transfer ownership), +paying with a better support, faster feedback, better discoverability, etc. + +Generic workflow of the ownership transfer looks like: + +* If not a member already, developer asks for a membership in the `pytest plugin developers community` organizations listed above, sending an email to ``_. + +* Developer transfers the ownership of his plugin repository to the organization listed above. + +* Existing organization members will make sure proper write permissions are set up for developer who transfered the ownership to the organization. + Writing a plugin by looking at examples ------------------------------------------------------- +--------------------------------------- .. _`Distribute`: http://pypi.python.org/pypi/distribute .. _`setuptools`: http://pypi.python.org/pypi/setuptools @@ -302,10 +326,10 @@ in the `pytest repository `_. .. _`well specified hooks`: pytest hook reference -==================================== +===================== Hook specification and validation ------------------------------------------ +--------------------------------- ``pytest`` calls hook functions to implement initialization, running, test execution and reporting. When ``pytest`` loads a plugin it validates From d99243c1a77ab02430ef1ca33fc9ae733c336d3d Mon Sep 17 00:00:00 2001 From: Anatoly Bubenkov Date: Wed, 24 Sep 2014 10:53:08 +0000 Subject: [PATCH 3/3] rename orgname to pytest-dev --HG-- branch : contributing-community --- doc/en/plugins.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt index 18aec7cc0..2adf35286 100644 --- a/doc/en/plugins.txt +++ b/doc/en/plugins.txt @@ -131,12 +131,12 @@ not implement. To simplify the plugin development and/or support, it was decided to create teams(companies) on popular code hosting services (at the moment it's github and bitbucket): -* ``_: +* ``_: probably the most popular hosting for pytest plugins - the name ``pytestorg`` is choosen because ``pytest`` was already taken by + the name ``pytest-dev`` is choosen because ``pytest`` was already taken by some unknown person, who's not active on the github or just doesn't check the email used to register that organization. -* ``_: +* ``_: pytest is hosted on the bitbucket, also a lot of pytest plugins are hosted there. More code hosting services can be added in the future.