diff options
author | Bruno Oliveira <nicoddemus@gmail.com> | 2018-03-15 12:04:34 -0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-03-15 12:04:34 -0300 |
commit | fbcf1a90c9ffa849827918249fef1721a1f43bdd (patch) | |
tree | 49ccb08c2a2349644211fd4fc2da6a5e757d676d /_pytest | |
parent | 1b535387bfc68bd8d0e1971558d5d7ac9f9e129a (diff) | |
parent | 51c0256cd4f069449651b82a35a98e8f54c73b4b (diff) | |
download | pytest-fbcf1a90c9ffa849827918249fef1721a1f43bdd.tar.gz |
Merge pull request #3193 from pytest-dev/ref-docs
Reference docs
Diffstat (limited to '_pytest')
-rw-r--r-- | _pytest/capture.py | 17 | ||||
-rw-r--r-- | _pytest/config.py | 2 | ||||
-rw-r--r-- | _pytest/doctest.py | 2 | ||||
-rw-r--r-- | _pytest/fixtures.py | 12 | ||||
-rw-r--r-- | _pytest/junitxml.py | 5 | ||||
-rw-r--r-- | _pytest/mark.py | 15 | ||||
-rw-r--r-- | _pytest/python.py | 2 | ||||
-rw-r--r-- | _pytest/python_api.py | 5 | ||||
-rw-r--r-- | _pytest/recwarn.py | 13 | ||||
-rw-r--r-- | _pytest/tmpdir.py | 2 |
10 files changed, 56 insertions, 19 deletions
diff --git a/_pytest/capture.py b/_pytest/capture.py index fc429e073..6e2139445 100644 --- a/_pytest/capture.py +++ b/_pytest/capture.py @@ -197,9 +197,9 @@ def _ensure_only_one_capture_fixture(request, name): @pytest.fixture def capsys(request): - """Enable capturing of writes to sys.stdout/sys.stderr and make + """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make captured output available via ``capsys.readouterr()`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` + which return a ``(out, err)`` namedtuple. ``out`` and ``err`` will be ``text`` objects. """ _ensure_only_one_capture_fixture(request, 'capsys') @@ -209,7 +209,7 @@ def capsys(request): @pytest.fixture def capsysbinary(request): - """Enable capturing of writes to sys.stdout/sys.stderr and make + """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make captured output available via ``capsys.readouterr()`` method calls which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``bytes`` objects. @@ -225,7 +225,7 @@ def capsysbinary(request): @pytest.fixture def capfd(request): - """Enable capturing of writes to file descriptors 1 and 2 and make + """Enable capturing of writes to file descriptors ``1`` and ``2`` and make captured output available via ``capfd.readouterr()`` method calls which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` objects. @@ -272,6 +272,10 @@ def _install_capture_fixture_on_item(request, capture_class): class CaptureFixture(object): + """ + Object returned by :py:func:`capsys`, :py:func:`capsysbinary`, :py:func:`capfd` and :py:func:`capfdbinary` + fixtures. + """ def __init__(self, captureclass, request): self.captureclass = captureclass self.request = request @@ -288,6 +292,10 @@ class CaptureFixture(object): cap.stop_capturing() def readouterr(self): + """Read and return the captured output so far, resetting the internal buffer. + + :return: captured content as a namedtuple with ``out`` and ``err`` string attributes + """ try: return self._capture.readouterr() except AttributeError: @@ -295,6 +303,7 @@ class CaptureFixture(object): @contextlib.contextmanager def disabled(self): + """Temporarily disables capture while inside the 'with' block.""" self._capture.suspend_capturing() capmanager = self.request.config.pluginmanager.getplugin('capturemanager') capmanager.suspend_global_capture(item=None, in_=False) diff --git a/_pytest/config.py b/_pytest/config.py index 359cc4bc8..e8bfeccb4 100644 --- a/_pytest/config.py +++ b/_pytest/config.py @@ -169,7 +169,7 @@ class PytestPluginManager(PluginManager): Overwrites :py:class:`pluggy.PluginManager <pluggy.PluginManager>` to add pytest-specific functionality: - * loading plugins from the command line, ``PYTEST_PLUGIN`` env variable and + * loading plugins from the command line, ``PYTEST_PLUGINS`` env variable and ``pytest_plugins`` global variables found in plugins being loaded; * ``conftest.py`` loading during start-up; """ diff --git a/_pytest/doctest.py b/_pytest/doctest.py index f54f833ec..a7bb2598c 100644 --- a/_pytest/doctest.py +++ b/_pytest/doctest.py @@ -379,6 +379,6 @@ def _fix_spoof_python2(runner, encoding): @pytest.fixture(scope='session') def doctest_namespace(): """ - Inject names into the doctest namespace. + Fixture that returns a :py:class:`dict` that will be injected into the namespace of doctests. """ return dict() diff --git a/_pytest/fixtures.py b/_pytest/fixtures.py index f9d0ef572..c4d5f726d 100644 --- a/_pytest/fixtures.py +++ b/_pytest/fixtures.py @@ -858,7 +858,7 @@ class FixtureFunctionMarker(object): def fixture(scope="function", params=None, autouse=False, ids=None, name=None): - """ (return a) decorator to mark a fixture factory function. + """Decorator to mark a fixture factory function. This decorator can be used (with or without parameters) to define a fixture function. The name of the fixture function can later be @@ -923,7 +923,15 @@ defaultfuncargprefixmarker = fixture() @fixture(scope="session") def pytestconfig(request): - """ the pytest config object with access to command line opts.""" + """Session-scoped fixture that returns the :class:`_pytest.config.Config` object. + + Example:: + + def test_foo(pytestconfig): + if pytestconfig.getoption("verbose"): + ... + + """ return request.config diff --git a/_pytest/junitxml.py b/_pytest/junitxml.py index e929eeba8..50f4e4084 100644 --- a/_pytest/junitxml.py +++ b/_pytest/junitxml.py @@ -200,6 +200,11 @@ def record_xml_property(request): """Add extra xml properties to the tag for the calling test. The fixture is callable with ``(name, value)``, with value being automatically xml-encoded. + + Example:: + + def test_function(record_xml_property): + record_xml_property("example_key", 1) """ request.node.warn( code='C3', diff --git a/_pytest/mark.py b/_pytest/mark.py index 3cac9dc91..ef7b937e9 100644 --- a/_pytest/mark.py +++ b/_pytest/mark.py @@ -116,6 +116,21 @@ class MarkerError(Exception): def param(*values, **kw): + """Specify a parameter in a `pytest.mark.parametrize`_ call. + + .. code-block:: python + + @pytest.mark.parametrize("test_input,expected", [ + ("3+5", 8), + pytest.param("6*9", 42, marks=pytest.mark.xfail), + ]) + def test_eval(test_input, expected): + assert eval(test_input) == expected + + :param values: variable args of the values of the parameter set, in order. + :keyword marks: a single mark or a list of marks to be applied to this parameter set. + :keyword str id: the id to attribute to this parameter set. + """ return ParameterSet.param(*values, **kw) diff --git a/_pytest/python.py b/_pytest/python.py index fb7bac8b8..d299d0987 100644 --- a/_pytest/python.py +++ b/_pytest/python.py @@ -717,7 +717,7 @@ class CallSpec2(object): class Metafunc(fixtures.FuncargnamesCompatAttr): """ - Metafunc objects are passed to the ``pytest_generate_tests`` hook. + Metafunc objects are passed to the :func:`pytest_generate_tests <_pytest.hookspec.pytest_generate_tests>` hook. They help to inspect a test function and to generate tests according to test configuration or values specified in the class or module where a test function is defined. diff --git a/_pytest/python_api.py b/_pytest/python_api.py index 541371449..e5a73a353 100644 --- a/_pytest/python_api.py +++ b/_pytest/python_api.py @@ -547,8 +547,9 @@ def raises(expected_exception, *args, **kwargs): The string will be evaluated using the same ``locals()`` and ``globals()`` at the moment of the ``raises`` call. - .. autoclass:: _pytest._code.ExceptionInfo - :members: + .. currentmodule:: _pytest._code + + Consult the API of ``excinfo`` objects: :class:`ExceptionInfo`. .. note:: Similar to caught exception objects in Python, explicitly clearing diff --git a/_pytest/recwarn.py b/_pytest/recwarn.py index 4fceb10a7..ab0f79c75 100644 --- a/_pytest/recwarn.py +++ b/_pytest/recwarn.py @@ -16,10 +16,7 @@ from _pytest.outcomes import fail @yield_fixture def recwarn(): - """Return a WarningsRecorder instance that provides these methods: - - * ``pop(category=None)``: return last warning matching the category. - * ``clear()``: clear list of warnings + """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions. See http://docs.python.org/library/warnings.html for information on warning categories. @@ -88,11 +85,11 @@ class _DeprecatedCallContext(object): def warns(expected_warning, *args, **kwargs): """Assert that code raises a particular class of warning. - Specifically, the input @expected_warning can be a warning class or - tuple of warning classes, and the code must return that warning - (if a single class) or one of those warnings (if a tuple). + Specifically, the parameter ``expected_warning`` can be a warning class or + sequence of warning classes, and the inside the ``with`` block must issue a warning of that class or + classes. - This helper produces a list of ``warnings.WarningMessage`` objects, + This helper produces a list of :class:`warnings.WarningMessage` objects, one for each warning raised. This function can be used as a context manager, or any of the other ways diff --git a/_pytest/tmpdir.py b/_pytest/tmpdir.py index 66b4a2d2f..315ead302 100644 --- a/_pytest/tmpdir.py +++ b/_pytest/tmpdir.py @@ -116,6 +116,8 @@ def tmpdir(request, tmpdir_factory): created as a sub directory of the base temporary directory. The returned object is a `py.path.local`_ path object. + + .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html """ name = request.node.name name = re.sub(r"[\W]", "_", name) |