From f7178654e588d88c2e9f1958635762856c6c67c7 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Tue, 27 Feb 2018 18:26:40 -0300 Subject: [PATCH] Add recwarn and tmpdir fixtures to the reference docs --- _pytest/recwarn.py | 13 ++++----- _pytest/tmpdir.py | 2 ++ doc/en/reference.rst | 66 ++++++++++++++++++++++++++++++++++++++++++-- doc/en/tmpdir.rst | 9 +++--- doc/en/warnings.rst | 18 ++---------- 5 files changed, 78 insertions(+), 30 deletions(-) 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) diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 77a8ba11a..a06e37007 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -9,8 +9,8 @@ This page contains the full reference to pytest's API. :local: -approx ------- +pytest.approx +------------- .. autofunction:: _pytest.python_api.approx @@ -67,6 +67,15 @@ pytest.deprecated_call .. autofunction:: _pytest.recwarn.deprecated_call :with: +pytest.warns +------------ + +**Tutorial**: :ref:`assertwarnings` + +.. autofunction:: _pytest.recwarn.warns + :with: + + .. _`hook-reference`: Hooks @@ -250,6 +259,10 @@ Full reference to objects accessible from :ref:`fixtures ` or hooks .. autoclass:: pluggy.PluginManager() :members: +.. autoclass:: pluggy.PluginManager() + :members: + + Fixtures -------- @@ -485,3 +498,52 @@ To use it, include in your top-most ``conftest.py`` file:: .. autoclass:: LineMatcher() :members: + + +recwarn +~~~~~~~ + +**Tutorial**: :ref:`assertwarnings` + +.. currentmodule:: _pytest.recwarn + +.. autofunction:: recwarn() + :no-auto-options: + +.. autoclass:: _pytest.recwarn.WarningsRecorder() + :members: + +Each recorded warning is an instance of :class:`warnings.WarningMessage`. + +.. note:: + :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1 + +.. note:: + ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated + differently; see :ref:`ensuring_function_triggers`. + + +tmpdir +~~~~~~ + +**Tutorial**: :doc:`tmpdir` + +.. currentmodule:: _pytest.tmpdir + +.. autofunction:: tmpdir() + :no-auto-options: + + +tmpdir_factory +~~~~~~~~~~~~~~ + +**Tutorial**: :ref:`tmpdir factory example` + +.. _`tmpdir factory api`: + +``tmpdir_factory`` instances have the following methods: + +.. currentmodule:: _pytest.tmpdir + +.. automethod:: TempdirFactory.mktemp +.. automethod:: TempdirFactory.getbasetemp diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst index b9c371e40..e01d359e0 100644 --- a/doc/en/tmpdir.rst +++ b/doc/en/tmpdir.rst @@ -51,6 +51,9 @@ Running this would result in a passed test except for the last test_tmpdir.py:7: AssertionError ========================= 1 failed in 0.12 seconds ========================= + +.. _`tmpdir factory example`: + The 'tmpdir_factory' fixture ---------------------------- @@ -81,12 +84,8 @@ to save time: img = load_image(image_file) # compute and test histogram -``tmpdir_factory`` instances have the following methods: +See :ref:`tmpdir_factory API ` for details. -.. currentmodule:: _pytest.tmpdir - -.. automethod:: TempdirFactory.mktemp -.. automethod:: TempdirFactory.getbasetemp .. _`base temporary directory`: diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst index d5a627aea..df61e1f38 100644 --- a/doc/en/warnings.rst +++ b/doc/en/warnings.rst @@ -250,23 +250,11 @@ The ``recwarn`` fixture will record warnings for the whole function:: Both ``recwarn`` and ``pytest.warns`` return the same interface for recorded warnings: a WarningsRecorder instance. To view the recorded warnings, you can iterate over this instance, call ``len`` on it to get the number of recorded -warnings, or index into it to get a particular recorded warning. It also -provides these methods: +warnings, or index into it to get a particular recorded warning. -.. autoclass:: _pytest.recwarn.WarningsRecorder() - :members: +.. currentmodule:: _pytest.warnings -Each recorded warning has the attributes ``message``, ``category``, -``filename``, ``lineno``, ``file``, and ``line``. The ``category`` is the -class of the warning. The ``message`` is the warning itself; calling -``str(message)`` will return the actual message of the warning. - -.. note:: - :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1 - -.. note:: - ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated - differently; see :ref:`ensuring_function_triggers`. +Full API: :class:`WarningsRecorder`. .. _`ensuring a function triggers a deprecation warning`: