finalized docs and funcarg attributes, i think

--HG--
branch : trunk

doc/test/config.txt

@@ -21,3 +21,26 @@ behind the ``--`` double-dash.
 IOW, you can set default values for options per project, per
 home-directoray, per shell session or per test-run. 
 
+
+.. _`basetemp`: 
+
+per-testrun temporary directories 
+-------------------------------------------
+
+``py.test`` runs provide means to create per-test session
+temporary (sub) directories.  You can create such directories 
+like this:
+
+.. sourcecode: python
+
+    import py
+    basetemp = py.test.config.ensuretemp() 
+    basetemp_subdir = py.test.config.ensuretemp("subdir") 
+
+By default, ``py.test`` creates a ``pytest-NUMBER`` directory
+and will keep around the directories of the last three 
+test runs.  You can also set the base temporary directory 
+with the `--basetemp`` option.  When distributing 
+tests on the same machine, ``py.test`` takes care to 
+pass around the basetemp directory such that all temporary
+files land below the same basetemp directory.  

doc/test/funcargs.txt

@@ -57,14 +57,21 @@ Request objects encapsulate a request for a function argument from a
 specific test function.  Request objects provide access to command line
 options, the underlying python function and allow interaction 
 with other providers and the test running process.  
-Basic attributes of request objects:
+
+Attributes of request objects
+++++++++++++++++++++++++++++++++++++++++
 
 ``request.argname``: name of the requested function argument 
 
 ``request.function``: python function object requesting the argument
 
+``request.fspath``: filesystem path of containing module
+
 ``request.config``: access to command line opts and general config
 
+finalizing after test function executed 
+++++++++++++++++++++++++++++++++++++++++
+
 Request objects allow to **register a finalizer method** which is 
 called after a test function has finished running. 
 This is useful for tearing down or cleaning up
@@ -79,6 +86,35 @@ function finish:
         request.addfinalizer(lambda: myfile.close())
         return myfile
 
+a unique temporary directory 
+++++++++++++++++++++++++++++++++++++++++
+
+request objects allow to create unique temporary 
+directories.  These directories will be created
+as subdirectories under the `per-testsession
+temporary directory`_.  Each request object 
+receives its own unique subdirectory whose
+basenames starts with the name of the function
+that triggered the funcarg request.  You
+can further work with the provided `py.path.local`_ 
+object to e.g. create subdirs or config files::
+
+    def pytest_funcarg__mysetup(self, request):
+        tmpdir = request.maketempdir()
+        tmpdir.mkdir("mysubdir")
+        tmpdir.join("config.ini").write("[default")
+        return tmpdir 
+
+Note that you do not need to perform finalization, 
+i.e. remove the temporary directory as this is
+part of the global management of the base temporary
+directory. 
+
+.. _`per-testsession temporary directory`: config.html#basetemp
+
+decorating/adding to existing funcargs 
+++++++++++++++++++++++++++++++++++++++++
+
 If you want to **decorate a function argument** that is 
 provided elsewhere you can ask the request object 
 to provide the "next" value:
@@ -94,6 +130,7 @@ This will raise a ``request.Error`` exception if there
 is no next provider left.  See the `decorator example`_ 
 for a use of this method. 
 
+
 .. _`lookup order`: 
 
 Order of funcarg provider lookup

py/test/dist/testing/test_nodemanage.py

@@ -3,7 +3,7 @@ from py.__.test.dist.nodemanage import NodeManager
 
 class pytest_funcarg__mysetup:
     def __init__(self, request):
-        basetemp = request.config.ensuretemp(request.getfspath().purebasename)
+        basetemp = request.maketempdir()
         basetemp = basetemp.mkdir(request.function.__name__) 
         self.source = basetemp.mkdir("source")
         self.dest = basetemp.mkdir("dest")

py/test/pycollect.py

@@ -403,6 +403,7 @@ class FuncargRequest:
         self.argname = argname 
         self.function = pyfuncitem.obj
         self.config = pyfuncitem.config
+        self.fspath = pyfuncitem.fspath
         self._plugins = self._getplugins()
         self._methods = self.config.pluginmanager.listattr(
             plugins=self._plugins, 
@@ -431,8 +432,12 @@ class FuncargRequest:
     def addfinalizer(self, finalizer):
         self._pyfuncitem.addfinalizer(finalizer)
 
-    def getfspath(self):
-        return self._pyfuncitem.fspath
+    def maketempdir(self):
+        basetemp = self.config.getbasetemp()
+        tmp = py.path.local.make_numbered_dir(
+            prefix=self.function.__name__ + "_", 
+            keep=0, rootdir=basetemp)
+        return tmp
 
     def _raiselookupfailed(self):
         available = []
@@ -447,4 +452,5 @@ class FuncargRequest:
         msg += "\n available funcargs: %s" %(", ".join(available),)
         raise LookupError(msg)
 
+
         

py/test/testing/test_funcargs.py

@@ -72,9 +72,9 @@ class TestRequest:
         req = item.getrequest("other")
         assert req.argname == "other"
         assert req.function == item.obj 
-        assert req.funcname == "test_func" 
+        assert req.function.__name__ == "test_func" 
         assert req.config == item.config 
-        assert repr(req).find(req.funcname) != -1
+        assert repr(req).find(req.function.__name__) != -1
         
     def test_request_contains_funcargs_methods(self, testdir):
         modcol = testdir.getmodulecol("""
@@ -114,8 +114,17 @@ class TestRequest:
         req.addfinalizer(l.pop)
         item.teardown()
 
+    def test_request_maketemp(self, testdir):
+        item = testdir.getitem("def test_func(): pass")
+        req = item.getrequest("xxx")
+        tmpdir = req.maketempdir()
+        tmpdir2 = req.maketempdir()
+        assert tmpdir != tmpdir2
+        assert tmpdir.basename.startswith("test_func")
+        assert tmpdir2.basename.startswith("test_func")
+
     def test_request_getmodulepath(self, testdir):
         modcol = testdir.getmodulecol("def test_somefunc(): pass")
         item, = testdir.genitems([modcol])
         req = item.getrequest("hello")
-        assert req.getfspath() == modcol.fspath 
+        assert req.fspath == modcol.fspath