<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>_pytest.hookspec</title>
<link rel="stylesheet" href="../../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '2.3.4.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="top" title="None" href="../../index.html" />
<link rel="up" title="Module code" href="../index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li><a href="../../contents.html">pytest-2.3.4.1</a> »</li>
<li><a href="../index.html" accesskey="U">Module code</a> »</li>
<g:plusone></g:plusone>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3>quicklinks</h3>
<div style="text-align: left; font-size: 100%; vertical-align: middle;">
<table>
<tr>
<td>
<a href="../../index.html">home</a>
</td><td>
<a href="../../contents.html">TOC/contents</a>
</td></tr><tr><td>
<a href="../../getting-started.html">install</a>
</td><td>
<a href="../../changelog.html">changelog</a>
</td></tr><tr><td>
<a href="../../example/index.html">examples</a>
</td><td>
<a href="../../customize.html">customize</a>
</td></tr><tr><td>
<a href="https://bitbucket.org/hpk42/pytest/issues?status=new&status=open">issues[bb]</a>
</td><td>
<a href="../../contact.html">contact</a>
</td></tr></table>
</div>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<h1>Source code for _pytest.hookspec</h1><div class="highlight"><pre>
<span class="sd">""" hook specifications for pytest plugins, invoked from main.py and builtin plugins. """</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># Initialization</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="k">def</span> <span class="nf">pytest_addhooks</span><span class="p">(</span><span class="n">pluginmanager</span><span class="p">):</span>
<span class="sd">"""called at plugin load time to allow adding new hooks via a call to</span>
<span class="sd"> pluginmanager.registerhooks(module)."""</span>
<div class="viewcode-block" id="pytest_namespace"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_namespace">[docs]</a><span class="k">def</span> <span class="nf">pytest_namespace</span><span class="p">():</span>
<span class="sd">"""return dict of name->object to be made globally available in</span>
<span class="sd"> the py.test/pytest namespace. This hook is called before command</span>
<span class="sd"> line options are parsed.</span>
<span class="sd"> """</span>
</div>
<div class="viewcode-block" id="pytest_cmdline_parse"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_cmdline_parse">[docs]</a><span class="k">def</span> <span class="nf">pytest_cmdline_parse</span><span class="p">(</span><span class="n">pluginmanager</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>
<span class="sd">"""return initialized config object, parsing the specified args. """</span></div>
<span class="n">pytest_cmdline_parse</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<div class="viewcode-block" id="pytest_cmdline_preparse"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_cmdline_preparse">[docs]</a><span class="k">def</span> <span class="nf">pytest_cmdline_preparse</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span>
<span class="sd">"""modify command line arguments before option parsing. """</span>
</div>
<div class="viewcode-block" id="pytest_addoption"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_addoption">[docs]</a><span class="k">def</span> <span class="nf">pytest_addoption</span><span class="p">(</span><span class="n">parser</span><span class="p">):</span>
<span class="sd">"""register optparse-style options and ini-style config values.</span>
<span class="sd"> This function must be implemented in a :ref:`plugin <pluginorder>` and is</span>
<span class="sd"> called once at the beginning of a test run.</span>
<span class="sd"> :arg parser: To add command line options, call</span>
<span class="sd"> :py:func:`parser.addoption(...) <_pytest.config.Parser.addoption>`.</span>
<span class="sd"> To add ini-file values call :py:func:`parser.addini(...)</span>
<span class="sd"> <_pytest.config.Parser.addini>`.</span>
<span class="sd"> Options can later be accessed through the</span>
<span class="sd"> :py:class:`config <_pytest.config.Config>` object, respectively:</span>
<span class="sd"> - :py:func:`config.getoption(name) <_pytest.config.Config.getoption>` to</span>
<span class="sd"> retrieve the value of a command line option.</span>
<span class="sd"> - :py:func:`config.getini(name) <_pytest.config.Config.getini>` to retrieve</span>
<span class="sd"> a value read from an ini-style file.</span>
<span class="sd"> The config object is passed around on many internal objects via the ``.config``</span>
<span class="sd"> attribute or can be retrieved as the ``pytestconfig`` fixture or accessed</span>
<span class="sd"> via (deprecated) ``pytest.config``.</span>
<span class="sd"> """</span>
</div>
<div class="viewcode-block" id="pytest_cmdline_main"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_cmdline_main">[docs]</a><span class="k">def</span> <span class="nf">pytest_cmdline_main</span><span class="p">(</span><span class="n">config</span><span class="p">):</span>
<span class="sd">""" called for performing the main command line action. The default</span>
<span class="sd"> implementation will invoke the configure hooks and runtest_mainloop. """</span></div>
<span class="n">pytest_cmdline_main</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<div class="viewcode-block" id="pytest_configure"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_configure">[docs]</a><span class="k">def</span> <span class="nf">pytest_configure</span><span class="p">(</span><span class="n">config</span><span class="p">):</span>
<span class="sd">""" called after command line options have been parsed</span>
<span class="sd"> and all plugins and initial conftest files been loaded.</span>
<span class="sd"> """</span>
</div>
<div class="viewcode-block" id="pytest_unconfigure"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_unconfigure">[docs]</a><span class="k">def</span> <span class="nf">pytest_unconfigure</span><span class="p">(</span><span class="n">config</span><span class="p">):</span>
<span class="sd">""" called before test process is exited. """</span>
</div>
<span class="k">def</span> <span class="nf">pytest_runtestloop</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
<span class="sd">""" called for performing the main runtest loop</span>
<span class="sd"> (after collection finished). """</span>
<span class="n">pytest_runtestloop</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># collection hooks</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="k">def</span> <span class="nf">pytest_collection</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
<span class="sd">""" perform the collection protocol for the given session. """</span>
<span class="n">pytest_collection</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">def</span> <span class="nf">pytest_collection_modifyitems</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">config</span><span class="p">,</span> <span class="n">items</span><span class="p">):</span>
<span class="sd">""" called after collection has been performed, may filter or re-order</span>
<span class="sd"> the items in-place."""</span>
<span class="k">def</span> <span class="nf">pytest_collection_finish</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
<span class="sd">""" called after collection has been performed and modified. """</span>
<div class="viewcode-block" id="pytest_ignore_collect"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_ignore_collect">[docs]</a><span class="k">def</span> <span class="nf">pytest_ignore_collect</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">config</span><span class="p">):</span>
<span class="sd">""" return True to prevent considering this path for collection.</span>
<span class="sd"> This hook is consulted for all files and directories prior to calling</span>
<span class="sd"> more specific hooks.</span>
<span class="sd"> """</span></div>
<span class="n">pytest_ignore_collect</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<div class="viewcode-block" id="pytest_collect_directory"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_collect_directory">[docs]</a><span class="k">def</span> <span class="nf">pytest_collect_directory</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
<span class="sd">""" called before traversing a directory for collection files. """</span></div>
<span class="n">pytest_collect_directory</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<div class="viewcode-block" id="pytest_collect_file"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_collect_file">[docs]</a><span class="k">def</span> <span class="nf">pytest_collect_file</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
<span class="sd">""" return collection Node or None for the given path. Any new node</span>
<span class="sd"> needs to have the specified ``parent`` as a parent."""</span>
<span class="c"># logging hooks for collection</span></div>
<span class="k">def</span> <span class="nf">pytest_collectstart</span><span class="p">(</span><span class="n">collector</span><span class="p">):</span>
<span class="sd">""" collector starts collecting. """</span>
<span class="k">def</span> <span class="nf">pytest_itemcollected</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
<span class="sd">""" we just collected a test item. """</span>
<span class="k">def</span> <span class="nf">pytest_collectreport</span><span class="p">(</span><span class="n">report</span><span class="p">):</span>
<span class="sd">""" collector finished collecting. """</span>
<span class="k">def</span> <span class="nf">pytest_deselected</span><span class="p">(</span><span class="n">items</span><span class="p">):</span>
<span class="sd">""" called for test items deselected by keyword. """</span>
<span class="k">def</span> <span class="nf">pytest_make_collect_report</span><span class="p">(</span><span class="n">collector</span><span class="p">):</span>
<span class="sd">""" perform ``collector.collect()`` and return a CollectReport. """</span>
<span class="n">pytest_make_collect_report</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># Python test function related hooks</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="k">def</span> <span class="nf">pytest_pycollect_makemodule</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">parent</span><span class="p">):</span>
<span class="sd">""" return a Module collector or None for the given path.</span>
<span class="sd"> This hook will be called for each matching test module path.</span>
<span class="sd"> The pytest_collect_file hook needs to be used if you want to</span>
<span class="sd"> create test modules for files that do not match as a test module.</span>
<span class="sd"> """</span>
<span class="n">pytest_pycollect_makemodule</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<div class="viewcode-block" id="pytest_pycollect_makeitem"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_pycollect_makeitem">[docs]</a><span class="k">def</span> <span class="nf">pytest_pycollect_makeitem</span><span class="p">(</span><span class="n">collector</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">obj</span><span class="p">):</span>
<span class="sd">""" return custom item/collector for a python object in a module, or None. """</span></div>
<span class="n">pytest_pycollect_makeitem</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">def</span> <span class="nf">pytest_pyfunc_call</span><span class="p">(</span><span class="n">pyfuncitem</span><span class="p">):</span>
<span class="sd">""" call underlying test function. """</span>
<span class="n">pytest_pyfunc_call</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<div class="viewcode-block" id="pytest_generate_tests"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_generate_tests">[docs]</a><span class="k">def</span> <span class="nf">pytest_generate_tests</span><span class="p">(</span><span class="n">metafunc</span><span class="p">):</span>
<span class="sd">""" generate (multiple) parametrized calls to a test function."""</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># generic runtest related hooks</span>
<span class="c"># -------------------------------------------------------------------------</span></div>
<span class="k">def</span> <span class="nf">pytest_itemstart</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">node</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="sd">""" (deprecated, use pytest_runtest_logstart). """</span>
<div class="viewcode-block" id="pytest_runtest_protocol"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_runtest_protocol">[docs]</a><span class="k">def</span> <span class="nf">pytest_runtest_protocol</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">nextitem</span><span class="p">):</span>
<span class="sd">""" implements the runtest_setup/call/teardown protocol for</span>
<span class="sd"> the given test item, including capturing exceptions and calling</span>
<span class="sd"> reporting hooks.</span>
<span class="sd"> :arg item: test item for which the runtest protocol is performed.</span>
<span class="sd"> :arg nexitem: the scheduled-to-be-next test item (or None if this</span>
<span class="sd"> is the end my friend). This argument is passed on to</span>
<span class="sd"> :py:func:`pytest_runtest_teardown`.</span>
<span class="sd"> :return boolean: True if no further hook implementations should be invoked.</span>
<span class="sd"> """</span></div>
<span class="n">pytest_runtest_protocol</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">def</span> <span class="nf">pytest_runtest_logstart</span><span class="p">(</span><span class="n">nodeid</span><span class="p">,</span> <span class="n">location</span><span class="p">):</span>
<span class="sd">""" signal the start of running a single test item. """</span>
<div class="viewcode-block" id="pytest_runtest_setup"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_runtest_setup">[docs]</a><span class="k">def</span> <span class="nf">pytest_runtest_setup</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
<span class="sd">""" called before ``pytest_runtest_call(item)``. """</span>
</div>
<div class="viewcode-block" id="pytest_runtest_call"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_runtest_call">[docs]</a><span class="k">def</span> <span class="nf">pytest_runtest_call</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
<span class="sd">""" called to execute the test ``item``. """</span>
</div>
<div class="viewcode-block" id="pytest_runtest_teardown"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_runtest_teardown">[docs]</a><span class="k">def</span> <span class="nf">pytest_runtest_teardown</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">nextitem</span><span class="p">):</span>
<span class="sd">""" called after ``pytest_runtest_call``.</span>
<span class="sd"> :arg nexitem: the scheduled-to-be-next test item (None if no further</span>
<span class="sd"> test item is scheduled). This argument can be used to</span>
<span class="sd"> perform exact teardowns, i.e. calling just enough finalizers</span>
<span class="sd"> so that nextitem only needs to call setup-functions.</span>
<span class="sd"> """</span>
</div>
<div class="viewcode-block" id="pytest_runtest_makereport"><a class="viewcode-back" href="../../plugins.html#_pytest.hookspec.pytest_runtest_makereport">[docs]</a><span class="k">def</span> <span class="nf">pytest_runtest_makereport</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">call</span><span class="p">):</span>
<span class="sd">""" return a :py:class:`_pytest.runner.TestReport` object</span>
<span class="sd"> for the given :py:class:`pytest.Item` and</span>
<span class="sd"> :py:class:`_pytest.runner.CallInfo`.</span>
<span class="sd"> """</span></div>
<span class="n">pytest_runtest_makereport</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">def</span> <span class="nf">pytest_runtest_logreport</span><span class="p">(</span><span class="n">report</span><span class="p">):</span>
<span class="sd">""" process a test setup/call/teardown report relating to</span>
<span class="sd"> the respective phase of executing a test. """</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># test session related hooks</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="k">def</span> <span class="nf">pytest_sessionstart</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
<span class="sd">""" before session.main() is called. """</span>
<span class="k">def</span> <span class="nf">pytest_sessionfinish</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">exitstatus</span><span class="p">):</span>
<span class="sd">""" whole test run finishes. """</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># hooks for customising the assert methods</span>
<span class="c"># -------------------------------------------------------------------------</span>
<div class="viewcode-block" id="pytest_assertrepr_compare"><a class="viewcode-back" href="../../assert.html#_pytest.hookspec.pytest_assertrepr_compare">[docs]</a><span class="k">def</span> <span class="nf">pytest_assertrepr_compare</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">op</span><span class="p">,</span> <span class="n">left</span><span class="p">,</span> <span class="n">right</span><span class="p">):</span>
<span class="sd">"""return explanation for comparisons in failing assert expressions.</span>
<span class="sd"> Return None for no custom explanation, otherwise return a list</span>
<span class="sd"> of strings. The strings will be joined by newlines but any newlines</span>
<span class="sd"> *in* a string will be escaped. Note that all but the first line will</span>
<span class="sd"> be indented sligthly, the intention is for the first line to be a summary.</span>
<span class="sd"> """</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># hooks for influencing reporting (invoked from _pytest_terminal)</span>
<span class="c"># -------------------------------------------------------------------------</span>
</div>
<span class="k">def</span> <span class="nf">pytest_report_header</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">startdir</span><span class="p">):</span>
<span class="sd">""" return a string to be displayed as header info for terminal reporting."""</span>
<span class="k">def</span> <span class="nf">pytest_report_teststatus</span><span class="p">(</span><span class="n">report</span><span class="p">):</span>
<span class="sd">""" return result-category, shortletter and verbose word for reporting."""</span>
<span class="n">pytest_report_teststatus</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">def</span> <span class="nf">pytest_terminal_summary</span><span class="p">(</span><span class="n">terminalreporter</span><span class="p">):</span>
<span class="sd">""" add additional section in terminal summary reporting. """</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># doctest hooks</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="k">def</span> <span class="nf">pytest_doctest_prepare_content</span><span class="p">(</span><span class="n">content</span><span class="p">):</span>
<span class="sd">""" return processed content for a given doctest"""</span>
<span class="n">pytest_doctest_prepare_content</span><span class="o">.</span><span class="n">firstresult</span> <span class="o">=</span> <span class="bp">True</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="c"># error handling and internal debugging hooks</span>
<span class="c"># -------------------------------------------------------------------------</span>
<span class="k">def</span> <span class="nf">pytest_plugin_registered</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">manager</span><span class="p">):</span>
<span class="sd">""" a new py lib plugin got registered. """</span>
<span class="k">def</span> <span class="nf">pytest_plugin_unregistered</span><span class="p">(</span><span class="n">plugin</span><span class="p">):</span>
<span class="sd">""" a py lib plugin got unregistered. """</span>
<span class="k">def</span> <span class="nf">pytest_internalerror</span><span class="p">(</span><span class="n">excrepr</span><span class="p">):</span>
<span class="sd">""" called for internal errors. """</span>
<span class="k">def</span> <span class="nf">pytest_keyboard_interrupt</span><span class="p">(</span><span class="n">excinfo</span><span class="p">):</span>
<span class="sd">""" called for keyboard interrupt. """</span>
</pre></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li><a href="../../contents.html">pytest-2.3.4.1</a> »</li>
<li><a href="../index.html" >Module code</a> »</li>
<g:plusone></g:plusone>
</ul>
</div>
<div class="footer">
© Copyright 2012, holger krekel.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-7597274-13']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
</body>
</html>
