Merge pull request #2194 from rjprins/remove-reinterp-from-docs

Remove mention of --assert=reinterp in documentation

doc/en/assert.rst

@@ -262,50 +262,20 @@ Advanced assertion introspection
 .. versionadded:: 2.1
 
 
-Reporting details about a failing assertion is achieved either by rewriting
+Reporting details about a failing assertion is achieved by rewriting assert
-assert statements before they are run or re-evaluating the assert expression and
+statements before they are run.  Rewritten assert statements put introspection
-recording the intermediate values. Which technique is used depends on the
+information into the assertion failure message.  ``pytest`` only rewrites test
-location of the assert, ``pytest`` configuration, and Python version being used
+modules directly discovered by its test collection process, so asserts in
-to run ``pytest``.
+supporting modules which are not themselves test modules will not be rewritten.
-
-By default, ``pytest`` rewrites assert statements in test modules.
-Rewritten assert statements put introspection information into the assertion failure message.
-``pytest`` only rewrites test modules directly discovered by its test collection process, so
-asserts in supporting modules which are not themselves test modules will not be
-rewritten.
 
 .. note::
 
    ``pytest`` rewrites test modules on import. It does this by using an import
-   hook to write a new pyc files. Most of the time this works transparently.
+   hook to write new pyc files. Most of the time this works transparently.
    However, if you are messing with import yourself, the import hook may
-   interfere. If this is the case, simply use ``--assert=reinterp`` or
+   interfere. If this is the case, use ``--assert=plain``. Additionally,
-   ``--assert=plain``. Additionally, rewriting will fail silently if it cannot
+   rewriting will fail silently if it cannot write new pycs, i.e. in a read-only
-   write new pycs, i.e. in a read-only filesystem or a zipfile.
+   filesystem or a zipfile.
-
-If an assert statement has not been rewritten or the Python version is less than
-2.6, ``pytest`` falls back on assert reinterpretation. In assert
-reinterpretation, ``pytest`` walks the frame of the function containing the
-assert statement to discover sub-expression results of the failing assert
-statement. You can force ``pytest`` to always use assertion reinterpretation by
-passing the ``--assert=reinterp`` option.
-
-Assert reinterpretation has a caveat not present with assert rewriting: If
-evaluating the assert expression has side effects you may get a warning that the
-intermediate values could not be determined safely.  A common example of this
-issue is an assertion which reads from a file::
-
-        assert f.read() != '...'
-
-If this assertion fails then the re-evaluation will probably succeed!
-This is because ``f.read()`` will return an empty string when it is
-called the second time during the re-evaluation.  However, it is
-easy to rewrite the assertion and avoid any trouble::
-
-        content = f.read()
-        assert content != '...'
-
-All assert introspection can be turned off by passing ``--assert=plain``.
 
 For further information, Benjamin Peterson wrote up `Behind the scenes of pytest's new assertion rewriting <http://pybites.blogspot.com/2011/07/behind-scenes-of-pytests-new-assertion.html>`_.
 
@@ -318,3 +288,4 @@ For further information, Benjamin Peterson wrote up `Behind the scenes of pytest
 
 .. versionchanged:: 3.0
    Removes the ``--no-assert`` and``--nomagic`` options.
+   Removes the ``--assert=reinterp`` option.

doc/en/faq.rst

@@ -66,14 +66,6 @@ This completely avoids previous issues of confusing assertion-reporting.
 It also means, that you can use Python's ``-O`` optimization without losing
 assertions in test modules.
 
-``pytest`` contains a second, mostly obsolete, assert debugging technique
-invoked via ``--assert=reinterpret``: When an ``assert`` statement fails, ``pytest`` re-interprets
-the expression part to show intermediate values.  This technique suffers
-from a caveat that the rewriting does not: If your expression has side
-effects (better to avoid them anyway!) the intermediate values may not
-be the same, confusing the reinterpreter and obfuscating the initial
-error (this is also explained at the command line if it happens).
-
 You can also turn off all assertion interaction using the
 ``--assert=plain`` option.