holger krekel avatar holger krekel committed 0eaa0fd

update docs, leave out internal plugins

Comments (0)

Files changed (23)

     border-bottom: 1px solid #8CACBB;
 }
 
+h2 {
+    border-bottom: 1px dotted #8CACBB;
+}
+
 
 h1, h2, h3, h4, h5, h6 {
     color: Black;
 
 
 h1 { font-size: 145%; }
-h2 { font-size: 135%; }
-h3 { font-size: 125%; }
-h4 { font-size: 120%; }
-h5 { font-size: 110%; }
-h6 { font-size: 80%; }
+h2 { font-size: 115%; }
+h3 { font-size: 105%; }
+h4 { font-size: 100%; }
+h5 { font-size: 100%; }
 
 h1 a { text-decoration: None;}
 

doc/test/plugin/doctest.txt

 
 collect and execute doctests from modules and test files.
 
+.. contents::
+  :local:
+
 Usage
 -------------
 
 ``--doctest-modules``
     search all python files for doctests
 
-Getting and improving this plugin
----------------------------------
+Start improving this plugin in 30 seconds
+=========================================
 
 
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
+Do you find the above documentation or the plugin itself lacking? 
 
 1. Download `pytest_doctest.py`_ plugin source code 
 2. put it somewhere as ``pytest_doctest.py`` into your import path 
-3. a subsequent test run will now use your local version! 
+3. a subsequent ``py.test`` run will use your local version
 
 Further information: extend_ documentation, other plugins_ or contact_.  
 
-For your convenience here is also an inlined version of ``pytest_doctest.py``:
-
-.. sourcecode:: python
-
-    """
-    collect and execute doctests from modules and test files. 
-    
-    Usage
-    -------------
-    
-    By default all files matching the ``test_*.txt`` pattern will 
-    be run with the ``doctest`` module.  If you issue::
-    
-        py.test --doctest-modules
-    
-    all python files in your projects will be doctest-run 
-    as well. 
-    """
-    
-    import py
-    from py.__.code.excinfo import Repr, ReprFileLocation
-    
-    def pytest_addoption(parser):
-        group = parser.addgroup("doctest options")
-        group.addoption("--doctest-modules", 
-            action="store_true", default=False,
-            help="search all python files for doctests", 
-            dest="doctestmodules")
-        
-    def pytest_collect_file(path, parent):
-        if path.ext == ".py":
-            if parent.config.getvalue("doctestmodules"):
-                return DoctestModule(path, parent)
-        if path.check(fnmatch="test_*.txt"):
-            return DoctestTextfile(path, parent)
-    
-    class ReprFailDoctest(Repr):
-        def __init__(self, reprlocation, lines):
-            self.reprlocation = reprlocation
-            self.lines = lines
-        def toterminal(self, tw):
-            for line in self.lines:
-                tw.line(line)
-            self.reprlocation.toterminal(tw)
-                 
-    class DoctestItem(py.test.collect.Item):
-        def __init__(self, path, parent):
-            name = self.__class__.__name__ + ":" + path.basename
-            super(DoctestItem, self).__init__(name=name, parent=parent)
-            self.fspath = path 
-    
-        def repr_failure(self, excinfo, outerr):
-            if excinfo.errisinstance(py.compat.doctest.DocTestFailure):
-                doctestfailure = excinfo.value
-                example = doctestfailure.example
-                test = doctestfailure.test
-                filename = test.filename 
-                lineno = test.lineno + example.lineno + 1
-                message = excinfo.type.__name__
-                reprlocation = ReprFileLocation(filename, lineno, message)
-                checker = py.compat.doctest.OutputChecker() 
-                REPORT_UDIFF = py.compat.doctest.REPORT_UDIFF
-                filelines = py.path.local(filename).readlines(cr=0)
-                i = max(test.lineno, max(0, lineno - 10)) # XXX? 
-                lines = []
-                for line in filelines[i:lineno]:
-                    lines.append("%03d %s" % (i+1, line))
-                    i += 1
-                lines += checker.output_difference(example, 
-                        doctestfailure.got, REPORT_UDIFF).split("\n")
-                return ReprFailDoctest(reprlocation, lines)
-            elif excinfo.errisinstance(py.compat.doctest.UnexpectedException):
-                excinfo = py.code.ExceptionInfo(excinfo.value.exc_info)
-                return super(DoctestItem, self).repr_failure(excinfo, outerr)
-            else: 
-                return super(DoctestItem, self).repr_failure(excinfo, outerr)
-    
-    class DoctestTextfile(DoctestItem):
-        def runtest(self):
-            if not self._deprecated_testexecution():
-                failed, tot = py.compat.doctest.testfile(
-                    str(self.fspath), module_relative=False, 
-                    raise_on_error=True, verbose=0)
-    
-    class DoctestModule(DoctestItem):
-        def runtest(self):
-            module = self.fspath.pyimport()
-            failed, tot = py.compat.doctest.testmod(
-                module, raise_on_error=True, verbose=0)
-    
-    
-    #
-    # Plugin tests
-    #
-    
-    class TestDoctests:
-    
-        def test_collect_testtextfile(self, testdir):
-            testdir.maketxtfile(whatever="")
-            checkfile = testdir.maketxtfile(test_something="""
-                alskdjalsdk
-                >>> i = 5
-                >>> i-1
-                4
-            """)
-            for x in (testdir.tmpdir, checkfile): 
-                #print "checking that %s returns custom items" % (x,) 
-                items, reprec = testdir.inline_genitems(x)
-                assert len(items) == 1
-                assert isinstance(items[0], DoctestTextfile)
-    
-        def test_collect_module(self, testdir):
-            path = testdir.makepyfile(whatever="#")
-            for p in (path, testdir.tmpdir): 
-                items, reprec = testdir.inline_genitems(p, '--doctest-modules')
-                assert len(items) == 1
-                assert isinstance(items[0], DoctestModule)
-    
-        def test_simple_doctestfile(self, testdir):
-            p = testdir.maketxtfile(test_doc="""
-                >>> x = 1
-                >>> x == 1
-                False
-            """)
-            reprec = testdir.inline_run(p)
-            reprec.assertoutcome(failed=1)
-    
-        def test_doctest_unexpected_exception(self, testdir):
-            from py.__.test.outcome import Failed 
-    
-            p = testdir.maketxtfile("""
-                >>> i = 0
-                >>> i = 1 
-                >>> x
-                2
-            """)
-            reprec = testdir.inline_run(p)
-            call = reprec.getcall("pytest_runtest_logreport")
-            assert call.rep.failed
-            assert call.rep.longrepr 
-            # XXX 
-            #testitem, = items
-            #excinfo = py.test.raises(Failed, "testitem.runtest()")
-            #repr = testitem.repr_failure(excinfo, ("", ""))
-            #assert repr.reprlocation 
-    
-        def test_doctestmodule(self, testdir):
-            p = testdir.makepyfile("""
-                '''
-                    >>> x = 1
-                    >>> x == 1
-                    False
-    
-                '''
-            """)
-            reprec = testdir.inline_run(p, "--doctest-modules")
-            reprec.assertoutcome(failed=1) 
-    
-        def test_doctestmodule_external(self, testdir):
-            p = testdir.makepyfile("""
-                #
-                def somefunc():
-                    '''
-                        >>> i = 0
-                        >>> i + 1
-                        2
-                    '''
-            """)
-            result = testdir.runpytest(p, "--doctest-modules")
-            result.stdout.fnmatch_lines([
-                '004 *>>> i = 0',
-                '005 *>>> i + 1',
-                '*Expected:',
-                "*    2",
-                "*Got:",
-                "*    1",
-                "*:5: DocTestFailure"
-            ])
-            
-    
-        def test_txtfile_failing(self, testdir):
-            p = testdir.maketxtfile("""
-                >>> i = 0
-                >>> i + 1
-                2
-            """)
-            result = testdir.runpytest(p)
-            result.stdout.fnmatch_lines([
-                '001 >>> i = 0',
-                '002 >>> i + 1',
-                'Expected:',
-                "    2",
-                "Got:",
-                "    1",
-                "*test_txtfile_failing.txt:2: DocTestFailure"
-            ])
-
-.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_doctest.py
+.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/85fe614ab05f301f206935d11a477df184cbbce6/py/test/plugin/pytest_doctest.py
 .. _`extend`: ../extend.html
 .. _`plugins`: index.html
 .. _`contact`: ../../contact.html

doc/test/plugin/execnetcleanup.txt

-
-pytest_execnetcleanup plugin
-============================
-
-cleanup execnet gateways during test function runs.
-
-
-
-Getting and improving this plugin
----------------------------------
-
-
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
-
-1. Download `pytest_execnetcleanup.py`_ plugin source code 
-2. put it somewhere as ``pytest_execnetcleanup.py`` into your import path 
-3. a subsequent test run will now use your local version! 
-
-Further information: extend_ documentation, other plugins_ or contact_.  
-
-For your convenience here is also an inlined version of ``pytest_execnetcleanup.py``:
-
-.. sourcecode:: python
-
-    """
-    cleanup execnet gateways during test function runs.
-    """
-    import py
-    
-    pytest_plugins = "xfail"
-    
-    def pytest_configure(config):
-        config.pluginmanager.register(Execnetcleanup())
-    
-    class Execnetcleanup:
-        _gateways = None
-        def __init__(self, debug=False):
-            self._debug = debug 
-    
-        def pyexecnet_gateway_init(self, gateway):
-            if self._gateways is not None:
-                self._gateways.append(gateway)
-            
-        def pyexecnet_gateway_exit(self, gateway):
-            if self._gateways is not None:
-                self._gateways.remove(gateway)
-    
-        def pytest_sessionstart(self, session):
-            self._gateways = []
-    
-        def pytest_sessionfinish(self, session, exitstatus):
-            l = []
-            for gw in self._gateways:
-                gw.exit()
-                l.append(gw)
-            #for gw in l:
-            #    gw.join()
-            
-        def pytest_pyfunc_call(self, __call__, pyfuncitem):
-            if self._gateways is not None:
-                gateways = self._gateways[:]
-                res = __call__.execute(firstresult=True)
-                while len(self._gateways) > len(gateways):
-                    self._gateways[-1].exit()
-                return res
-      
-    def test_execnetplugin(testdir):
-        reprec = testdir.inline_runsource("""
-            import py
-            import sys
-            def test_hello():
-                sys._gw = py.execnet.PopenGateway()
-            def test_world():
-                assert hasattr(sys, '_gw')
-                py.test.raises(KeyError, "sys._gw.exit()") # already closed 
-                
-        """, "-s", "--debug")
-        reprec.assertoutcome(passed=2)
-
-.. _`pytest_execnetcleanup.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_execnetcleanup.py
-.. _`extend`: ../extend.html
-.. _`plugins`: index.html
-.. _`contact`: ../../contact.html
-.. _`checkout the py.test development version`: ../../download.html#checkout

doc/test/plugin/figleaf.txt

 
 write and report coverage data with 'figleaf'.
 
+.. contents::
+  :local:
+
 
 
 command line options
 ``--figleaf-html=FIGLEAFHTML``
     path to the coverage html dir.
 
-Getting and improving this plugin
----------------------------------
+Start improving this plugin in 30 seconds
+=========================================
 
 
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
+Do you find the above documentation or the plugin itself lacking? 
 
 1. Download `pytest_figleaf.py`_ plugin source code 
 2. put it somewhere as ``pytest_figleaf.py`` into your import path 
-3. a subsequent test run will now use your local version! 
+3. a subsequent ``py.test`` run will use your local version
 
 Further information: extend_ documentation, other plugins_ or contact_.  
 
-For your convenience here is also an inlined version of ``pytest_figleaf.py``:
-
-.. sourcecode:: python
-
-    """
-    write and report coverage data with 'figleaf'. 
-    
-    """
-    import py
-    
-    figleaf = py.test.importorskip("figleaf.annotate_html")
-    
-    def pytest_addoption(parser):
-        group = parser.addgroup('figleaf options')
-        group.addoption('-F', action='store_true', default=False,
-                dest = 'figleaf',
-                help=('trace python coverage with figleaf and write HTML '
-                     'for files below the current working dir'))
-        group.addoption('--figleaf-data', action='store', default='.figleaf',
-                dest='figleafdata',
-                help='path to coverage tracing file.')
-        group.addoption('--figleaf-html', action='store', default='html',
-                dest='figleafhtml', 
-                help='path to the coverage html dir.')
-    
-    def pytest_configure(config):
-        figleaf.start()
-    
-    def pytest_terminal_summary(terminalreporter):
-        config = terminalreporter.config
-        datafile = py.path.local(config.getvalue('figleafdata'))
-        tw = terminalreporter._tw
-        tw.sep('-', 'figleaf')
-        tw.line('Writing figleaf data to %s' % (datafile))
-        figleaf.stop()
-        figleaf.write_coverage(str(datafile))
-        coverage = get_coverage(datafile, config)
-        reportdir = py.path.local(config.getvalue('figleafhtml'))
-        tw.line('Writing figleaf html to file://%s' % (reportdir))
-        figleaf.annotate_html.prepare_reportdir(str(reportdir))
-        exclude = []
-        figleaf.annotate_html.report_as_html(coverage, 
-                str(reportdir), exclude, {})
-    
-    def get_coverage(datafile, config):
-        # basepath = config.topdir
-        basepath = py.path.local()
-        data = figleaf.read_coverage(str(datafile))
-        d = {}
-        coverage = figleaf.combine_coverage(d, data)
-        for path in coverage.keys():
-            if not py.path.local(path).relto(basepath):
-                del coverage[path]
-        return coverage
-    
-    
-    def test_functional(testdir):
-        py.test.importorskip("figleaf")
-        testdir.plugins.append("figleaf")
-        testdir.makepyfile("""
-            def f():    
-                x = 42
-            def test_whatever():
-                pass
-            """)
-        result = testdir.runpytest('-F')
-        assert result.ret == 0
-        assert result.stdout.fnmatch_lines([
-            '*figleaf html*'
-            ])
-        #print result.stdout.str()
-
-.. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_figleaf.py
+.. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/85fe614ab05f301f206935d11a477df184cbbce6/py/test/plugin/pytest_figleaf.py
 .. _`extend`: ../extend.html
 .. _`plugins`: index.html
 .. _`contact`: ../../contact.html

doc/test/plugin/hooklog.txt

-
-pytest_hooklog plugin
-=====================
-
-log invocations of extension hooks to a file.
-
-
-
-command line options
---------------------
-
-
-``--hooklog=HOOKLOG``
-    write hook calls to the given file.
-
-Getting and improving this plugin
----------------------------------
-
-
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
-
-1. Download `pytest_hooklog.py`_ plugin source code 
-2. put it somewhere as ``pytest_hooklog.py`` into your import path 
-3. a subsequent test run will now use your local version! 
-
-Further information: extend_ documentation, other plugins_ or contact_.  
-
-For your convenience here is also an inlined version of ``pytest_hooklog.py``:
-
-.. sourcecode:: python
-
-    """ log invocations of extension hooks to a file. """ 
-    import py
-    
-    def pytest_addoption(parser):
-        parser.addoption("--hooklog", dest="hooklog", default=None, 
-            help="write hook calls to the given file.")
-    
-    def pytest_configure(config):
-        hooklog = config.getvalue("hooklog")
-        if hooklog:
-            assert not config.pluginmanager.comregistry.logfile
-            config.pluginmanager.comregistry.logfile = open(hooklog, 'w')
-    
-    def pytest_unconfigure(config):
-        f = config.pluginmanager.comregistry.logfile
-        if f:
-            f.close()
-            config.pluginmanager.comregistry.logfile = None
-    
-    # ===============================================================================
-    # plugin tests 
-    # ===============================================================================
-    
-    def test_functional(testdir):
-        testdir.makepyfile("""
-            def test_pass():
-                pass
-        """)
-        testdir.runpytest("--hooklog=hook.log")
-        s = testdir.tmpdir.join("hook.log").read()
-        assert s.find("pytest_sessionstart") != -1
-        assert s.find("ItemTestReport") != -1
-        assert s.find("sessionfinish") != -1
-
-.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_hooklog.py
-.. _`extend`: ../extend.html
-.. _`plugins`: index.html
-.. _`contact`: ../../contact.html
-.. _`checkout the py.test development version`: ../../download.html#checkout

doc/test/plugin/index.txt

 
 monkeypatch_ safely patch object attributes, dicts and environment variables.
 
-iocapture_ convenient capturing of writes to stdout/stderror streams
+iocapture_ convenient capturing of writes to stdout/stderror streams and file descriptors.
 
 recwarn_ helpers for asserting deprecation and other warnings.
 
 
 resultlog_ resultlog plugin for machine-readable logging of test results.
 
-terminal_ terminal reporting of the full testing process.
-
-
-internal plugins / core functionality
-=====================================
-
-pdb_ interactive debugging with the Python Debugger.
-
-keyword_ py.test.mark / keyword plugin
-
-hooklog_ log invocations of extension hooks to a file.
-
-runner_ collect and run test items and create reports.
-
-execnetcleanup_ cleanup execnet gateways during test function runs.
-
-pytester_ funcargs and support code for testing py.test's own functionality.
+terminal_ Implements terminal reporting of the full testing process.
 
 
 .. _`xfail`: xfail.html
 .. _`pocoo`: pocoo.html
 .. _`resultlog`: resultlog.html
 .. _`terminal`: terminal.html
-.. _`pdb`: pdb.html
-.. _`keyword`: keyword.html
-.. _`hooklog`: hooklog.html
-.. _`runner`: runner.html
-.. _`execnetcleanup`: execnetcleanup.html
-.. _`pytester`: pytester.html

doc/test/plugin/iocapture.txt

 pytest_iocapture plugin
 =======================
 
-convenient capturing of writes to stdout/stderror streams
+convenient capturing of writes to stdout/stderror streams and file descriptors.
 
-and file descriptors. 
+.. contents::
+  :local:
 
 Example Usage
 ----------------------
 capturing so that you can successively check for output. 
 After the test function finishes the original streams
 will be restored.
+
 .. _`capsys funcarg`:
 
 
 captures writes to sys.stdout/sys.stderr and makes 
 them available successively via a ``capsys.reset()`` method 
 which returns a ``(out, err)`` tuple of captured strings. 
+
 .. _`capfd funcarg`:
 
 
 them available successively via a ``capsys.reset()`` method 
 which returns a ``(out, err)`` tuple of captured strings. 
 
-Getting and improving this plugin
----------------------------------
+Start improving this plugin in 30 seconds
+=========================================
 
 
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
+Do you find the above documentation or the plugin itself lacking? 
 
 1. Download `pytest_iocapture.py`_ plugin source code 
 2. put it somewhere as ``pytest_iocapture.py`` into your import path 
-3. a subsequent test run will now use your local version! 
+3. a subsequent ``py.test`` run will use your local version
 
 Further information: extend_ documentation, other plugins_ or contact_.  
 
-For your convenience here is also an inlined version of ``pytest_iocapture.py``:
-
-.. sourcecode:: python
-
-    """
-    convenient capturing of writes to stdout/stderror streams 
-    and file descriptors. 
-    
-    Example Usage
-    ----------------------
-    
-    You can use the `capsys funcarg`_ to capture writes 
-    to stdout and stderr streams by using it in a test 
-    likes this:
-    
-    .. sourcecode:: python
-    
-        def test_myoutput(capsys):
-            print "hello" 
-            print >>sys.stderr, "world"
-            out, err = capsys.reset()
-            assert out == "hello\\n"
-            assert err == "world\\n"
-            print "next"
-            out, err = capsys.reset()
-            assert out == "next\\n" 
-    
-    The ``reset()`` call returns a tuple and will restart 
-    capturing so that you can successively check for output. 
-    After the test function finishes the original streams
-    will be restored. 
-    """
-    
-    import py
-    
-    def pytest_funcarg__capsys(request):
-        """captures writes to sys.stdout/sys.stderr and makes 
-        them available successively via a ``capsys.reset()`` method 
-        which returns a ``(out, err)`` tuple of captured strings. 
-        """ 
-        capture = Capture(py.io.StdCapture)
-        request.addfinalizer(capture.finalize)
-        return capture 
-    
-    def pytest_funcarg__capfd(request):
-        """captures writes to file descriptors 1 and 2 and makes 
-        them available successively via a ``capsys.reset()`` method 
-        which returns a ``(out, err)`` tuple of captured strings. 
-        """ 
-        capture = Capture(py.io.StdCaptureFD)
-        request.addfinalizer(capture.finalize)
-        return capture 
-    
-    def pytest_pyfunc_call(pyfuncitem):
-        if hasattr(pyfuncitem, 'funcargs'):
-            for funcarg, value in pyfuncitem.funcargs.items():
-                if funcarg == "capsys" or funcarg == "capfd":
-                    value.reset()
-    
-    class Capture:
-        _capture = None
-        def __init__(self, captureclass):
-            self._captureclass = captureclass
-    
-        def finalize(self):
-            if self._capture:
-                self._capture.reset()
-    
-        def reset(self):
-            res = None
-            if self._capture:
-                res = self._capture.reset()
-            self._capture = self._captureclass()
-            return res 
-    
-    class TestCapture:
-        def test_std_functional(self, testdir):        
-            reprec = testdir.inline_runsource("""
-                def test_hello(capsys):
-                    print 42
-                    out, err = capsys.reset()
-                    assert out.startswith("42")
-            """)
-            reprec.assertoutcome(passed=1)
-            
-        def test_stdfd_functional(self, testdir):        
-            reprec = testdir.inline_runsource("""
-                def test_hello(capfd):
-                    import os
-                    os.write(1, "42")
-                    out, err = capfd.reset()
-                    assert out.startswith("42")
-            """)
-            reprec.assertoutcome(passed=1)
-    
-        def test_funcall_yielded_no_funcargs(self, testdir):        
-            reprec = testdir.inline_runsource("""
-                def test_hello():
-                    yield lambda: None
-            """)
-            reprec.assertoutcome(passed=1)
-
-.. _`pytest_iocapture.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_iocapture.py
+.. _`pytest_iocapture.py`: http://bitbucket.org/hpk42/py-trunk/raw/85fe614ab05f301f206935d11a477df184cbbce6/py/test/plugin/pytest_iocapture.py
 .. _`extend`: ../extend.html
 .. _`plugins`: index.html
 .. _`contact`: ../../contact.html

doc/test/plugin/keyword.txt

-
-pytest_keyword plugin
-=====================
-
-py.test.mark / keyword plugin
-
-
-
-Getting and improving this plugin
----------------------------------
-
-
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
-
-1. Download `pytest_keyword.py`_ plugin source code 
-2. put it somewhere as ``pytest_keyword.py`` into your import path 
-3. a subsequent test run will now use your local version! 
-
-Further information: extend_ documentation, other plugins_ or contact_.  
-
-For your convenience here is also an inlined version of ``pytest_keyword.py``:
-
-.. sourcecode:: python
-
-    """
-        py.test.mark / keyword plugin 
-    """
-    import py
-    
-    def pytest_namespace():
-        mark = KeywordDecorator({})
-        return {'mark': mark}
-    
-    class KeywordDecorator:
-        """ decorator for setting function attributes. """
-        def __init__(self, keywords, lastname=None):
-            self._keywords = keywords
-            self._lastname = lastname
-    
-        def __call__(self, func=None, **kwargs):
-            if func is None:
-                kw = self._keywords.copy()
-                kw.update(kwargs)
-                return KeywordDecorator(kw)
-            elif not hasattr(func, 'func_dict'):
-                kw = self._keywords.copy()
-                name = self._lastname
-                if name is None:
-                    name = "mark"
-                kw[name] = func
-                return KeywordDecorator(kw)
-            func.func_dict.update(self._keywords)
-            return func 
-    
-        def __getattr__(self, name):
-            if name[0] == "_":
-                raise AttributeError(name)
-            kw = self._keywords.copy()
-            kw[name] = True
-            return self.__class__(kw, lastname=name)
-    
-    def test_pytest_mark_getattr():
-        mark = KeywordDecorator({})
-        def f(): pass
-    
-        mark.hello(f)
-        assert f.hello == True
-    
-        mark.hello("test")(f)
-        assert f.hello == "test"
-    
-        py.test.raises(AttributeError, "mark._hello")
-        py.test.raises(AttributeError, "mark.__str__")
-    
-    def test_pytest_mark_call():
-        mark = KeywordDecorator({})
-        def f(): pass
-        mark(x=3)(f)
-        assert f.x == 3
-        def g(): pass
-        mark(g)
-        assert not g.func_dict
-    
-        mark.hello(f)
-        assert f.hello == True
-    
-        mark.hello("test")(f)
-        assert f.hello == "test"
-    
-        mark("x1")(f)
-        assert f.mark == "x1"
-    
-    def test_mark_plugin(testdir):
-        p = testdir.makepyfile("""
-            import py
-            pytest_plugins = "keyword" 
-            @py.test.mark.hello
-            def test_hello():
-                assert hasattr(test_hello, 'hello')
-        """)
-        result = testdir.runpytest(p)
-        assert result.stdout.fnmatch_lines(["*passed*"])
-
-.. _`pytest_keyword.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_keyword.py
-.. _`extend`: ../extend.html
-.. _`plugins`: index.html
-.. _`contact`: ../../contact.html
-.. _`checkout the py.test development version`: ../../download.html#checkout

doc/test/plugin/monkeypatch.txt

 
 safely patch object attributes, dicts and environment variables.
 
+.. contents::
+  :local:
+
 Usage
 ----------------
 
 for an extensive discussion. 
 
 .. _`monkeypatch blog post`: http://tetamap.wordpress.com/2009/03/03/monkeypatching-in-unit-tests-done-right/
+
 .. _`monkeypatch funcarg`:
 
 
 All such modifications will be undone when the requesting 
 test function finished its execution. 
 
-Getting and improving this plugin
----------------------------------
+Start improving this plugin in 30 seconds
+=========================================
 
 
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
+Do you find the above documentation or the plugin itself lacking? 
 
 1. Download `pytest_monkeypatch.py`_ plugin source code 
 2. put it somewhere as ``pytest_monkeypatch.py`` into your import path 
-3. a subsequent test run will now use your local version! 
+3. a subsequent ``py.test`` run will use your local version
 
 Further information: extend_ documentation, other plugins_ or contact_.  
 
-For your convenience here is also an inlined version of ``pytest_monkeypatch.py``:
-
-.. sourcecode:: python
-
-    """
-    safely patch object attributes, dicts and environment variables. 
-    
-    Usage
-    ----------------
-    
-    Use the `monkeypatch funcarg`_ to safely patch the environment
-    variables, object attributes or dictionaries.  For example, if you want
-    to set the environment variable ``ENV1`` and patch the
-    ``os.path.abspath`` function to return a particular value during a test
-    function execution you can write it down like this:
-    
-    .. sourcecode:: python 
-    
-        def test_mytest(monkeypatch):
-            monkeypatch.setenv('ENV1', 'myval')
-            monkeypatch.setattr(os.path, 'abspath', lambda x: '/')
-            ... # your test code 
-    
-    The function argument will do the modifications and memorize the 
-    old state.  After the test function finished execution all 
-    modifications will be reverted.  See the `monkeypatch blog post`_ 
-    for an extensive discussion. 
-    
-    .. _`monkeypatch blog post`: http://tetamap.wordpress.com/2009/03/03/monkeypatching-in-unit-tests-done-right/
-    """
-    
-    import os
-    
-    def pytest_funcarg__monkeypatch(request):
-        """The returned ``monkeypatch`` funcarg provides three 
-        helper methods to modify objects, dictionaries or os.environ::
-    
-            monkeypatch.setattr(obj, name, value)  
-            monkeypatch.setitem(mapping, name, value) 
-            monkeypatch.setenv(name, value) 
-    
-        All such modifications will be undone when the requesting 
-        test function finished its execution. 
-        """
-        monkeypatch = MonkeyPatch()
-        request.addfinalizer(monkeypatch.finalize)
-        return monkeypatch
-    
-    notset = object()
-    
-    class MonkeyPatch:
-        def __init__(self):
-            self._setattr = []
-            self._setitem = []
-    
-        def setattr(self, obj, name, value):
-            self._setattr.insert(0, (obj, name, getattr(obj, name, notset)))
-            setattr(obj, name, value)
-    
-        def setitem(self, dictionary, name, value):
-            self._setitem.insert(0, (dictionary, name, dictionary.get(name, notset)))
-            dictionary[name] = value
-    
-        def setenv(self, name, value):
-            self.setitem(os.environ, name, str(value))        
-    
-        def finalize(self):
-            for obj, name, value in self._setattr:
-                if value is not notset:
-                    setattr(obj, name, value)
-                else:
-                    delattr(obj, name)
-            for dictionary, name, value in self._setitem:
-                if value is notset:
-                    del dictionary[name]
-                else:
-                    dictionary[name] = value
-    
-    
-    def test_setattr():
-        class A:
-            x = 1
-        monkeypatch = MonkeyPatch()
-        monkeypatch.setattr(A, 'x', 2)
-        assert A.x == 2
-        monkeypatch.setattr(A, 'x', 3)
-        assert A.x == 3
-        monkeypatch.finalize()
-        assert A.x == 1
-    
-        monkeypatch.setattr(A, 'y', 3)
-        assert A.y == 3
-        monkeypatch.finalize()
-        assert not hasattr(A, 'y')
-         
-    
-    def test_setitem():
-        d = {'x': 1}
-        monkeypatch = MonkeyPatch()
-        monkeypatch.setitem(d, 'x', 2)
-        monkeypatch.setitem(d, 'y', 1700)
-        assert d['x'] == 2
-        assert d['y'] == 1700
-        monkeypatch.setitem(d, 'x', 3)
-        assert d['x'] == 3
-        monkeypatch.finalize()
-        assert d['x'] == 1
-        assert 'y' not in d
-    
-    def test_setenv():
-        monkeypatch = MonkeyPatch()
-        monkeypatch.setenv('XYZ123', 2)
-        import os
-        assert os.environ['XYZ123'] == "2"
-        monkeypatch.finalize()
-        assert 'XYZ123' not in os.environ
-    
-    def test_monkeypatch_plugin(testdir):
-        reprec = testdir.inline_runsource("""
-            pytest_plugins = 'pytest_monkeypatch', 
-            def test_method(monkeypatch):
-                assert monkeypatch.__class__.__name__ == "MonkeyPatch"
-        """)
-        res = reprec.countoutcomes()
-        assert tuple(res) == (1, 0, 0), res
-
-.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_monkeypatch.py
+.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/85fe614ab05f301f206935d11a477df184cbbce6/py/test/plugin/pytest_monkeypatch.py
 .. _`extend`: ../extend.html
 .. _`plugins`: index.html
 .. _`contact`: ../../contact.html

doc/test/plugin/pdb.txt

-
-pytest_pdb plugin
-=================
-
-interactive debugging with the Python Debugger.
-
-
-
-command line options
---------------------
-
-
-``--pdb``
-    start pdb (the Python debugger) on errors.
-
-Getting and improving this plugin
----------------------------------
-
-
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
-
-1. Download `pytest_pdb.py`_ plugin source code 
-2. put it somewhere as ``pytest_pdb.py`` into your import path 
-3. a subsequent test run will now use your local version! 
-
-Further information: extend_ documentation, other plugins_ or contact_.  
-
-For your convenience here is also an inlined version of ``pytest_pdb.py``:
-
-.. sourcecode:: python
-
-    """
-    interactive debugging with the Python Debugger.
-    """
-    import py
-    import pdb, sys, linecache
-    from py.__.test.outcome import Skipped
-    
-    def pytest_addoption(parser):
-        group = parser.getgroup("general") 
-        group._addoption('--pdb',
-                   action="store_true", dest="usepdb", default=False,
-                   help="start pdb (the Python debugger) on errors.")
-    
-    
-    def pytest_configure(config):
-        if config.option.usepdb:
-            if config.getvalue("looponfail"):
-                raise config.Error("--pdb incompatible with --looponfail.")
-            if config.option.dist != "no":
-                raise config.Error("--pdb incomptaible with distributing tests.")
-            config.pluginmanager.register(PdbInvoke())
-    
-    class PdbInvoke:
-        def pytest_runtest_makereport(self, item, call):
-            if call.excinfo and not call.excinfo.errisinstance(Skipped): 
-                tw = py.io.TerminalWriter()
-                repr = call.excinfo.getrepr()
-                repr.toterminal(tw) 
-                post_mortem(call.excinfo._excinfo[2])
-    
-    class Pdb(py.std.pdb.Pdb):
-        def do_list(self, arg):
-            self.lastcmd = 'list'
-            last = None
-            if arg:
-                try:
-                    x = eval(arg, {}, {})
-                    if type(x) == type(()):
-                        first, last = x
-                        first = int(first)
-                        last = int(last)
-                        if last < first:
-                            # Assume it's a count
-                            last = first + last
-                    else:
-                        first = max(1, int(x) - 5)
-                except:
-                    print '*** Error in argument:', repr(arg)
-                    return
-            elif self.lineno is None:
-                first = max(1, self.curframe.f_lineno - 5)
-            else:
-                first = self.lineno + 1
-            if last is None:
-                last = first + 10
-            filename = self.curframe.f_code.co_filename
-            breaklist = self.get_file_breaks(filename)
-            try:
-                for lineno in range(first, last+1):
-                    # start difference from normal do_line
-                    line = self._getline(filename, lineno)
-                    # end difference from normal do_line
-                    if not line:
-                        print '[EOF]'
-                        break
-                    else:
-                        s = repr(lineno).rjust(3)
-                        if len(s) < 4: s = s + ' '
-                        if lineno in breaklist: s = s + 'B'
-                        else: s = s + ' '
-                        if lineno == self.curframe.f_lineno:
-                            s = s + '->'
-                        print s + '\t' + line,
-                        self.lineno = lineno
-            except KeyboardInterrupt:
-                pass
-        do_l = do_list
-    
-        def _getline(self, filename, lineno):
-            if hasattr(filename, "__source__"):
-                try:
-                    return filename.__source__.lines[lineno - 1] + "\n"
-                except IndexError:
-                    return None
-            return linecache.getline(filename, lineno)
-    
-        def get_stack(self, f, t):
-            # Modified from bdb.py to be able to walk the stack beyond generators,
-            # which does not work in the normal pdb :-(
-            stack, i = pdb.Pdb.get_stack(self, f, t)
-            if f is None:
-                i = max(0, len(stack) - 1)
-            return stack, i
-    
-    def post_mortem(t):
-        # modified from pdb.py for the new get_stack() implementation
-        p = Pdb()
-        p.reset()
-        p.interaction(None, t)
-    
-    def set_trace():
-        # again, a copy of the version in pdb.py
-        Pdb().set_trace(sys._getframe().f_back)
-    
-    
-    class TestPDB: 
-        def pytest_funcarg__pdblist(self, request):
-            monkeypatch = request.getfuncargvalue("monkeypatch")
-            pdblist = []
-            def mypdb(*args):
-                pdblist.append(args)
-            monkeypatch.setitem(globals(), 'post_mortem', mypdb)
-            return pdblist 
-    
-        def test_incompatibility_messages(self, testdir):
-            Error = py.test.config.Error
-            py.test.raises(Error, "testdir.parseconfigure('--pdb', '--looponfail')")
-            py.test.raises(Error, "testdir.parseconfigure('--pdb', '-n 3')")
-            py.test.raises(Error, "testdir.parseconfigure('--pdb', '-d')")
-             
-        def test_pdb_on_fail(self, testdir, pdblist):
-            rep = testdir.inline_runsource1('--pdb', """
-                def test_func(): 
-                    assert 0
-            """)
-            assert rep.failed
-            assert len(pdblist) == 1
-            tb = py.code.Traceback(pdblist[0][0])
-            assert tb[-1].name == "test_func"
-    
-        def test_pdb_on_skip(self, testdir, pdblist):
-            rep = testdir.inline_runsource1('--pdb', """
-                import py
-                def test_func():
-                    py.test.skip("hello")
-            """)
-            assert rep.skipped 
-            assert len(pdblist) == 0
-    
-        def test_pdb_interaction(self, testdir):
-            p1 = testdir.makepyfile("""
-                def test_1():
-                    i = 0
-                    assert i == 1
-            """)
-            child = testdir.spawn_pytest("--pdb %s" % p1)
-            #child.expect(".*def test_1.*")
-            child.expect(".*i = 0.*")
-            child.expect("(Pdb)")
-            child.sendeof()
-            child.expect("1 failed")
-            if child.isalive(): 
-                child.wait()
-
-.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_pdb.py
-.. _`extend`: ../extend.html
-.. _`plugins`: index.html
-.. _`contact`: ../../contact.html
-.. _`checkout the py.test development version`: ../../download.html#checkout
Add a comment to this file

doc/test/plugin/pocoo.txt

File contents unchanged.

doc/test/plugin/pytester.txt

-
-pytest_pytester plugin
-======================
-
-funcargs and support code for testing py.test's own functionality.
-
-
-.. _`testdir funcarg`:
-
-
-the 'testdir' test function argument
-------------------------------------
-
-XXX missing docstring
-.. _`reportrecorder funcarg`:
-
-
-the 'reportrecorder' test function argument
--------------------------------------------
-
-XXX missing docstring
-.. _`venv funcarg`:
-
-
-the 'venv' test function argument
----------------------------------
-
-XXX missing docstring
-.. _`linecomp funcarg`:
-
-
-the 'linecomp' test function argument
--------------------------------------
-
-XXX missing docstring
-.. _`py_setup funcarg`:
-
-
-the 'py_setup' test function argument
--------------------------------------
-
-XXX missing docstring
-.. _`LineMatcher funcarg`:
-
-
-the 'LineMatcher' test function argument
-----------------------------------------
-
-XXX missing docstring
-
-Getting and improving this plugin
----------------------------------
-
-
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
-
-1. Download `pytest_pytester.py`_ plugin source code 
-2. put it somewhere as ``pytest_pytester.py`` into your import path 
-3. a subsequent test run will now use your local version! 
-
-Further information: extend_ documentation, other plugins_ or contact_.  
-
-For your convenience here is also an inlined version of ``pytest_pytester.py``:
-
-.. sourcecode:: python
-
-    """
-    funcargs and support code for testing py.test's own functionality. 
-    """
-    
-    import py
-    import sys, os
-    import inspect
-    from py.__.test.config import Config as pytestConfig
-    import hookspec
-    import subprocess
-    
-    pytest_plugins = '_pytest'
-    
-    def pytest_funcarg__linecomp(request):
-        return LineComp()
-    
-    def pytest_funcarg__LineMatcher(request):
-        return LineMatcher
-    
-    def pytest_funcarg__testdir(request):
-        tmptestdir = TmpTestdir(request)
-        return tmptestdir
-    
-    def pytest_funcarg__reportrecorder(request):
-        reprec = ReportRecorder(py._com.comregistry)
-        request.addfinalizer(lambda: reprec.comregistry.unregister(reprec))
-        return reprec
-    
-    class RunResult:
-        def __init__(self, ret, outlines, errlines):
-            self.ret = ret
-            self.outlines = outlines
-            self.errlines = errlines
-            self.stdout = LineMatcher(outlines)
-            self.stderr = LineMatcher(errlines)
-    
-    class TmpTestdir:
-        def __init__(self, request):
-            self.request = request
-            self._pytest = request.getfuncargvalue("_pytest")
-            # XXX remove duplication with tmpdir plugin 
-            basetmp = request.config.ensuretemp("testdir")
-            name = request.function.__name__
-            for i in range(100):
-                try:
-                    tmpdir = basetmp.mkdir(name + str(i))
-                except py.error.EEXIST:
-                    continue
-                break
-            # we need to create another subdir
-            # because Directory.collect() currently loads
-            # conftest.py from sibling directories
-            self.tmpdir = tmpdir.mkdir(name)
-            self.plugins = []
-            self._syspathremove = []
-            self.chdir() # always chdir
-            assert hasattr(self, '_olddir')
-            self.request.addfinalizer(self.finalize)
-    
-        def __repr__(self):
-            return "<TmpTestdir %r>" % (self.tmpdir,)
-    
-        def Config(self, comregistry=None, topdir=None):
-            if topdir is None:
-                topdir = self.tmpdir.dirpath()
-            return pytestConfig(comregistry, topdir=topdir)
-    
-        def finalize(self):
-            for p in self._syspathremove:
-                py.std.sys.path.remove(p)
-            if hasattr(self, '_olddir'):
-                self._olddir.chdir()
-    
-        def getreportrecorder(self, obj):
-            if isinstance(obj, py._com.Registry):
-                registry = obj
-            elif hasattr(obj, 'comregistry'):
-                registry = obj.comregistry
-            elif hasattr(obj, 'pluginmanager'):
-                registry = obj.pluginmanager.comregistry
-            elif hasattr(obj, 'config'):
-                registry = obj.config.pluginmanager.comregistry
-            else:
-                raise ValueError("obj %r provides no comregistry" %(obj,))
-            assert isinstance(registry, py._com.Registry)
-            reprec = ReportRecorder(registry)
-            reprec.hookrecorder = self._pytest.gethookrecorder(hookspec, registry)
-            reprec.hook = reprec.hookrecorder.hook
-            return reprec
-    
-        def chdir(self):
-            old = self.tmpdir.chdir()
-            if not hasattr(self, '_olddir'):
-                self._olddir = old 
-    
-        def _makefile(self, ext, args, kwargs):
-            items = kwargs.items()
-            if args:
-                source = "\n".join(map(str, args))
-                basename = self.request.function.__name__
-                items.insert(0, (basename, source))
-            ret = None
-            for name, value in items:
-                p = self.tmpdir.join(name).new(ext=ext)
-                source = py.code.Source(value)
-                p.write(str(py.code.Source(value)).lstrip())
-                if ret is None:
-                    ret = p
-            return ret 
-    
-    
-        def makefile(self, ext, *args, **kwargs):
-            return self._makefile(ext, args, kwargs)
-    
-        def makeconftest(self, source):
-            return self.makepyfile(conftest=source)
-    
-        def makepyfile(self, *args, **kwargs):
-            return self._makefile('.py', args, kwargs)
-    
-        def maketxtfile(self, *args, **kwargs):
-            return self._makefile('.txt', args, kwargs)
-    
-        def syspathinsert(self, path=None):
-            if path is None:
-                path = self.tmpdir
-            py.std.sys.path.insert(0, str(path))
-            self._syspathremove.append(str(path))
-                
-        def mkdir(self, name):
-            return self.tmpdir.mkdir(name)
-        
-        def genitems(self, colitems):
-            return list(self.session.genitems(colitems))
-    
-        def inline_genitems(self, *args):
-            #config = self.parseconfig(*args)
-            config = self.parseconfig(*args)
-            session = config.initsession()
-            rec = self.getreportrecorder(config)
-            colitems = [config.getfsnode(arg) for arg in config.args]
-            items = list(session.genitems(colitems))
-            return items, rec 
-    
-        def runitem(self, source):
-            # used from runner functional tests 
-            item = self.getitem(source)
-            # the test class where we are called from wants to provide the runner 
-            testclassinstance = self.request.function.im_self
-            runner = testclassinstance.getrunner()
-            return runner(item)
-    
-        def inline_runsource(self, source, *cmdlineargs):
-            p = self.makepyfile(source)
-            l = list(cmdlineargs) + [p]
-            return self.inline_run(*l)
-    
-        def inline_runsource1(self, *args):
-            args = list(args)
-            source = args.pop()
-            p = self.makepyfile(source)
-            l = list(args) + [p]
-            reprec = self.inline_run(*l)
-            reports = reprec.getreports("pytest_runtest_logreport")
-            assert len(reports) == 1, reports 
-            return reports[0]
-    
-        def inline_run(self, *args):
-            config = self.parseconfig(*args)
-            config.pluginmanager.do_configure(config)
-            session = config.initsession()
-            reprec = self.getreportrecorder(config)
-            session.main()
-            config.pluginmanager.do_unconfigure(config)
-            return reprec 
-    
-        def config_preparse(self):
-            config = self.Config()
-            for plugin in self.plugins:
-                if isinstance(plugin, str):
-                    config.pluginmanager.import_plugin(plugin)
-                else:
-                    if isinstance(plugin, dict):
-                        plugin = PseudoPlugin(plugin) 
-                    if not config.pluginmanager.isregistered(plugin):
-                        config.pluginmanager.register(plugin)
-            #print "config.pluginmanager.impname2plugin", config.pluginmanager.impname2plugin
-            return config
-    
-        def parseconfig(self, *args):
-            if not args:
-                args = (self.tmpdir,)
-            config = self.config_preparse()
-            args = list(args) + ["--basetemp=%s" % self.tmpdir.dirpath('basetemp')]
-            config.parse(args)
-            return config 
-    
-        def parseconfigure(self, *args):
-            config = self.parseconfig(*args)
-            config.pluginmanager.do_configure(config)
-            return config
-    
-        def getitem(self,  source, funcname="test_func"):
-            modcol = self.getmodulecol(source)
-            moditems = modcol.collect()
-            for item in modcol.collect():
-                if item.name == funcname:
-                    return item 
-            else:
-                assert 0, "%r item not found in module:\n%s" %(funcname, source)
-    
-        def getitems(self,  source):
-            modcol = self.getmodulecol(source)
-            return list(modcol.config.initsession().genitems([modcol]))
-            #assert item is not None, "%r item not found in module:\n%s" %(funcname, source)
-            #return item 
-    
-        def getfscol(self,  path, configargs=()):
-            self.config = self.parseconfig(path, *configargs)
-            self.session = self.config.initsession()
-            return self.config.getfsnode(path)
-    
-        def getmodulecol(self,  source, configargs=(), withinit=False):
-            kw = {self.request.function.__name__: py.code.Source(source).strip()}
-            path = self.makepyfile(**kw)
-            if withinit:
-                self.makepyfile(__init__ = "#")
-            self.config = self.parseconfig(path, *configargs)
-            self.session = self.config.initsession()
-            #self.config.pluginmanager.do_configure(config=self.config)
-            # XXX 
-            self.config.pluginmanager.import_plugin("runner") 
-            plugin = self.config.pluginmanager.getplugin("runner") 
-            plugin.pytest_configure(config=self.config)
-    
-            return self.config.getfsnode(path)
-    
-        def prepare(self):
-            p = self.tmpdir.join("conftest.py") 
-            if not p.check():
-                plugins = [x for x in self.plugins if isinstance(x, str)]
-                if not plugins:
-                    return
-                p.write("import py ; pytest_plugins = %r" % plugins)
-            else:
-                if self.plugins:
-                    print "warning, ignoring reusing existing con", p 
-    
-        def popen(self, cmdargs, stdout, stderr, **kw):
-            if not hasattr(py.std, 'subprocess'):
-                py.test.skip("no subprocess module")
-            env = os.environ.copy()
-            env['PYTHONPATH'] = ":".join(filter(None, [
-                str(os.getcwd()), env.get('PYTHONPATH', '')]))
-            kw['env'] = env
-            #print "env", env
-            return py.std.subprocess.Popen(cmdargs, stdout=stdout, stderr=stderr, **kw)
-    
-        def run(self, *cmdargs):
-            self.prepare()
-            old = self.tmpdir.chdir()
-            #print "chdir", self.tmpdir
-            try:
-                return self._run(*cmdargs)
-            finally:
-                old.chdir()
-    
-        def _run(self, *cmdargs):
-            cmdargs = map(str, cmdargs)
-            p1 = py.path.local("stdout")
-            p2 = py.path.local("stderr")
-            print "running", cmdargs, "curdir=", py.path.local()
-            f1 = p1.open("w")
-            f2 = p2.open("w")
-            popen = self.popen(cmdargs, stdout=f1, stderr=f2, 
-                close_fds=(sys.platform != "win32"))
-            ret = popen.wait()
-            f1.close()
-            f2.close()
-            out, err = p1.readlines(cr=0), p2.readlines(cr=0)
-            if err:
-                for line in err: 
-                    print >>py.std.sys.stderr, line
-            if out:
-                for line in out: 
-                    print >>py.std.sys.stdout, line
-            return RunResult(ret, out, err)
-    
-        def runpybin(self, scriptname, *args):
-            fullargs = self._getpybinargs(scriptname) + args
-            return self.run(*fullargs)
-    
-        def _getpybinargs(self, scriptname):
-            bindir = py.path.local(py.__file__).dirpath("bin")
-            script = bindir.join(scriptname)
-            assert script.check()
-            return py.std.sys.executable, script
-    
-        def runpytest(self, *args):
-            p = py.path.local.make_numbered_dir(prefix="runpytest-", 
-                keep=None, rootdir=self.tmpdir)
-            args = ('--basetemp=%s' % p, ) + args 
-            return self.runpybin("py.test", *args)
-    
-        def spawn_pytest(self, string, expect_timeout=10.0):
-            pexpect = py.test.importorskip("pexpect", "2.3")
-            basetemp = self.tmpdir.mkdir("pexpect")
-            invoke = "%s %s" % self._getpybinargs("py.test")
-            cmd = "%s --basetemp=%s %s" % (invoke, basetemp, string)
-            child = pexpect.spawn(cmd, logfile=basetemp.join("spawn.out").open("w"))
-            child.timeout = expect_timeout
-            return child
-    
-    class PseudoPlugin:
-        def __init__(self, vars):
-            self.__dict__.update(vars) 
-    
-    class ReportRecorder(object):
-        def __init__(self, comregistry):
-            self.comregistry = comregistry
-            comregistry.register(self)
-    
-        def getcall(self, name):
-            return self.hookrecorder.getcall(name)
-    
-        def popcall(self, name):
-            return self.hookrecorder.popcall(name)
-    
-        def getcalls(self, names):
-            """ return list of ParsedCall instances matching the given eventname. """
-            return self.hookrecorder.getcalls(names)
-    
-        # functionality for test reports 
-    
-        def getreports(self, names="pytest_runtest_logreport pytest_collectreport"):
-            return [x.rep for x in self.getcalls(names)]
-    
-        def matchreport(self, inamepart="", names="pytest_runtest_logreport pytest_collectreport"):
-            """ return a testreport whose dotted import path matches """
-            l = []
-            for rep in self.getreports(names=names):
-                colitem = rep.getnode()
-                if not inamepart or inamepart in colitem.listnames():
-                    l.append(rep)
-            if not l:
-                raise ValueError("could not find test report matching %r: no test reports at all!" %
-                    (inamepart,))
-            if len(l) > 1:
-                raise ValueError("found more than one testreport matching %r: %s" %(
-                                 inamepart, l))
-            return l[0]
-    
-        def getfailures(self, names='pytest_runtest_logreport pytest_collectreport'):
-            return [rep for rep in self.getreports(names) if rep.failed]
-    
-        def getfailedcollections(self):
-            return self.getfailures('pytest_collectreport')
-    
-        def listoutcomes(self):
-            passed = []
-            skipped = []
-            failed = []
-            for rep in self.getreports("pytest_runtest_logreport"):
-                if rep.passed: 
-                    if rep.when == "call": 
-                        passed.append(rep) 
-                elif rep.skipped: 
-                    skipped.append(rep) 
-                elif rep.failed:
-                    failed.append(rep) 
-            return passed, skipped, failed 
-    
-        def countoutcomes(self):
-            return map(len, self.listoutcomes())
-    
-        def assertoutcome(self, passed=0, skipped=0, failed=0):
-            realpassed, realskipped, realfailed = self.listoutcomes()
-            assert passed == len(realpassed)
-            assert skipped == len(realskipped)
-            assert failed == len(realfailed)
-    
-        def clear(self):
-            self.hookrecorder.calls[:] = []
-    
-        def unregister(self):
-            self.comregistry.unregister(self)
-            self.hookrecorder.finish_recording()
-    
-    def test_reportrecorder(testdir):
-        registry = py._com.Registry()
-        recorder = testdir.getreportrecorder(registry)
-        assert not recorder.getfailures()
-        item = testdir.getitem("def test_func(): pass")
-        class rep:
-            excinfo = None
-            passed = False
-            failed = True 
-            skipped = False
-            when = "call" 
-    
-        recorder.hook.pytest_runtest_logreport(rep=rep)
-        failures = recorder.getfailures()
-        assert failures == [rep]
-        failures = recorder.getfailures()
-        assert failures == [rep]
-    
-        class rep:
-            excinfo = None
-            passed = False
-            failed = False
-            skipped = True
-            when = "call" 
-        rep.passed = False
-        rep.skipped = True
-        recorder.hook.pytest_runtest_logreport(rep=rep)
-    
-        modcol = testdir.getmodulecol("")
-        rep = modcol.config.hook.pytest_make_collect_report(collector=modcol)
-        rep.passed = False
-        rep.failed = True
-        rep.skipped = False
-        recorder.hook.pytest_collectreport(rep=rep)
-    
-        passed, skipped, failed = recorder.listoutcomes()
-        assert not passed and skipped and failed
-    
-        numpassed, numskipped, numfailed = recorder.countoutcomes()
-        assert numpassed == 0
-        assert numskipped == 1
-        assert numfailed == 1
-        assert len(recorder.getfailedcollections()) == 1
-    
-        recorder.unregister()
-        recorder.clear() 
-        recorder.hook.pytest_runtest_logreport(rep=rep)
-        py.test.raises(ValueError, "recorder.getfailures()")
-    
-    class LineComp:
-        def __init__(self):
-            self.stringio = py.std.StringIO.StringIO()
-    
-        def assert_contains_lines(self, lines2):
-            """ assert that lines2 are contained (linearly) in lines1. 
-                return a list of extralines found.
-            """
-            __tracebackhide__ = True
-            val = self.stringio.getvalue()
-            self.stringio.truncate(0)  # remove what we got 
-            lines1 = val.split("\n")
-            return LineMatcher(lines1).fnmatch_lines(lines2)
-                
-    class LineMatcher:
-        def __init__(self,  lines):
-            self.lines = lines
-    
-        def str(self):
-            return "\n".join(self.lines)
-    
-        def fnmatch_lines(self, lines2):
-            if isinstance(lines2, str):
-                lines2 = py.code.Source(lines2)
-            if isinstance(lines2, py.code.Source):
-                lines2 = lines2.strip().lines
-    
-            from fnmatch import fnmatch
-            __tracebackhide__ = True
-            lines1 = self.lines[:]
-            nextline = None
-            extralines = []
-            for line in lines2:
-                nomatchprinted = False
-                while lines1:
-                    nextline = lines1.pop(0)
-                    if line == nextline:
-                        print "exact match:", repr(line)
-                        break 
-                    elif fnmatch(nextline, line):
-                        print "fnmatch:", repr(line)
-                        print "   with:", repr(nextline)
-                        break
-                    else:
-                        if not nomatchprinted:
-                            print "nomatch:", repr(line)
-                            nomatchprinted = True
-                        print "    and:", repr(nextline)
-                    extralines.append(nextline)
-                else:
-                    if line != nextline:
-                        #__tracebackhide__ = True
-                        raise AssertionError("expected line not found: %r" % line)
-            extralines.extend(lines1)
-            return extralines 
-    
-    def test_parseconfig(testdir):
-        config1 = testdir.parseconfig()
-        config2 = testdir.parseconfig()
-        assert config2 != config1
-        assert config1 != py.test.config
-    
-    def test_testdir_runs_with_plugin(testdir):
-        testdir.makepyfile("""
-            pytest_plugins = "pytest_pytester" 
-            def test_hello(testdir):
-                assert 1
-        """)
-        result = testdir.runpytest()
-        assert result.stdout.fnmatch_lines([
-            "*1 passed*"
-        ])
-    
-    #
-    # experimental funcargs for venv/install-tests
-    #
-    
-    def pytest_funcarg__venv(request):
-        p = request.config.mktemp(request.function.__name__, numbered=True)
-        venv = VirtualEnv(str(p)) 
-        venv.create()
-        return venv 
-       
-    def pytest_funcarg__py_setup(request):
-        rootdir = py.path.local(py.__file__).dirpath().dirpath()
-        setup = rootdir.join('setup.py')
-        if not setup.check():
-            py.test.skip("not found: %r" % setup)
-        return SetupBuilder(setup)
-    
-    class SetupBuilder:
-        def __init__(self, setup_path):
-            self.setup_path = setup_path
-    
-        def make_sdist(self, destdir=None):
-            temp = py.path.local.mkdtemp()
-            try:
-                args = ['python', str(self.setup_path), 'sdist', 
-                        '--dist-dir', str(temp)]
-                subprocess.check_call(args)
-                l = temp.listdir('py-*')
-                assert len(l) == 1
-                sdist = l[0]
-                if destdir is None:
-                    destdir = self.setup_path.dirpath('build')
-                    assert destdir.check()
-                else:
-                    destdir = py.path.local(destdir)
-                target = destdir.join(sdist.basename)
-                sdist.copy(target)
-                return target 
-            finally:
-                temp.remove()
-    
-    # code taken from Ronny Pfannenschmidt's virtualenvmanager 
-    
-    class VirtualEnv(object):
-        def __init__(self, path):
-            #XXX: supply the python executable
-            self.path = path
-    
-        def __repr__(self):
-            return "<VirtualEnv at %r>" %(self.path)
-    
-        def _cmd(self, name):
-            return os.path.join(self.path, 'bin', name)
-    
-        @property
-        def valid(self):
-            return os.path.exists(self._cmd('python'))
-    
-        def create(self, sitepackages=False):
-            args = ['virtualenv', self.path]
-            if not sitepackages:
-                args.append('--no-site-packages')
-            subprocess.check_call(args)
-    
-        def makegateway(self):
-            python = self._cmd('python')
-            return py.execnet.makegateway("popen//python=%s" %(python,))
-    
-        def pcall(self, cmd, *args, **kw):
-            assert self.valid
-            return subprocess.call([
-                    self._cmd(cmd)
-                ] + list(args),
-                **kw)
-    
-    
-        def easy_install(self, *packages, **kw):
-            args = []
-            if 'index' in kw:
-                index = kw['index']
-                if isinstance(index, (list, tuple)):
-                    for i in index:
-                        args.extend(['-i', i])
-                else:
-                    args.extend(['-i', index])
-    
-            args.extend(packages)
-            self.pcall('easy_install', *args)
-    
-    
-        @property
-        def has_pip(self):
-            return os.path.exists(self._cmd('pip'))
-    
-        def pip_install(self, *packages):
-            if not self.has_pip:
-                self.easy_install('pip')
-    
-            self.pcall('pip', *packages)
-
-.. _`pytest_pytester.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_pytester.py
-.. _`extend`: ../extend.html
-.. _`plugins`: index.html
-.. _`contact`: ../../contact.html
-.. _`checkout the py.test development version`: ../../download.html#checkout

doc/test/plugin/recwarn.txt

 
 helpers for asserting deprecation and other warnings.
 
-**recwarn**: function argument where one can call recwarn.pop() to get
-the last warning that would have been shown. 
+.. contents::
+  :local:
 
-**py.test.deprecated_call(func, *args, **kwargs)**: assert that the given function call triggers a deprecation warning.
+Example usage 
+---------------------
+
+You can use the ``recwarn`` funcarg to track 
+warnings within a test function:
+
+.. sourcecode:: python
+
+    def test_hello(recwarn):
+        from warnings import warn
+        warn("hello", DeprecationWarning)
+        w = recwarn.pop(DeprecationWarning)
+        assert issubclass(w.category, DeprecationWarning)
+        assert 'hello' in str(w.message)
+        assert w.filename
+        assert w.lineno
+
+You can also call a global helper for checking
+taht a certain function call yields a Deprecation
+warning:
+
+.. sourcecode:: python
+
+    import py
+            
+    def test_global():
+        py.test.deprecated_call(myfunction, 17)
+
 .. _`recwarn funcarg`:
 
 
 the 'recwarn' test function argument
 ------------------------------------
 
- check that warnings have been raised. 
+Return a WarningsRecorder instance that provides these methods:
 
-Getting and improving this plugin
----------------------------------
+* ``pop(category=None)``: return last warning matching the category.
+* ``clear()``: clear list of warnings 
 
+Start improving this plugin in 30 seconds
+=========================================
 
-Do you find the above documentation or the plugin itself lacking,
-not fit for what you need?  Here is a **30 seconds guide**
-to get you started on improving the plugin:
+
+Do you find the above documentation or the plugin itself lacking? 
 
 1. Download `pytest_recwarn.py`_ plugin source code 
 2. put it somewhere as ``pytest_recwarn.py`` into your import path 
-3. a subsequent test run will now use your local version! 
+3. a subsequent ``py.test`` run will use your local version
 
 Further information: extend_ documentation, other plugins_ or contact_.  
 
-For your convenience here is also an inlined version of ``pytest_recwarn.py``:
-
-.. sourcecode:: python
-
-    """
-    helpers for asserting deprecation and other warnings. 
-    
-    **recwarn**: function argument where one can call recwarn.pop() to get
-    the last warning that would have been shown. 
-    
-    **py.test.deprecated_call(func, *args, **kwargs)**: assert that the given function call triggers a deprecation warning. 
-    """
-    
-    import py
-    import os
-    
-    def pytest_funcarg__recwarn(request):
-        """ check that warnings have been raised. """ 
-        warnings = WarningsRecorder()
-        request.addfinalizer(warnings.finalize)
-        return warnings
-    
-    def pytest_namespace():
-        return {'deprecated_call': deprecated_call}
-    
-    def deprecated_call(func, *args, **kwargs):
-        """ assert that calling func(*args, **kwargs)
-            triggers a DeprecationWarning. 
-        """ 
-        warningmodule = py.std.warnings
-        l = []
-        oldwarn_explicit = getattr(warningmodule, 'warn_explicit')
-        def warn_explicit(*args, **kwargs): 
-            l.append(args) 
-            oldwarn_explicit(*args, **kwargs)
-        oldwarn = getattr(warningmodule, 'warn')
-        def warn(*args, **kwargs): 
-            l.append(args) 
-            oldwarn(*args, **kwargs)
-            
-        warningmodule.warn_explicit = warn_explicit
-        warningmodule.warn = warn
-        try:
-            ret = func(*args, **kwargs)
-        finally:
-            warningmodule.warn_explicit = warn_explicit
-            warningmodule.warn = warn
-        if not l:
-            #print warningmodule
-            raise AssertionError("%r did not produce DeprecationWarning" %(func,))
-        return ret
-    
-    
-    class RecordedWarning:
-        def __init__(self, message, category, filename, lineno, line):
-            self.message = message
-            self.category = category
-            self.filename = filename
-            self.lineno = lineno
-            self.line = line
-    
-    class WarningsRecorder:
-        def __init__(self):
-            warningmodule = py.std.warnings
-            self.list = []
-            def showwarning(message, category, filename, lineno, line=0):
-                self.list.append(RecordedWarning(
-                    message, category, filename, lineno, line))
-                try:
-                    self.old_showwarning(message, category, 
-                        filename, lineno, line=line)
-                except TypeError:
-                    # < python2.6 
-                    self.old_showwarning(message, category, filename, lineno)
-            self.old_showwarning = warningmodule.showwarning
-            warningmodule.showwarning = showwarning
-    
-        def pop(self, cls=Warning):
-            """ pop the first recorded warning, raise exception if not exists."""
-            for i, w in py.builtin.enumerate(self.list):
-                if issubclass(w.category, cls):
-                    return self.list.pop(i)
-            __tracebackhide__ = True
-            assert 0, "%r not found in %r" %(cls, self.list)
-    
-        #def resetregistry(self):
-        #    import warnings
-        #    warnings.onceregistry.clear()
-        #    warnings.__warningregistry__.clear()
-    
-        def clear(self): 
-            self.list[:] = []
-    
-        def finalize(self):
-            py.std.warnings.showwarning = self.old_showwarning
-    
-    def test_WarningRecorder():
-        showwarning = py.std.warnings.showwarning
-        rec = WarningsRecorder()
-        assert py.std.warnings.showwarning != showwarning
-        assert not rec.list
-        py.std.warnings.warn_explicit("hello", UserWarning, "xyz", 13)
-        assert len(rec.list) == 1
-        py.std.warnings.warn(DeprecationWarning("hello"))
-        assert len(rec.list) == 2
-        warn = rec.pop()
-        assert str(warn.message) == "hello"
-        l = rec.list
-        rec.clear()
-        assert len(rec.list) == 0
-        assert l is rec.list
-        py.test.raises(AssertionError, "rec.pop()")
-        rec.finalize()
-        assert showwarning == py.std.warnings.showwarning
-    
-    def test_recwarn_functional(testdir):
-        reprec = testdir.inline_runsource("""
-            pytest_plugins = 'pytest_recwarn', 
-            import warnings
-            oldwarn = warnings.showwarning
-            def test_method(recwarn):
-                assert warnings.showwarning != oldwarn
-                warnings.warn("hello")
-                warn = recwarn.pop()
-                assert isinstance(warn.message, UserWarning)
-            def test_finalized():
-                assert warnings.showwarning == oldwarn
-        """)
-        res = reprec.countoutcomes()
-        assert tuple(res) == (2, 0, 0), res
-            
-    #
-    # ============ test py.test.deprecated_call() ==============
-    #
-    
-    def dep(i):
-        if i == 0:
-            py.std.warnings.warn("is deprecated", DeprecationWarning)
-        return 42
-    
-    reg = {}
-    def dep_explicit(i):
-        if i == 0:
-            py.std.warnings.warn_explicit("dep_explicit", category=DeprecationWarning, 
-                                          filename="hello", lineno=3)
-    
-    def test_deprecated_call_raises():
-        excinfo = py.test.raises(AssertionError, 
-                       "py.test.deprecated_call(dep, 3)")
-        assert str(excinfo).find("did not produce") != -1 
-    
-    def test_deprecated_call():
-        py.test.deprecated_call(dep, 0)
-    
-    def test_deprecated_call_ret():
-        ret = py.test.deprecated_call(dep, 0)
-        assert ret == 42
-    
-    def test_deprecated_call_preserves():
-        r = py.std.warnings.onceregistry.copy()
-        f = py.std.warnings.filters[:]
-        test_deprecated_call_raises()
-        test_deprecated_call()
-        assert r == py.std.warnings.onceregistry
-        assert f == py.std.warnings.filters
-    
-    def test_deprecated_explicit_call_raises():
-        py.test.raises(AssertionError, 
-                       "py.test.deprecated_call(dep_explicit, 3)")
-    
-    def test_deprecated_explicit_call():
-        py.test.deprecated_call(dep_explicit, 0)
-        py.test.deprecated_call(dep_explicit, 0)
-
-.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/ea1f958813ebbff45161fdb468a6204be5396112/py/test/plugin/pytest_recwarn.py
+.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/85fe614ab05f301f206935d11a477df184cbbce6/py/test/plugin/pytest_recwarn.py
 .. _`extend`: ../extend.html
 .. _`plugins`: index.html
 .. _`contact`: ../../contact.html

doc/test/plugin/restdoc.txt

 
 perform ReST syntax, local and remote reference tests on .rst/.txt files.
 
+.. contents::
+  :local:
+
 
 
 command line options
 ``--forcegen``
     force generation of html files.
 
-Getting and improving this plugin