1 new commit in pytest: https://bitbucket.org/hpk42/pytest/commits/1abf285d64ae/ Changeset: 1abf285d64ae User: hpk42 Date: 2015-02-27 10:17:14+00:00 Summary: Merged contributing-community into default Affected #: 1 file
diff -r 452d4b637b11f0fb13da045f64bbd35148a73cda -r 1abf285d64ae7fcfaee1fcd01c045357a8a7411b doc/en/plugins.txt --- 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 @@ .. _`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 @@ .. _`extplugins`: Installing External Plugins / Searching ------------------------------------------------------- +--------------------------------------- Installing a plugin happens through any usual Python installation tool, for example:: @@ -119,8 +119,42 @@ .. _`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 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): + +* `<https://github.com/pytest-dev>`_: + probably the most popular hosting for pytest plugins + 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. +* `<https://bitbucket.org/pytest-dev>`_: + 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 `<pytest-...@python.org>`_. + +* 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 @@ -138,7 +172,7 @@ .. _`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 +203,11 @@ ``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: @@ -199,7 +234,7 @@ 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 +249,7 @@ Accessing another plugin by name --------------------------------------------- +-------------------------------- If a plugin wants to collaborate with code from another plugin it can obtain a reference through @@ -230,7 +265,7 @@ .. _`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 +279,7 @@ .. _`cmdunregister`: Deactivating / unregistering a plugin by name ----------------------------------------------------------------------------- +--------------------------------------------- You can prevent plugins from loading or unregister them:: @@ -257,7 +292,7 @@ .. _`builtin plugins`: pytest default plugin reference -==================================== +=============================== You can find the source code for the following plugins @@ -291,10 +326,10 @@ .. _`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 @@ -305,7 +340,7 @@ hook name itself you get an error showing the available arguments. Initialization, command line and configuration hooks --------------------------------------------------------------------- +---------------------------------------------------- .. currentmodule:: _pytest.hookspec @@ -319,7 +354,7 @@ .. autofunction:: pytest_unconfigure Generic "runtest" hooks ------------------------------- +----------------------- All runtest related hooks receive a :py:class:`pytest.Item` object. @@ -339,7 +374,7 @@ the reporting hook to print information about a test run. Collection hooks ------------------------------- +---------------- ``pytest`` calls the following hooks for collecting files and directories: @@ -359,7 +394,7 @@ .. autofunction:: pytest_collection_modifyitems Reporting hooks ------------------------------- +--------------- Session related reporting hooks: @@ -375,7 +410,7 @@ Debugging/Interaction hooks --------------------------------------- +--------------------------- There are few hooks which can be used for special reporting or interaction with exceptions: @@ -468,7 +503,7 @@ Reference of objects involved in hooks -=========================================================== +====================================== .. autoclass:: _pytest.config.Config() :members: Repository URL: https://bitbucket.org/hpk42/pytest/ -- This is a commit notification from bitbucket.org. You are receiving this because you have the service enabled, addressing the recipient of this email. _______________________________________________ pytest-commit mailing list pytest-commit@python.org https://mail.python.org/mailman/listinfo/pytest-commit
