Commits

Jurko Gospodnetić committed 896c7b1

Documentation cleanup - corrected typos & minor stylistic changes.

Comments (0)

Files changed (20)

         self._ids = py.builtin.set()
 
     def parametrize(self, argnames, argvalues, indirect=False, ids=None):
-        """ add new invocations to the underlying test function using the
-        list of argvalues for the given argnames.  Parametrization is performed
+        """ Add new invocations to the underlying test function using the list
+        of argvalues for the given argnames.  Parametrization is performed
         during the collection phase.  If you need to setup expensive resources
         you may pass indirect=True and implement a funcarg factory which can
         perform the expensive setup just before a test is actually run.
         :arg argvalues: a list of values for the argname or a list of tuples of
             values for the list of argument names.
 
-        :arg indirect: if True each argvalue corresponding to an argument will be
-            passed as request.param to its respective funcarg factory so that
-            it can perform more expensive setups during the setup phase of
+        :arg indirect: if True each argvalue corresponding to an argument will
+            be passed as request.param to its respective funcarg factory so
+            that it can perform more expensive setups during the setup phase of
             a test rather than at collection time.
 
-        :arg ids: list of string ids each corresponding to the argvalues
-            so that they are part of the test id. If no ids are provided
-            they will be generated automatically from the argvalues.
+        :arg ids: list of string ids each corresponding to the argvalues so
+            that they are part of the test id. If no ids are provided they will
+            be generated automatically from the argvalues.
         """
         if not isinstance(argnames, (tuple, list)):
             argnames = (argnames,)
         self._calls = newcalls
 
     def addcall(self, funcargs=None, id=_notexists, param=_notexists):
-        """ (deprecated, use parametrize) add a new call to the underlying
-        test function during
-        the collection phase of a test run.  Note that request.addcall() is
-        called during the test collection phase prior and independently
-        to actual test execution.  You should only use addcall()
-        if you need to specify multiple arguments of a test function
+        """ (deprecated, use parametrize) Add a new call to the underlying
+        test function during the collection phase of a test run.  Note that
+        request.addcall() is called during the test collection phase prior and
+        independently to actual test execution.  You should only use addcall()
+        if you need to specify multiple arguments of a test function.
 
         :arg funcargs: argument keyword dictionary used when invoking
             the test function.
 
 
     def applymarker(self, marker):
-        """ apply a marker to a single test function invocation.
+        """ Apply a marker to a single test function invocation.
         This method is useful if you don't want to have a keyword/marker
         on all function invocations.
 
         self._pyfuncitem.keywords[marker.markname] = marker
 
     def cached_setup(self, setup, teardown=None, scope="module", extrakey=None):
-        """ return a testing resource managed by ``setup`` &
+        """ Return a testing resource managed by ``setup`` &
         ``teardown`` calls.  ``scope`` and ``extrakey`` determine when the
         ``teardown`` function will be called so that subsequent calls to
         ``setup`` would recreate the resource.
         >>> raises(ZeroDivisionError, f, x=0)
         <ExceptionInfo ...>
 
-    A third possibility is to use a string which which will
-    be executed::
+    A third possibility is to use a string to be executed::
 
         >>> raises(ZeroDivisionError, "f(0)")
         <ExceptionInfo ...>

doc/announce/release-2.0.2.txt

-py.test 2.0.2: bug fixes, improved xfail/skip expressions, speedups
+py.test 2.0.2: bug fixes, improved xfail/skip expressions, speed ups
 ===========================================================================
 
 Welcome to pytest-2.0.2, a maintenance and bug fix release of pytest,
 
   Also you can now access module globals from xfail/skipif
   expressions so that this for example works now::
- 
+
     import pytest
     import mymodule
     @pytest.mark.skipif("mymodule.__version__[0] == "1")
     def test_function():
         pass
 
-  This will not run the test function if the module's version string 
+  This will not run the test function if the module's version string
   does not start with a "1".  Note that specifying a string instead
-  of a boolean expressions allows py.test to report meaningful information 
-  when summarizing a test run as to what conditions lead to skipping 
+  of a boolean expressions allows py.test to report meaningful information
+  when summarizing a test run as to what conditions lead to skipping
   (or xfail-ing) tests.
 
 - fix issue28 - setup_method and pytest_generate_tests work together
 - fixed typos in the docs (thanks Victor Garcia, Brianna Laugher) and particular
   thanks to Laura Creighton who also revieved parts of the documentation.
 
-- fix slighly wrong output of verbose progress reporting for classes 
+- fix slighly wrong output of verbose progress reporting for classes
   (thanks Amaury)
 
 - more precise (avoiding of) deprecation warnings for node.Class|Function accesses

doc/announce/release-2.1.0.txt

 py.test 2.1.0: perfected assertions and bug fixes
 ===========================================================================
 
-Welcome to the relase of pytest-2.1, a mature testing tool for Python,
+Welcome to the release of pytest-2.1, a mature testing tool for Python,
 supporting CPython 2.4-3.2, Jython and latest PyPy interpreters.  See
 the improved extensive docs (now also as PDF!) with tested examples here:
 
 See http://pytest.org/assert.html#advanced-assertion-introspection for
 detailed information.  The work has been partly sponsored by my company,
 merlinux GmbH.
-  
+
 For further details on bug fixes and smaller enhancements see below.
 
 If you want to install or upgrade pytest, just type one of::
   unexpected exceptions
 - fix issue47: timing output in junitxml for test cases is now correct
 - fix issue48: typo in MarkInfo repr leading to exception
-- fix issue49: avoid confusing error when initizaliation partially fails
+- fix issue49: avoid confusing error when initialization partially fails
 - fix issue44: env/username expansion for junitxml file path
 - show releaselevel information in test runs for pypy
 - reworked doc pages for better navigation and PDF generation
 - report KeyboardInterrupt even if interrupted during session startup
 - fix issue 35 - provide PDF doc version and download link from index page
-

doc/announce/release-2.2.0.txt

 ===========================================================================
 
 pytest-2.2.0 is a test-suite compatible release of the popular
-py.test testing tool.  Plugins might need upgrades. It comes 
+py.test testing tool.  Plugins might need upgrades. It comes
 with these improvements:
 
 * easier and more powerful parametrization of tests:
   - the new "--strict" bails out with an error if using unregistered markers.
   - see examples at http://pytest.org/latest/example/markers.html
 
-* duration profiling: new "--duration=N" option showing the N slowest test 
+* duration profiling: new "--duration=N" option showing the N slowest test
   execution or setup/teardown calls. This is most useful if you want to
   find out where your slowest test code is.
 
-* also 2.2.0 performs more eager calling of teardown/finalizers functions 
+* also 2.2.0 performs more eager calling of teardown/finalizers functions
   resulting in better and more accurate reporting when they fail
 
 Besides there is the usual set of bug fixes along with a cleanup of
 
 While test suites should work unchanged you might need to upgrade plugins:
 
-* You need a new version of the pytest-xdist plugin (1.7) for distributing 
-  test runs.  
+* You need a new version of the pytest-xdist plugin (1.7) for distributing
+  test runs.
 
 * Other plugins might need an upgrade if they implement
   the ``pytest_runtest_logreport`` hook which now is called unconditionally
   for the setup/teardown fixture phases of a test. You may choose to
   ignore setup/teardown failures by inserting "if rep.when != 'call': return"
-  or something similar. Note that most code probably "just" works because 
+  or something similar. Note that most code probably "just" works because
   the hook was already called for failing setup/teardown phases of a test
   so a plugin should have been ready to grok such reports already.
 
 
 - fix issue90: introduce eager tearing down of test items so that
   teardown function are called earlier.
-- add an all-powerful metafunc.parametrize function which allows to 
+- add an all-powerful metafunc.parametrize function which allows to
   parametrize test function arguments in multiple steps and therefore
-  from indepdenent plugins and palces. 
+  from independent plugins and places.
 - add a @pytest.mark.parametrize helper which allows to easily
-  call a test function with different argument values
-- Add examples to the "parametrize" example page, including a quick port 
+  call a test function with different argument values.
+- Add examples to the "parametrize" example page, including a quick port
   of Test scenarios and the new parametrize function and decorator.
 - introduce registration for "pytest.mark.*" helpers via ini-files
-  or through plugin hooks.  Also introduce a "--strict" option which 
+  or through plugin hooks.  Also introduce a "--strict" option which
   will treat unregistered markers as errors
   allowing to avoid typos and maintain a well described set of markers
-  for your test suite.  See exaples at http://pytest.org/latest/mark.html
+  for your test suite.  See examples at http://pytest.org/latest/mark.html
   and its links.
 - issue50: introduce "-m marker" option to select tests based on markers
-  (this is a stricter and more predictable version of '-k' in that "-m"
+  (this is a stricter and more predictable version of "-k" in that "-m"
   only matches complete markers and has more obvious rules for and/or
   semantics.
-- new feature to help optimizing the speed of your tests: 
-  --durations=N option for displaying N slowest test calls 
+- new feature to help optimizing the speed of your tests:
+  --durations=N option for displaying N slowest test calls
   and setup/teardown methods.
 - fix issue87: --pastebin now works with python3
 - fix issue89: --pdb with unexpected exceptions in doctest work more sensibly
-- fix and cleanup pytest's own test suite to not leak FDs 
+- fix and cleanup pytest's own test suite to not leak FDs
 - fix issue83: link to generated funcarg list
 - fix issue74: pyarg module names are now checked against imp.find_module false positives
 - fix compatibility with twisted/trial-11.1.0 use cases
 
     # do checks related to excinfo.type, excinfo.value, excinfo.traceback
 
-If you want to write test code that works on Python2.4 as well,
+If you want to write test code that works on Python 2.4 as well,
 you may also use two other ways to test for an expected exception::
 
     pytest.raises(ExpectedException, func, *args, **kwargs)
 
 .. confval:: minversion
 
-   specifies a minimal pytest version required for running tests.
+   Specifies a minimal pytest version required for running tests.
 
         minversion = 2.1  # will fail if we run with pytest-2.0
 
 .. confval:: addopts
 
-   add the specified ``OPTS`` to the set of command line arguments as if they
+   Add the specified ``OPTS`` to the set of command line arguments as if they
    had been specified by the user. Example: if you have this ini file content::
 
        [pytest]
    and methods are considered as test modules.
 
    See :ref:`change naming conventions` for examples.
-

doc/example/index.txt

 
 .. note::
 
-   see :doc:`../getting-started` for basic introductionary examples
+   see :doc:`../getting-started` for basic introductory examples
 
 .. toctree::
    :maxdepth: 2

doc/example/markers.txt

 
 Here are some example using the :ref:`mark` mechanism.
 
-marking test functions and selecting them for a run
+Marking test functions and selecting them for a run
 ----------------------------------------------------
 
 You can "mark" a test function with custom metadata like this::
 
     # content of pytest.ini
     [pytest]
-    markers = 
-        webtest: mark a test as a webtest. 
+    markers =
+        webtest: mark a test as a webtest.
 
 You can ask which markers exist for your test suite - the list includes our just defined ``webtest`` markers::
 
     @pytest.mark.trylast: mark a hook implementation function such that the plugin machinery will try to call it last/as late as possible.
     
 
-For an example on how to add and work with markers from a plugin, see 
+For an example on how to add and work with markers from a plugin, see
 :ref:`adding a custom marker from a plugin`.
 
 .. note::
 Marking whole classes or modules
 ----------------------------------------------------
 
-If you are programming with Python2.6 you may use ``pytest.mark`` decorators
-with classes to apply markers to all of its test methods::
+If you are programming with Python 2.6 or later you may use ``pytest.mark``
+decorators with classes to apply markers to all of its test methods::
 
     # content of test_mark_classlevel.py
     import pytest
 This is equivalent to directly applying the decorator to the
 two test functions.
 
-To remain backward-compatible with Python2.4 you can also set a
+To remain backward-compatible with Python 2.4 you can also set a
 ``pytestmark`` attribute on a TestClass like this::
 
     import pytest
 Using ``-k TEXT`` to select tests
 ----------------------------------------------------
 
-You can use the ``-k`` command line option to only run tests with names that match the given argument::
+You can use the ``-k`` command line option to only run tests with names matching
+the given argument::
 
     $ py.test -k send_http  # running with the above defined examples
     ============================= test session starts ==============================
 
 .. _`adding a custom marker from a plugin`:
 
-custom marker and command line option to control test runs
+Custom marker and command line option to control test runs
 ----------------------------------------------------------
 
 .. regendoc:wipe
 
     def pytest_configure(config):
         # register an additional marker
-        config.addinivalue_line("markers", 
+        config.addinivalue_line("markers",
             "env(name): mark test to run only on named environment")
 
     def pytest_runtest_setup(item):

doc/example/mysetup.txt

         def myapp(self):
             return MyApp()
 
-To run the example we stub out a a simple ``MyApp`` application object::
+To run the example we stub out a simple ``MyApp`` application object::
 
     # content of myapp.py
     class MyApp:

doc/example/nonpython.txt

     representation string of your choice.  It
     will be reported as a (red) string.
 
-``reportinfo()`` is used for representing the test location and is also consulted for
-reporting in ``verbose`` mode::
+``reportinfo()`` is used for representing the test location and is also
+consulted when reporting in ``verbose`` mode::
 
     nonpython $ py.test -v
     =========================== test session starts ============================

doc/example/parametrize.txt

 
 .. _parametrizemark:
 
-simple "decorator" parametrization of a test function
+Simple "decorator" parametrization of a test function
 ----------------------------------------------------------------------------
 
 .. versionadded:: 2.2
 
-The builtin ``pytest.mark.parametrize`` decorator directly enables 
+The builtin ``pytest.mark.parametrize`` decorator directly enables
 parametrization of arguments for a test function.  Here is an example
 of a test function that wants to compare that processing some input
 results in expected output::
     def test_eval(input, expected):
         assert eval(input) == expected
 
-we parametrize two arguments of the test function so that the test 
+we parametrize two arguments of the test function so that the test
 function is called three times.  Let's run it::
 
     $ py.test -q 
 As expected when running the full range of ``param1`` values
 we'll get an error on the last one.
 
-a quick port of "testscenarios"
+A quick port of "testscenarios"
 ------------------------------------
 
 .. _`test scenarios`: http://bazaar.launchpad.net/~lifeless/testscenarios/trunk/annotate/head%3A/doc/example.py
 
-Here is a quick port of to run tests configured with `test scenarios`_,
+Here is a quick port to run tests configured with `test scenarios`_,
 an add-on from Robert Collins for the standard unittest framework. We
 only have to work a bit to construct the correct arguments for pytest's
 :py:func:`Metafunc.parametrize`::
 
 The parametrization of test functions happens at collection
 time.  It is a good idea to setup expensive resources like DB
-connections or subprocess only when the actual test is run.  
-Here is a simple example how you can achieve that, first 
+connections or subprocess only when the actual test is run.
+Here is a simple example how you can achieve that, first
 the actual test requiring a ``db`` object::
 
     # content of test_backends.py
-    
+
     import pytest
     def test_db_initialized(db):
         # a dummy test
         "one database object"
     class DB2:
         "alternative database object"
-    
+
     def pytest_funcarg__db(request):
         if request.param == "d1":
             return DB1()
 
 
 Here is an example ``pytest_generate_function`` function implementing a
-parametrization scheme similar to Michael Foords `unittest
+parametrization scheme similar to Michael Foord's `unittest
 parameterizer`_ but in a lot less code::
 
     # content of ./test_parametrize.py
         # called once per each test function
         funcarglist = metafunc.cls.params[metafunc.function.__name__]
         argnames = list(funcarglist[0])
-        metafunc.parametrize(argnames, [[funcargs[name] for name in argnames] 
+        metafunc.parametrize(argnames, [[funcargs[name] for name in argnames]
                 for funcargs in funcarglist])
 
     class TestClass:
 with different sets of arguments for its three arguments:
 
 * ``python1``: first python interpreter, run to pickle-dump an object to a file
-* ``python2``: second interpreter, run to pickle-load an object from a file 
+* ``python2``: second interpreter, run to pickle-load an object from a file
 * ``obj``: object to be dumped/loaded
 
 .. literalinclude:: multipython.py

doc/example/simple.txt

         # called from within a test run
     else:
         # called "normally"
-    
+
 accordingly in your application.  It's also a good idea
-to rather use your own application module rather than ``sys``
+to use your own application module rather than ``sys``
 for handling flag.
 
 Adding info to test report header
 you present more information appropriately::
 
     # content of conftest.py
-    
+
     def pytest_report_header(config):
         if config.option.verbose > 0:
             return ["info1: did you know that ...", "did you?"]
 .. versionadded: 2.2
 
 If you have a slow running large test suite you might want to find
-out which tests are slowest. Let's make an artifical test suite::
+out which tests are the slowest. Let's make an artifical test suite::
 
     # content of test_some_are_slow.py
-   
-    import time 
+
+    import time
 
     def test_funcfast():
         pass
-    
+
     def test_funcslow1():
         time.sleep(0.1)
-        
+
     def test_funcslow2():
         time.sleep(0.2)
-   
-Now we can profile which test functions execute slowest::
+
+Now we can profile which test functions execute the slowest::
 
     $ py.test --durations=3
     =========================== test session starts ============================
 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``
-since many people have gotten used to the old name and there
+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`` still uses many metaprogramming techniques and
 reading its source is thus likely not something for Python beginners.
 
-A second "magic" issue arguably the assert statement debugging feature. When
+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 caveat that the rewriting does not: If your
-expression has side effects (better to avoid them anyway!)  the intermediate
+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``.
 
 We like `Convention over Configuration`_ and didn't see much point
 in allowing a more flexible or abstract mechanism.  Moreover,
-is is nice to be able to search for ``pytest_funcarg__MYARG`` in
-a source code and safely find all factory functions for
+it is nice to be able to search for ``pytest_funcarg__MYARG`` in
+source code and safely find all factory functions for
 the ``MYARG`` function argument.
 
 .. _`Convention over Configuration`: http://en.wikipedia.org/wiki/Convention_over_Configuration
 also possible to run a test function multiple times with different objects.
 
 The basic mechanism for injecting objects is also called the
-*funcarg mechanism* because objects are ultimatly injected
+*funcarg mechanism* because objects are ultimately injected
 by calling a test function with it as an argument.  Unlike the
 classical xUnit approach *funcargs* relate more to `Dependency Injection`_
 because they help to de-couple test code from objects required for
 The funcarg **request** object
 =============================================
 
-Each funcarg factory receives a **request** object which is tied to a
-specific test function call.  A request object is passed to a funcarg
-factory and provides access to test configuration and context:
+Each funcarg factory receives a **request** object tied to a specific test
+function call.  A request object is passed to a funcarg factory and provides
+access to test configuration and context:
 
 .. autoclass:: _pytest.python.FuncargRequest()
     :members: function,cls,module,keywords,config

doc/goodpractises.txt

 Use tox and Continuous Integration servers
 -------------------------------------------------
 
-If you frequently relase 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 Jenkins_ pick it up
 .. _standalone:
 .. _`genscript method`:
 
-Create a py.test standalone Script
+Create a py.test standalone script
 -------------------------------------------
 
 If you are a maintainer or application developer and want others
 
     * find ``basedir`` -- this is the first "upward" (towards the root)
       directory not containing an ``__init__.py``.  If both the ``a``
-      and ``b`` directories contain an ``__init__.py`` the basedir will 
+      and ``b`` directories contain an ``__init__.py`` the basedir will
       be the parent dir of ``a``.
 
     * perform ``sys.path.insert(0, basedir)`` to make the test module
 by simply not specifying them.  If you mistype argument names or the
 hook name itself you get an error showing the available arguments.
 
-Initialisation, command line and configuration hooks
+Initialization, command line and configuration hooks
 --------------------------------------------------------------------
 
 .. currentmodule:: _pytest.hookspec
 
-Asserting deprecation and other warnings.
+Asserting deprecation and other warnings
 =====================================================
 
 The recwarn function argument
 
     def test_global():
         pytest.deprecated_call(myfunction, 17)
-

doc/test/plugin/cov.txt

 
 .. IMPORTANT::
 
-    Ensure that you manually delete the init_covmain.pth file in your site-packages directory.
+    Ensure that you manually delete the init_covmain.pth file in your
+    site-packages directory.
 
-    This file starts coverage collection of subprocesses if appropriate during site initialisation
-    at python startup.
+    This file starts coverage collection of subprocesses if appropriate during
+    site initialization at python startup.
 
 
 Usage
 
 For subprocess measurement environment variables must make it from the main process to the
 subprocess.  The python used by the subprocess must have pytest-cov installed.  The subprocess must
-do normal site initialisation so that the environment variables can be detected and coverage
+do normal site initialization so that the environment variables can be detected and coverage
 started.
 
 
 .. versionadded: 2.0.0
 
 In previous versions you could only enter PDB tracing if
-you disable capturing on the command line via ``py.test -s``.
+you disabled capturing on the command line via ``py.test -s``.
 
 .. _durations:
 
-Profiling test execution duration 
+Profiling test execution duration
 -------------------------------------
 
 .. versionadded: 2.2
 which will usually be called once for all the functions::
 
     def setup_module(module):
-        """ setup up any state specific to the execution
-            of the given module.
-        """
+        """ setup any state specific to the execution of the given module."""
 
     def teardown_module(module):
-        """ teardown any state that was previously setup
-            with a setup_module method.
+        """ teardown any state that was previously setup with a setup_module
+        method.
         """
 
 Class level setup/teardown
 
     @classmethod
     def setup_class(cls):
-        """ setup up any state specific to the execution
-            of the given class (which usually contains tests).
+        """ setup any state specific to the execution of the given class (which
+        usually contains tests).
         """
 
     @classmethod
     def teardown_class(cls):
-        """ teardown any state that was previously setup
-            with a call to setup_class.
+        """ teardown any state that was previously setup with a call to
+        setup_class.
         """
 
 Method and function level setup/teardown
 Similarly, the following methods are called around each method invocation::
 
     def setup_method(self, method):
-        """ setup up any state tied to the execution of the given
-        method in a class.  setup_method is invoked for every
-        test method of a class.
+        """ setup any state tied to the execution of the given method in a
+        class.  setup_method is invoked for every test method of a class.
         """
 
     def teardown_method(self, method):
-        """ teardown any state that was previously setup
-        with a setup_method call.
+        """ teardown any state that was previously setup with a setup_method
+        call.
         """
 
 If you would rather define test functions directly at module level
 you can also use the following functions to implement fixtures::
 
     def setup_function(function):
-        """ setup up any state tied to the execution of the given
-        function. Invoked for every test function in the module.
+        """ setup any state tied to the execution of the given function.
+        Invoked for every test function in the module.
         """
 
     def teardown_function(function):
-        """ teardown any state that was previously setup
-        with a setup_function call.
+        """ teardown any state that was previously setup with a setup_function
+        call.
         """
-    
-Note that it possible that setup/teardown pairs are invoked multiple
-times per testing process.
+
+Note that it is possible for setup/teardown pairs to be invoked multiple times
+per testing process.
 
 .. _`unittest.py module`: http://docs.python.org/library/unittest.html
-