Commits

lac committed 0379564

Difficult merge. I will now go over all the files to see that I haven't
missed a fix that happened between when I made my clone and began work and
I made my fork.

Comments (0)

Files changed (4)

-basic test configuration
+Basic test configuration
 ===================================
 
 Command line options and configuration file settings
 
 You can get help on options and ini-config values by running::
 
+XYZZY what is ini-config?  This appears to not be defined anywhere. Maybe
+swap this paragraph with the next one?
+
     py.test -h   # prints options _and_ config file settings
 
 This will display command line and configuration file settings
 which were registered by installed plugins.
 
+XYZZY how do I find out what plugins I have installed?  link to the plugin section?
 
-how test configuration is read from setup/tox ini-files
+
+How test configuration is read from setup/tox ini-files
 --------------------------------------------------------
 
 py.test searched for the first matching ini-style configuration file
     path/to/setup.cfg
     ... # up until root of filesystem
 
-If argument is provided to a py.test run, the current working directory
+XYZZY: so if I have a pytest.ini in my home directory, and I make
+a directory path also in my home directory, then py.test path/to/testdir
+will find the one in my home directory?  This is worth a warning note, 
+I think.
+
+XYZZY: what happens if I have more than one?  Does it quit after finding
+the first one, or does  the second one overwrite the values in my first one
+and so on and so forth?
+
+If no argument is provided to a py.test run, the current working directory
 is used to start the search.
 
 .. _`how to change command line options defaults`:
 .. _`adding default options`:
 
-how to change command line options defaults
+XYZZY: You need to explain norecursedirs someplace, and I think here
+       would be a good place to begin a new section.  There are other
+       good places, as long as it gets done before the section on
+       builtin configuation options. 
+
+How to override the default command line options
 ------------------------------------------------
 
-py.test provides a simple way to set some default
-command line options.  For example, if you want
-to always see detailed info on skipped and xfailed
+It can be tedious to type the same series of command line options
+every time you use py.test .  You can override the default command
+line options in your ini-style configuration directory.
+For example, if you always want
+to see detailed info on skipped and xfailed
 tests, as well as have terser "dot progress output",
 you can add this to your root directory::
 
+XYZZY you add this to your ini-style configuration file, which may live
+in but does not have to live in your root directory, no?
+
     # content of pytest.ini
     # (or tox.ini or setup.cfg)
     [pytest]
 From now on, running ``py.test`` will implicitly add
 the specified options.
 
+XYZZY: and if I have more than one file?  whose options win?
+
 builtin configuration file options
 ----------------------------------------------
 
 .. confval:: minversion
 
+XYZZY: This needs to have its terminology changed.  You do not want to
+use the English world 'minimal' here, because it does not mean what you
+think it means.  What you are describing here is not, in the
+English sense a 'minimal pytest' or a 'minimal version'  -- that would 
+be a stripped down version to work on a Maemo, or something like that.
+I think what you want is _earliest_ version.  You might have been looking
+for the english word 'miminum'.  If you assume that pytests always
+increase, then you could indeed say that the minimum version is the
+version with the lowest version number.  It would be an uncomfortable
+English usage, one that feels awkward to native English speakers,
+but not out and out wrong.  What you have is out and out
+wrong.  I'd change it to 'needsversion'.
+
+Is there any need for a way to specify that this test must be run with
+a particular version of py.test, and that version only?  If so then something
+like:
+needsversion = 2.1  # will fail if we run with anything other than pytest-2.1
+needsversion = 2.1+ # will fail if we run with anything prior to pytest-2.1
+could work.  But I have no clue if this is ever needed.
+
+   specifies the earliest pytest version which is capable of running tests.
+
+        minversion = 2.1  # will fail if we run with pytest-2.0
+
    specifies a minimal pytest version needed for running tests.
 
         minversion = 2.1  # will fail if we run with pytest-2.0
        py.test --maxfail=2 -rf test_hello.py
 
    Default is to add no options.
+XYZZY Do you mean 'If left empty'?  I think so, as in
+      addopts = #--maxfail=2 -rf comment this out for now.  Otherwise, I'd
+      just delete the line, because I don't think addopts has a default.
+
 
 .. confval:: norecursedirs
 
+XYZZY I was taught that 'recurse into a directory' was bad English.  And what
+was meant was 'descend' into a directory.  Recursion was to be left to 
+recursive programs, and their friends.  But the usage seems common now.
+I may just be old-fashioned, so I am not changing this because it would
+be a major change.
+
+XYZZY This needs to cross reference with extracol
+
    Set the directory basename patterns to avoid when recursing
    for test discovery.  The individual (fnmatch-style) patterns are
    applied to the basename of a directory to decide if to recurse into it.
         [!seq]  matches any char not in seq
 
    Default patterns are ``.* _* CVS {args}``. Setting a ``norecurse``
-   replaces the default.  Here is a customizing example for avoiding
-   a different set of directories::
+   replaces the default.  Here is an example of how to avoid certain
+   directories::
 
     # content of setup.cfg
+XYZZY you could put this in pytest.ini or tox.ini, correct?  Which makes
+me wonder what happens if you have more than one of these files?
+
     [pytest]
     norecursedirs = .svn _build tmp*
 
    One or more name prefixes determining which test functions
    and methods are considered as test modules.
 
-   See :ref:`change naming conventions` for examples.
+   See :ref:`change naming conventions` for examples of changing python_files, python_classes and python_functions.  XYZZY check to see the examples exist for
+all 3.
 
+XYZZY aren't the real examples in extracol?  Shouldn't we cross reference them?
 Why a ``py.test`` instead of a ``pytest`` command?
 ++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Some historic, some practical reasons: ``py.test`` used to be part of
-the ``py`` package which provided several developer utilities,
+Some of the reasons are historic, others are practical. ``py.test`` used 
+to be part of
+the ``py`` package which provided several developer utitilities,
 all starting with ``py.<TAB>``, providing nice TAB-completion. If
-you install ``pip install pycmd`` you get these tools from a separate
-package.  These days the command line tool could be called ``pytest``
-but then again many people have gotten used to the old name and there
+you install pycmd with  ``pip install pycmd`` you will get these tools from
+a separate
+package.  
+
+XYZZY Can you use easy_install as well?
+
+These days the command line tool could be called ``pytest``
+but since many people have become used to the name py.test and there
 is another tool named "pytest" so we just decided to stick with
 ``py.test``.
 
-What's the relation to nose and unittest?
+How does py.test relate to nose and unittest?
 +++++++++++++++++++++++++++++++++++++++++++++++++
 
-py.test and nose_ share basic philosophy when it comes
-to running Python tests.  In fact, you can run many tests
-written nose with py.test.  nose_ was originally created
+XYZZY The above is a hard sentence in english, because
+'relation' really wants the preposition 'between' (not 'to') , and really
+ wants the number of the things that are related to be two, not three.
+ Two things relate.  Three things don't -- though they can be
+ related.  Other possible wordings -- How are py.test nose and unittest
+ related?  What is py.test's relationship with the other testing frameworks,
+ nose and unittest?  
+
+py.test and nose_ share a basic philosophy when it comes
+to running Python tests.  
+
+XYZZY You might say what the philosophy is here.  You ought to say that
+      the tests themselves look virtually identical.
+
+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.  As of version 2.0 support for running unittest test
-suites is majorly improved and you should be able to run
-many Django and Twisted test suites.
+cycle.  
+
+XYZZY 'majorly' is not an English word.
+
+Version 2.0 of py.test greatly improved support for running unittest test
+suites unchanged.  As a result you can run many Django and Twisted test 
+suites.
+
+XYZZY I wasn't aware there was more than one Django or Twisted test suite.
+Maybe you meant 'There is also support for tests which invoke 3rd party
+libraries such as Django or Twisted'?  I think I just don't understand
+what you are trying to say.
 
 .. _features: test/features.html
 
 ++++++++++++++++++++++++++++++++++++++++++
 
 Around 2007 (version ``0.8``) some people claimed that py.test
-was using too much "magic".  It has been refactored a lot.  Thrown
-out old code.  Deprecated unused approaches and code.  And it is today
-probably one of the smallest, most universally runnable and most
-customizable testing frameworks for Python.   It's true that
-``py.test`` uses metaprogramming techniques, i.e. it views
-test code similar to how compilers view programs, using a
+was using too much "magic".  Since that time it has been refactored a 
+lot.  Old code was
+thrown out, and unused approaches and code were deprecated.
+
+Today it is
+one of the smallest, most universally runnable and most
+customizable testing frameworks for Python.
+
+XYZZY This last sentence is true, but it's the answer to the criticism
+      'Isn't py.test a bloated, slow, pig?' not 'Doesn't it use too much
+      magic?') Maybe you wanted to say Thus many of the complaints 
+      that py.test "uses too much magic" are based on code that does not 
+      exist today. ?  Either that or you need to explain what it is
+      that people mean when they say 'too much magic'.  Personally, I think
+      it usually means 'I looked at the code and I couldn't understand 
+      it,  because I don't understand how to use metaclasses', but you
+      probably don't want to start a war by saying something like that in
+      a faq.
+
+It's true that
+``py.test`` uses metaprogramming techniques, in order to view
+test code similarly to how compilers view programs, using a
 somewhat abstract internal model.
 
 It's also true that the no-boilerplate testing is implemented by making
 use of the Python assert statement through "re-interpretation":
 When an ``assert`` statement fails, py.test re-interprets the expression
-to show intermediate values if a test fails.  If your expression
-has side effects the intermediate values may not be the same, obfuscating
-the initial error (this is also explained at the command line if it happens).
-``py.test --no-assert`` turns off assert re-interpretation.
-Sidenote: it is good practise to avoid asserts with side effects.
+to show the intermediate values.  If that expression
+has side effects, the intermediate values may not be the same as when 
+the test initially failed, obfuscating
+the initial error.  py.test notices when this happens and prints a warning
+at the command line.
+Note that it is good practice to avoid asserts with side effects, something
+which is easy to do with py.test.  XYZZY insert reference to where this is
+explained.  
+Or you can turn off assert reinterpretation by invoking py.test as
+``py.test --no-assert``.
+
 
 .. _`py namespaces`: index.html
 .. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py
 Is using funcarg- versus xUnit setup a style question?
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-For simple applications and for people experienced with nose_ or
+Yes. For simple applications and for people experienced with nose_ or
 unittest-style test setup using `xUnit style setup`_ often
 feels natural.  For larger test suites, parametrized testing
 or setup of complex test resources using funcargs_ may feel more natural.
 
 Why the ``pytest_funcarg__*`` name for funcarg factories?
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+XYZZY: Alternatively doesn't mean 'as an alternative'.  It means to
+       alternate between exactly 2 ways of doing something.  i.e. "I
+       used red and green colours alternatively when painting my fence."
+       Your fence is striped.  If you painted half your fence red and
+       the other half green then you did not paint it alternatively.
+       This is in contrast with 'alternative' the noun and 'alternative'
+       the adjective, both of which mean "(of) one choice (out of exactly 
+       two choices)".  Strictly speaking, you should not say "there are
+       5 alternatives" (because there are, by definition, only two) and
+       instead say "there are 5 choices".  But  in informal usage,  people
+       talk about having "many alternatives" and "several alternatives"
+       all the time.  
 
-We alternatively implemented an explicit registration mechanism for
+XYZZY: According to how I reworded the next paragraph, the meaning is that
+       there once was
+       an explicit registration mechanism, but it doesn't exist any more.
+       If this is untrue -- the mechanism still exists for people who
+       prefer things this way, and the pytest_funcarg__* is merely
+       an alternative way to do this, then this paragraph will need
+       rewriting.
+
+py.test used to have an explicit registration mechanism as an alternative way
+to specify
 function argument factories.  But lacking a good use case for this
 indirection and flexibility we decided to go for `Convention over
-Configuration`_ and rather have factories specified by convention.
-Besides removing the need for an registration indirection it allows to
-"grep" for ``pytest_funcarg__MYARG`` and will safely find all factory
+Configuration`_ and instead have factories specified by convention.
+Besides removing the need for any registration indirection it allows you to
+"grep" for ``pytest_funcarg__MYARG`` which will safely find all factory
 functions for the ``MYARG`` function argument.
 
 .. _`Convention over Configuration`: http://en.wikipedia.org/wiki/Convention_over_Configuration
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 On windows the multiprocess package will instantiate sub processes
-by pickling and thus implicitly re-import a lot of local modules.
+by pickling and thus implicitely re-import a lot of local modules.
 Unfortunately, setuptools-0.6.11 does not ``if __name__=='__main__'``
 protect its generated command line script.  This leads to infinite
 recursion when running a test that instantiates Processes.
 .. _`install distribute`: http://pypi.python.org/pypi/distribute#installation-instructions
 
 .. include:: links.inc
+
+XYZZY include something about virtualenv here
+XYZZY include something about tox here

doc/goodpractices.txt

 
 .. highlightlang:: python
-.. _`goodpractises`:
+.. _`goodpractices`:
 
-Good Integration Practises
+Good Integration Practices
 =================================================
 
 Work with virtual environments
 -----------------------------------------------------------
 
-We recommend to work with virtualenv_ environments and use easy_install_
+We recommend the you work with virtualenv_ environments and use easy_install_
 (or pip_) for installing your application dependencies as well as
-the ``pytest`` package itself.  This way you get a much more reproducible
-environment.  A good tool to help you automate test runs against multiple
+the ``pytest`` package itself.  This way you will get a much more reproducible
+environment. 
+
+XYZZY is 'reprocducible' what you meant to say?  I would have thought 
+      'consistent'.
+
+             A good tool to help you automate test runs against multiple
 dependency configurations or Python interpreters is `tox`_,
-independently created by the main py.test author.  The latter
-is also useful for integration with the continuous integration
+independently created by py.test's primary author.  `tox`_
+is also useful for integration with the continous integration
 server Hudson_.
 
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _`buildout`: http://www.buildout.org/
 .. _pip: http://pypi.python.org/pypi/pip
 
-Use tox and Continuous Integration servers
+Use tox and Continous Integration servers
 -------------------------------------------------
 
-If you are (often) releasing code to the public you
+If you frequently release code to the public you
 may want to look into `tox`_, the virtualenv test automation
 tool and its `pytest support <http://codespeak.net/tox/example/pytest.html>`_.
-The basic idea is to generate a JUnitXML file through the ``--junitxml=PATH`` option and have a continuous integration server like Hudson_ pick it up.
+The basic idea is to generate a JUnitXML file through the ``--junitxml=PATH`` option and have a continous integration server like Hudson_ pick it up.
 
 .. _standalone:
 .. _`genscript method`:
 this will execute your tests using ``runtest.py``. As this is a
 standalone version of ``py.test`` no prior installation whatsoever is
 required for calling the test command. You can also pass additional
-arguments to the subprocess-calls like your test directory or other
+arguments to the subprocess-calls such as your test directory or other
 options.
 
+XYZZY Maybe an example of doing this?
+
 .. _`test discovery`:
 .. _`Python test discovery`:
 
 
 ``py.test`` implements the following standard test discovery:
 
-* collection starts from initial command line arguments
+* collection starts from the initial command line arguments
   which may be directories, filenames or test ids.
-* recurse into directories, unless they match :confval:`norecursedirs`
+* It then recurses into directories, unless they match :confval:`norecursedirs`
+
+XYZZY Again, I am not sure this isn't incorrect English, albeit commonly
+used incorrect English, and you should be talkiing about descending into
+directories.
+
+loking for:
 * ``test_*.py`` or ``*_test.py`` files, imported by their `package name`_.
 * ``Test`` prefixed test classes (without an ``__init__`` method)
 * ``test_`` prefixed test functions or methods are test items
 
-For changing and customization example, see :doc:`example/pythoncollection`.
+For and example of how to modify and customize your test discovery
+see :doc:`example/pythoncollection`.
 
 py.test additionally discovers tests using the standard
 :ref:`unittest.TestCase <unittest.TestCase>` subclassing technique.
 
     Test modules are imported under their fully qualified name as follows:
 
-    * find ``basedir`` -- this is the first "upward" directory not
-      containing an ``__init__.py``
+    * find ``basedir`` -- this is the first "upward" (towards the root)
+      directory not containing an ``__init__.py``
+
+XYZZY it's odd that in csc, up in a tree is towards its root, not its
+      branches.
 
     * perform ``sys.path.insert(0, basedir)`` to make the fully
       qualified test module path importable.
+XYZZY: general comment -- it's really icky to read code in small screenwidths,
+       so that you need to scroll it.  What you want, instead, is
+       a way to collapse all the stuff in your right hand region -- where
+       "this page" and the search box is -- to zero width, thus making it
+       possible to read the sources without scrolling.  According to
+       http://sphinx.pocoo.org/theming.html Sphinx already has this in
+       the form of a collapsible sidebar but I haven't found an example of
+       something that uses this, yet.  Found one.  Leo's doc, though
+       their sidebar is on the lhs not the rhs. 
+       http://webpages.charter.net/edreamleo/design.html
+
+XYZZY: I changed 'assert with the assert statement' to 'asserts with the 
+       assert statement' for readability.  But I am not sure I got every
+       reference.
 
 
 Welcome to ``py.test``!
 =============================================
 
 
-- **a mature fully featured testing tool**
+- **a mature full-featured testing tool**
 
  - runs on Posix/Windows, Python 2.4-3.2, PyPy and Jython
  - continuously `tested on many Python interpreters <http://hudson.testrun.org/view/pytest/job/pytest/>`_
- - used in :ref:`many projects and organisations <projects>`, ranging from 10 to 10000 tests
+ - used in :ref:`many projects and organisations <projects>`, in test suites
+   which contain 10s or 10s of thousands of tests.
  - has :ref:`comprehensive documentation <toc>`
  - comes with :ref:`tested examples <examples>`
- - supports :ref:`good integration practises <goodpractises>`
+ - supports :ref:`good integration practices <goodpractices>`
 
 - **provides no-boilerplate testing**
 
- - makes it :ref:`easy to get started <getstarted>`, refined :ref:`usage options <usage>`
- - :ref:`assert with the assert statement`
+ - makes it :ref:`easy to get started <getstarted>`
+ - has refined :ref:`usage options <usage>`
+ - :ref:`asserts with the assert statement`
  - helpful :ref:`traceback and failing assertion reporting <tbreportdemo>`
- - allows :ref:`print debugging <printdebugging>` and :ref:`generic output
-   capturing <captures>`
- - supports :pep:`8` compliant coding style in tests
+ - allows :ref:`print debugging <printdebugging>` and :ref:`the
+   capturing  of generic output <captures>`
+ - supports the :pep:`8`-compliant coding style in tests
+
+XYZZY: or :pep:`8`-compliant coding styles?  depends on whether you think
+PEP 8 supports one or multiple styles.
 
 - **supports functional testing and complex test setups**
 
  - advanced :ref:`skip and xfail`
  - generic :ref:`marking and test selection <mark>`
  - can :ref:`distribute tests to multiple CPUs <xdistcpu>` through :ref:`xdist plugin <xdist>`
- - can :ref:`continuously re-run failing tests <looponfailing>`
+ - can :ref:`continously re-run failing tests <looponfailing>`
  - many :ref:`builtin helpers <pytest helpers>`
  - flexible :ref:`Python test discovery`
  - unique :ref:`dependency injection through funcargs <funcargs>`
    tests, including running testcases made for Django and trial
  - supports extended :ref:`xUnit style setup <xunitsetup>`
  - supports domain-specific :ref:`non-python tests`
- - supports generating testing coverage reports
+ - supports the generation of  testing coverage reports
  - `Javascript unit- and functional testing`_
 
 - **extensive plugin and customization system**