Merge pull request #2625 from nicoddemus/historical-notes

Historical notes in the docs

Author: nicoddemus

doc/en/cache.rst

@@ -5,14 +5,6 @@ Cache: working with cross-testrun state
 
 .. versionadded:: 2.8
 
-.. warning::
-
-  The functionality of this core plugin was previously distributed
-  as a third party plugin named ``pytest-cache``.  The core plugin
-  is compatible regarding command line options and API usage except that you
-  can only store/receive data between test runs that is json-serializable.
-
-
 Usage
 ---------
 

doc/en/contact.rst

@@ -19,9 +19,9 @@ Contact channels
 - `pytest-commit at python.org (mailing list)`_: for commits and new issues
 
 - :doc:`contribution guide <contributing>` for help on submitting pull
-  requests to bitbucket (including using git via gitifyhg).
+  requests to GitHub.
 
-- #pylib on irc.freenode.net IRC channel for random questions.
+- ``#pylib`` on irc.freenode.net IRC channel for random questions.
 
 - private mail to Holger.Krekel at gmail com if you want to communicate sensitive issues
 
@@ -46,6 +46,5 @@ Contact channels
 .. _`py-dev`:
 .. _`development mailing list`:
 .. _`pytest-dev at python.org (mailing list)`: http://mail.python.org/mailman/listinfo/pytest-dev
-.. _`py-svn`:
 .. _`pytest-commit at python.org (mailing list)`: http://mail.python.org/mailman/listinfo/pytest-commit
 

doc/en/contents.rst

@@ -38,6 +38,7 @@ Full pytest documentation
    bash-completion
 
    backwards-compatibility
+   historical-notes
    license
    contributing
    talks

doc/en/example/attic.rst

@@ -17,7 +17,7 @@ example: specifying and selecting acceptance tests
 
     class AcceptFixture(object):
         def __init__(self, request):
-            if not request.config.option.acceptance:
+            if not request.config.getoption('acceptance'):
                 pytest.skip("specify -A to run acceptance tests")
             self.tmpdir = request.config.mktemp(request.function.__name__, numbered=True)
 

doc/en/example/markers.rst

@@ -173,14 +173,18 @@ Or to select "http" and "quick" tests::
 
 .. note::
 
-    If you are using expressions such as "X and Y" then both X and Y
-    need to be simple non-keyword names.  For example, "pass" or "from"
-    will result in SyntaxErrors because "-k" evaluates the expression.
-
-    However, if the "-k" argument is a simple string, no such restrictions
-    apply.  Also "-k 'not STRING'" has no restrictions.  You can also
-    specify numbers like "-k 1.3" to match tests which are parametrized
-    with the float "1.3".
+    If you are using expressions such as ``"X and Y"`` then both ``X`` and ``Y``
+    need to be simple non-keyword names. For example, ``"pass"`` or ``"from"``
+    will result in SyntaxErrors because ``"-k"`` evaluates the expression using
+    Python's `eval`_ function.
+
+.. _`eval`: https://docs.python.org/3.6/library/functions.html#eval
+
+
+    However, if the ``"-k"`` argument is a simple string, no such restrictions
+    apply. Also ``"-k 'not STRING'"`` has no restrictions.  You can also
+    specify numbers like ``"-k 1.3"`` to match tests which are parametrized
+    with the float ``"1.3"``.
 
 Registering markers
 -------------------------------------

doc/en/example/parametrize.rst

@@ -36,7 +36,7 @@ Now we add a test configuration like this::
 
     def pytest_generate_tests(metafunc):
         if 'param1' in metafunc.fixturenames:
-            if metafunc.config.option.all:
+            if metafunc.config.getoption('all'):
                 end = 5
             else:
                 end = 2

doc/en/fixture.rst

@@ -109,20 +109,14 @@ Note that if you misspell a function argument or want
 to use one that isn't available, you'll see an error
 with a list of available function arguments.
 
-.. Note::
+.. note::
 
     You can always issue::
 
         pytest --fixtures test_simplefactory.py
 
     to see available fixtures.
 
-    In versions prior to 2.3 there was no ``@pytest.fixture`` marker
-    and you had to use a magic ``pytest_funcarg__NAME`` prefix
-    for the fixture factory.  This remains and will remain supported
-    but is not anymore advertised as the primary means of declaring fixture
-    functions.
-
 Fixtures: a prime example of dependency injection
 ---------------------------------------------------
 
@@ -292,14 +286,6 @@ the ``with`` statement ends.
 Note that if an exception happens during the *setup* code (before the ``yield`` keyword), the
 *teardown* code (after the ``yield``) will not be called.
 
-
-.. note::
-    Prior to version 2.10, in order to use a ``yield`` statement to execute teardown code one
-    had to mark a fixture using the ``yield_fixture`` marker. From 2.10 onward, normal
-    fixtures can use ``yield`` directly so the ``yield_fixture`` decorator is no longer needed
-    and considered deprecated.
-
-
 An alternative option for executing *teardown* code is to
 make use of the ``addfinalizer`` method of the `request-context`_ object to register
 finalization functions.

doc/en/goodpractices.rst

@@ -249,15 +249,6 @@ by putting them into a ``[tool:pytest]`` section:
     python_files = testing/*/*.py
 
 
-.. note::
-    Prior to 3.0, the supported section name was ``[pytest]``. Due to how
-    this may collide with some distutils commands, the recommended
-    section name for ``setup.cfg`` files is now ``[tool:pytest]``.
-
-    Note that for ``pytest.ini`` and ``tox.ini`` files the section
-    name is ``[pytest]``.
-
-
 Manual Integration
 ^^^^^^^^^^^^^^^^^^
 

doc/en/historical-notes.rst

@@ -0,0 +1,177 @@
+Historical Notes
+================
+
+This page lists features or behavior from previous versions of pytest which have changed over the years. They are
+kept here as a historical note so users looking at old code can find documentation related to them.
+
+cache plugin integrated into the core
+-------------------------------------
+
+.. versionadded:: 2.8
+
+The functionality of the :ref:`core cache <cache>` plugin was previously distributed
+as a third party plugin named ``pytest-cache``.  The core plugin
+is compatible regarding command line options and API usage except that you
+can only store/receive data between test runs that is json-serializable.
+
+
+funcargs and ``pytest_funcarg__``
+---------------------------------
+
+.. versionchanged:: 2.3
+
+In versions prior to 2.3 there was no ``@pytest.fixture`` marker
+and you had to use a magic ``pytest_funcarg__NAME`` prefix
+for the fixture factory.  This remains and will remain supported
+but is not anymore advertised as the primary means of declaring fixture
+functions.
+
+
+``@pytest.yield_fixture`` decorator
+-----------------------------------
+
+.. versionchanged:: 2.10
+
+Prior to version 2.10, in order to use a ``yield`` statement to execute teardown code one
+had to mark a fixture using the ``yield_fixture`` marker. From 2.10 onward, normal
+fixtures can use ``yield`` directly so the ``yield_fixture`` decorator is no longer needed
+and considered deprecated.
+
+
+``[pytest]`` header in ``setup.cfg``
+------------------------------------
+
+.. versionchanged:: 3.0
+
+Prior to 3.0, the supported section name was ``[pytest]``. Due to how
+this may collide with some distutils commands, the recommended
+section name for ``setup.cfg`` files is now ``[tool:pytest]``.
+
+Note that for ``pytest.ini`` and ``tox.ini`` files the section
+name is ``[pytest]``.
+
+
+Applying marks to ``@pytest.mark.parametrize`` parameters
+---------------------------------------------------------
+
+.. versionchanged:: 3.1
+
+Prior to version 3.1 the supported mechanism for marking values
+used the syntax::
+
+    import pytest
+    @pytest.mark.parametrize("test_input,expected", [
+        ("3+5", 8),
+        ("2+4", 6),
+        pytest.mark.xfail(("6*9", 42),),
+    ])
+    def test_eval(test_input, expected):
+        assert eval(test_input) == expected
+
+
+This was an initial hack to support the feature but soon was demonstrated to be incomplete,
+broken for passing functions or applying multiple marks with the same name but different parameters.
+
+The old syntax is planned to be removed in pytest-4.0.
+
+
+``@pytest.mark.parametrize`` argument names as a tuple
+------------------------------------------------------
+
+.. versionchanged:: 2.4
+
+In versions prior to 2.4 one needed to specify the argument
+names as a tuple.  This remains valid but the simpler ``"name1,name2,..."``
+comma-separated-string syntax is now advertised first because
+it's easier to write and produces less line noise.
+
+
+setup: is now an "autouse fixture"
+----------------------------------
+
+.. versionchanged:: 2.3
+
+During development prior to the pytest-2.3 release the name
+``pytest.setup`` was used but before the release it was renamed
+and moved to become part of the general fixture mechanism,
+namely :ref:`autouse fixtures`
+
+
+.. _string conditions:
+
+Conditions as strings instead of booleans
+-----------------------------------------
+
+.. versionchanged:: 2.4
+
+Prior to pytest-2.4 the only way to specify skipif/xfail conditions was
+to use strings::
+
+    import sys
+    @pytest.mark.skipif("sys.version_info >= (3,3)")
+    def test_function():
+        ...
+
+During test function setup the skipif condition is evaluated by calling
+``eval('sys.version_info >= (3,0)', namespace)``.  The namespace contains
+all the module globals, and ``os`` and ``sys`` as a minimum.
+
+Since pytest-2.4 :ref:`boolean conditions <condition booleans>` are considered preferable
+because markers can then be freely imported between test modules.
+With strings you need to import not only the marker but all variables
+used by the marker, which violates encapsulation.
+
+The reason for specifying the condition as a string was that ``pytest`` can
+report a summary of skip conditions based purely on the condition string.
+With conditions as booleans you are required to specify a ``reason`` string.
+
+Note that string conditions will remain fully supported and you are free
+to use them if you have no need for cross-importing markers.
+
+The evaluation of a condition string in ``pytest.mark.skipif(conditionstring)``
+or ``pytest.mark.xfail(conditionstring)`` takes place in a namespace
+dictionary which is constructed as follows:
+
+* the namespace is initialized by putting the ``sys`` and ``os`` modules
+  and the pytest ``config`` object into it.
+
+* updated with the module globals of the test function for which the
+  expression is applied.
+
+The pytest ``config`` object allows you to skip based on a test
+configuration value which you might have added::
+
+    @pytest.mark.skipif("not config.getvalue('db')")
+    def test_function(...):
+        ...
+
+The equivalent with "boolean conditions" is::
+
+    @pytest.mark.skipif(not pytest.config.getvalue("db"),
+                        reason="--db was not specified")
+    def test_function(...):
+        pass
+
+.. note::
+
+    You cannot use ``pytest.config.getvalue()`` in code
+    imported before pytest's argument parsing takes place.  For example,
+    ``conftest.py`` files are imported before command line parsing and thus
+    ``config.getvalue()`` will not execute correctly.
+
+``pytest.set_trace()``
+----------------------
+
+.. versionchanged:: 2.4
+
+Previous to version 2.4 to set a break point in code one needed to use ``pytest.set_trace()``::
+
+    import pytest
+    def test_function():
+        ...
+        pytest.set_trace()    # invoke PDB debugger and tracing
+
+
+This is no longer needed and one can use the native ``import pdb;pdb.set_trace()`` call directly.
+
+For more details see :ref:`breakpoints`.

doc/en/parametrize.rst

@@ -99,26 +99,6 @@ for example with the builtin ``mark.xfail``::
     def test_eval(test_input, expected):
         assert eval(test_input) == expected
 
-.. note::
-
-  prior to version 3.1 the supported mechanism for marking values
-  used the syntax::
-
-        import pytest
-        @pytest.mark.parametrize("test_input,expected", [
-            ("3+5", 8),
-            ("2+4", 6),
-            pytest.mark.xfail(("6*9", 42),),
-        ])
-        def test_eval(test_input, expected):
-            assert eval(test_input) == expected
-
-
-  This was an initial hack to support the feature but soon was demonstrated to be incomplete,
-  broken for passing functions or applying multiple marks with the same name but different parameters.
-  The old syntax will be removed in pytest-4.0.
-
-
 Let's run this::
 
     $ pytest
@@ -143,15 +123,8 @@ To get all combinations of multiple parametrized arguments you can stack
     def test_foo(x, y):
         pass
 
-This will run the test with the arguments set to x=0/y=2, x=0/y=3, x=1/y=2 and
-x=1/y=3.
-
-.. note::
-
-    In versions prior to 2.4 one needed to specify the argument
-    names as a tuple.  This remains valid but the simpler ``"name1,name2,..."``
-    comma-separated-string syntax is now advertised first because
-    it's easier to write and produces less line noise.
+This will run the test with the arguments set to ``x=0/y=2``, ``x=0/y=3``, ``x=1/y=2`` and
+``x=1/y=3``.
 
 .. _`pytest_generate_tests`:
 
@@ -187,7 +160,7 @@ command line option and the parametrization of our test function::
     def pytest_generate_tests(metafunc):
         if 'stringinput' in metafunc.fixturenames:
             metafunc.parametrize("stringinput",
-                                 metafunc.config.option.stringinput)
+                                 metafunc.config.getoption('stringinput'))
 
 If we now pass two stringinput values, our test will run twice::