some more finalization of docs

CHANGELOG

@@ -1,17 +1,15 @@
 Changes between 2.2.4 and 2.3.0.dev
 -----------------------------------
 
+- fix issue139 - introduce @pytest.fixture which allows direct scoping
+  and parametrization of funcarg factories.  Introduce new @pytest.setup
+  marker to allow the writing of setup functions which accept funcargs.
 - fix issue198 - conftest fixtures were not found on windows32 in some
   circumstances with nested directory structures due to path manipulation issues
 - fix issue193 skip test functions with were parametrized with empty
   parameter sets
 - fix python3.3 compat, mostly reporting bits that previously depended
   on dict ordering
-- introduce a generic "markers" object on Nodes and a request.node
-  attribute pointing to the scope-specific collection node of a request.
-  node.markers allows reading and manipulating of MarkInfo objects
-  previously attached with @pytest.mark.* or request.applymarker or
-  setattr(node.markers, name, pytest.mark.*) calls.
 - introduce re-ordering of tests by resource and parametrization setup
   which takes precedence to the usual file-ordering
 - fix issue185 monkeypatching time.time does not cause pytest to fail
@@ -22,9 +20,6 @@ Changes between 2.2.4 and 2.3.0.dev
   it is constructed correctly from the original current working dir.
 - fix "python setup.py test" example to cause a proper "errno" return
 - fix issue165 - fix broken doc links and mention stackoverflow for FAQ
-- fix issue139 - introduce @pytest.factory which allows direct scoping
-  and parametrization of funcarg factories.  Introduce new @pytest.setup
-  marker to allow the writing of setup functions which accept funcargs.
 - catch unicode-issues when writing failure representations
   to terminal to prevent the whole session from crashing
 - fix xfail/skip confusion: a skip-mark or an imperative pytest.skip
@@ -48,6 +43,10 @@ Changes between 2.2.4 and 2.3.0.dev
   especially with respect to the "magic" history, also mention
   pytest-django, trial and unittest integration.
 
+- make request.keywords and node.keywords writable.  All descendant
+  collection nodes will see keyword values.  Keywords are dictionaries
+  containing markers and other info.
+
 - fix issue 178: xml binary escapes are now wrapped in py.xml.raw
 
 - fix issue 176: correctly catch the builtin AssertionError

_pytest/__init__.py

@@ -1,2 +1,2 @@
 #
-__version__ = '2.3.0.dev30'
+__version__ = '2.3.0.dev31'

_pytest/python.py

@@ -10,6 +10,8 @@ from py._code.code import TerminalRepr
 import _pytest
 cutdir = py.path.local(_pytest.__file__).dirpath()
 
+callable = py.builtin.callable
+
 class FixtureFunctionMarker:
     def __init__(self, scope, params, autouse=False):
         self.scope = scope
@@ -45,7 +47,7 @@ def fixture(scope="function", params=None, autouse=False):
                 can see it.  If False (the default) then an explicit
                 reference is needed to activate the fixture.
     """
-    if py.builtin.callable(scope) and params is None and autouse == False:
+    if callable(scope) and params is None and autouse == False:
         # direct decoration
         return FixtureFunctionMarker("function", params, autouse)(scope)
     else:
@@ -474,7 +476,7 @@ class Generator(FunctionMixin, PyCollector):
         seen = {}
         for i, x in enumerate(self.obj()):
             name, call, args = self.getcallargs(x)
-            if not py.builtin.callable(call):
+            if not callable(call):
                 raise TypeError("%r yielded non callable test %r" %(self.obj, call,))
             if name is None:
                 name = "[%d]" % i

doc/en/conf.py

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

doc/en/contents.txt

@@ -12,9 +12,9 @@ Full pytest documentation
    :maxdepth: 2
 
    overview
-   example/index
    apiref
    plugins
+   example/index
    talks
    develop
    funcarg_compare.txt

doc/en/unittest.txt

@@ -10,9 +10,9 @@ py.test has support for running Python `unittest.py style`_ tests.
 It's meant for leveraging existing unittest-style projects
 to use pytest features.  Concretely, pytest will automatically 
 collect ``unittest.TestCase`` subclasses and their ``test`` methods in
-test files.  It will invoke typlical ``setUp/tearDown`` methods and 
+test files.  It will invoke typical setup/teardown methods and 
 generally try to make test suites written to run on unittest, to also 
-run using pytest.  We assume here that you are familiar with writing
+run using ``py.test``.  We assume here that you are familiar with writing
 ``unittest.TestCase`` style tests and rather focus on 
 integration aspects.
 
@@ -24,8 +24,8 @@ After :ref:`installation` type::
     py.test 
 
 and you should be able to run your unittest-style tests if they
-are contained in ``test_*`` modules.  This way you can make
-use of most :ref:`pytest features <features>`, for example
+are contained in ``test_*`` modules.  If that works for you then
+you can make use of most :ref:`pytest features <features>`, for example
 ``--pdb`` debugging in failures, using :ref:`plain assert-statements <assert>`,
 :ref:`more informative tracebacks <tbreportdemo>`, stdout-capturing or 
 distributing tests to multiple CPUs via the ``-nNUM`` option if you 
@@ -35,17 +35,17 @@ the general pytest documentation for many more examples.
 Mixing pytest fixtures into unittest.TestCase style tests
 -----------------------------------------------------------
 
-pytest supports using its :ref:`fixture mechanism <fixture>` with
-``unittest.TestCase`` style tests.  Assuming you have at least skimmed
-the pytest fixture features, let's jump-start into an example that 
-integrates a pytest ``db_class`` fixture, setting up a 
-class-cached database object, and then reference it from 
-a unittest-style test::
+Running your unittest with ``py.test`` allows you to use its
+:ref:`fixture mechanism <fixture>` with ``unittest.TestCase`` style
+tests.  Assuming you have at least skimmed the pytest fixture features,
+let's jump-start into an example that integrates a pytest ``db_class``
+fixture, setting up a class-cached database object, and then reference
+it from a unittest-style test::
 
     # content of conftest.py
 
-    # hooks and fixtures in this file are available throughout all test 
-    # modules living below the directory of this conftest.py file
+    # we define a fixture function below and it will be "used" by
+    # referencing its name from tests
 
     import pytest
 
@@ -53,6 +53,7 @@ a unittest-style test::
     def db_class(request):
         class DummyDB:
             pass
+        # set a class attribute on the invoking test context 
         request.cls.db = DummyDB()
 
 This defines a fixture function ``db_class`` which - if used - is 
@@ -81,7 +82,7 @@ fixture definition::
             assert 0, self.db   # fail for demo purposes
 
 The ``@pytest.mark.usefixtures("db_class")`` class-decorator makes sure that 
-the pytest fixture function ``db_class`` is called for each test method.
+the pytest fixture function ``db_class`` is called once per class.
 Due to the deliberately failing assert statements, we can take a look at
 the ``self.db`` values in the traceback::
 
@@ -114,7 +115,7 @@ the ``self.db`` values in the traceback::
     test_unittest_db.py:12: AssertionError
     ========================= 2 failed in 0.02 seconds =========================
 
-This default pytest traceback shows that, indeed, the two test methods
+This default pytest traceback shows that the two test methods
 share the same ``self.db`` instance which was our intention
 when writing the class-scoped fixture function above.
 
@@ -124,13 +125,17 @@ autouse fixtures and accessing other fixtures
 
 Although it's usually better to explicitely declare use of fixtures you need
 for a given test, you may sometimes want to have fixtures that are 
-automatically used in a given context.  For this, you can flag
-fixture functions with ``@pytest.fixture(autouse=True)`` and define
-the fixture function in the context where you want it used.  Let's look 
-at an ``initdir`` fixrure which makes all test methods of a ``TestCase`` class 
-execute in a temporary directory with a pre-initialized ``samplefile.ini``.
-Our ``initdir`` fixture itself uses the pytest builtin :ref:`tmpdir <tmpdir>`
-fixture to help with creating a temporary dir::
+automatically used in a given context.  After all, the traditional 
+style of unittest-setup mandates the use of this implicit fixture writing
+and chances are, you are used to it or like it.  
+
+You can flag fixture functions with ``@pytest.fixture(autouse=True)``
+and define the fixture function in the context where you want it used.
+Let's look at an ``initdir`` fixture which makes all test methods of a
+``TestCase`` class execute in a temporary directory with a
+pre-initialized ``samplefile.ini``.  Our ``initdir`` fixture itself uses
+the pytest builtin :ref:`tmpdir <tmpdir>` fixture to delegate the
+creation of a per-test temporary directory::
 
     # content of test_unittest_cleandir.py
     import pytest
@@ -148,8 +153,8 @@ fixture to help with creating a temporary dir::
 
 Due to the ``autouse`` flag the ``initdir`` fixture function will be
 used for all methods of the class where it is defined.  This is a
-shortcut for using a ``@pytest.mark.usefixtures("initdir")`` on the
-class like in the previous example.
+shortcut for using a ``@pytest.mark.usefixtures("initdir")`` marker
+on the class like in the previous example.
 
 Running this test module ...::
 
@@ -161,11 +166,13 @@ was executed ahead of the ``test_method``.
 
 .. note::
 
-   ``unittest.TestCase`` methods cannot directly receive fixture 
+   While pytest supports receiving fixtures via :ref:`test function arguments <funcargs>` for non-unittest test methods, ``unittest.TestCase`` methods cannot directly receive fixture 
    function arguments as implementing that is likely to inflict
    on the ability to run general unittest.TestCase test suites.
-   Given enough demand, attempts might be made, though.  If
-   unittest finally grows a reasonable plugin system that should 
-   help as well.  In the meanwhile, the above ``usefixtures`` and 
-   ``autouse`` examples should help to mix in pytest fixtures into
-   unittest suites.
+   Maybe optional support would be possible, though.  If unittest finally 
+   grows a plugin system that should help as well.  In the meanwhile, the 
+   above ``usefixtures`` and ``autouse`` examples should help to mix in 
+   pytest fixtures into unittest suites.  And of course you can also start
+   to selectively leave away the ``unittest.TestCase`` subclassing, use
+   plain asserts and get the unlimited pytest feature set.
+

setup.py

@@ -24,7 +24,7 @@ def main():
         name='pytest',
         description='py.test: simple powerful testing with Python',
         long_description = long_description,
-        version='2.3.0.dev30',
+        version='2.3.0.dev31',
         url='http://pytest.org',
         license='MIT license',
         platforms=['unix', 'linux', 'osx', 'cygwin', 'win32'],

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 distshare={homedir}/.tox/distshare
-envlist=py26,py27,py31,py32,py33,py27-xdist,py25,py24
+envlist=py26,py27,py31,py32,py33,py27-xdist,py25,trial
 indexserver=
     pypi = http://pypi.python.org/simple
     testrun = http://pypi.testrun.org