fix issue129 - improve http://pytest.org/latest/faq.html

especially with respect to the "magic" history, also mention
pytest-django, trial and unittest integration.

CHANGELOG

@@ -4,6 +4,9 @@ Changes between 2.2.4 and 2.2.5.dev
 - fix issue128: show captured output when capsys/capfd are used
 - pluginmanager.register(...) now raises ValueError if the
   plugin has been already registered or the name is taken
+- fix issue129: improve http://pytest.org/latest/faq.html 
+  especially with respect to the "magic" history, also mention
+  pytest-django, trial and unittest integration.
 
 Changes between 2.2.3 and 2.2.4
 -----------------------------------

doc/en/assert.txt

@@ -2,6 +2,7 @@
 The writing and reporting of assertions in tests
 ==================================================
 
+.. _`assertfeedback`:
 .. _`assert with the assert statement`:
 
 Asserting with the ``assert`` statement

doc/en/conf.py

@@ -17,7 +17,7 @@
 #
 # The full version, including alpha/beta/rc tags.
 # The short X.Y version.
-version = release = "2.2.4.2"
+version = release = "2.2.4.3"
 
 import sys, os
 

doc/en/customize.txt

@@ -23,8 +23,9 @@ It looks for file basenames in this order::
     tox.ini
     setup.cfg
 
-Searching stops when the first ``[pytest]`` section is found.
+Searching stops when the first ``[pytest]`` section is found in any of
-There is no merging of configuration values from multiple files.  Example::
+these files.  There is no merging of configuration values from multiple 
+files.  Example:: 
 
     py.test path/to/testdir
 

doc/en/faq.txt

@@ -9,6 +9,75 @@ Some Issues and Questions
 On naming, nosetests, licensing and magic
 ------------------------------------------------
 
+How does py.test relate to nose and unittest?
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+py.test and nose_ share basic philosophy when it comes
+to running and writing Python tests.  In fact, you can run many tests
+written for nose with py.test.  nose_ was originally created
+as a clone of ``py.test`` when py.test was in the ``0.8`` release
+cycle.  Note that starting with pytest-2.0 support for running unittest
+test suites is majorly improved.
+
+how does py.test relate to twisted's trial?
+++++++++++++++++++++++++++++++++++++++++++++++
+
+Since some time py.test has builtin support for supporting tests
+written using trial. It does not itself start a reactor, however,
+and does not handle Deferreds returned from a test.  Someone using
+these features might eventually write a dedicated ``pytest-twisted`` 
+plugin which will surely see strong support from the pytest development
+team.
+ 
+how does py.test work with Django?
+++++++++++++++++++++++++++++++++++++++++++++++
+
+In 2012, some work is going into the `pytest-django plugin <http://pypi.python.org/pypi/pytest-django>`_.  It substitutes the usage of Django's
+``manage.py test`` and allows to use all pytest features_ most of which
+are not available from Django directly.
+
+.. _features: test/features.html
+
+
+What's this "magic" with py.test? (historic notes)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Around 2007 (version ``0.8``) some people thought that py.test
+was using too much "magic".  It had been part of the `pylib`_ which
+contains a lot of unreleated python library code.  Around 2010 there
+was a major cleanup refactoring, which removed unused or deprecated code 
+and resulted in the new ``pytest`` PyPI package which strictly contains
+only test-related code.  This relese also brought a complete pluginification
+such that the core is around 300 lines of code and everything else is
+implemented in plugins.  Thus ``pytest`` today is a small, universally runnable 
+and customizable testing framework for Python.   Note, however, that
+``pytest`` uses metaprogramming techniques and reading its source is 
+thus likely not something for Python beginners.
+
+A second "magic" issue was the assert statement debugging feature.  
+Nowadays, py.test explicitely rewrites assert statements in test modules
+in order to provide more useful :ref:`assert feedback <assertfeedback>`.
+This completely avoids previous issues of confusing assertion-reporting.  
+It also means, that you can use Python's ``-O`` optimization without loosing
+assertions in test modules.
+
+py.test contains a second assert debugging technique, invoked via
+``--assert=reinterpret``, activated by default on Python-2.5: When an
+``assert`` statement that was missed by the rewriter fails, py.test
+re-interprets the expression to show intermediate values if a test
+fails. This second 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
+``--assertmode=off`` option.
+
+.. _`py namespaces`: index.html
+.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py
+
+
 Why a ``py.test`` instead of a ``pytest`` command?
 ++++++++++++++++++++++++++++++++++++++++++++++++++
 
@@ -20,48 +89,7 @@ you install ``pip install pycmd`` you get these tools from a separate
 package.  These days the command line tool could be called ``pytest``
 but since many people have gotten used to the old name and there
 is another tool named "pytest" we just decided to stick with
-``py.test``.
+``py.test`` for now.
-
-How does py.test relate to nose and unittest?
-+++++++++++++++++++++++++++++++++++++++++++++++++
-
-py.test and nose_ share basic philosophy when it comes
-to running and writing Python tests.  In fact, you can run many tests
-written for nose with py.test.  nose_ was originally created
-as a clone of ``py.test`` when py.test was in the ``0.8`` release
-cycle.  Note that starting with pytest-2.0 support for running unittest
-test suites is majorly improved and you should be able to run
-many Django and Twisted test suites without modification.
-
-.. _features: test/features.html
-
-
-What's this "magic" with py.test?
-++++++++++++++++++++++++++++++++++++++++++
-
-Around 2007 (version ``0.8``) some people claimed that py.test
-was using too much "magic".  Partly this has been fixed by removing
-unused, deprecated or complicated code.  It is today probably one
-of the smallest, most universally runnable and most
-customizable testing frameworks for Python.   However,
-``py.test`` still uses many metaprogramming techniques and
-reading its source is thus likely not something for Python beginners.
-
-A second "magic" issue is arguably the assert statement debugging feature. When
-loading test modules py.test rewrites the source code of assert statements. When
-a rewritten assert statement fails, its error message has more information than
-the original. py.test also has a second assert debugging technique. When an
-``assert`` statement that was missed by the rewriter fails, py.test
-re-interprets the expression to show intermediate values if a test fails. This
-second 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 turn off all assertion debugging with ``py.test --assertmode=off``.
-
-.. _`py namespaces`: index.html
-.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py
-
 
 Function arguments, parametrized tests and setup
 -------------------------------------------------------

doc/en/links.inc

@@ -18,3 +18,4 @@
 .. _hudson: http://hudson-ci.org/
 .. _jenkins: http://jenkins-ci.org/
 .. _tox: http://codespeak.net/tox
+.. _pylib: http://pylib.org