* refine collect hooks and docs, remove pytest_collect_recurse

* write and extend extension docs

--HG--
branch : trunk

py/test/collect.py

@@ -384,7 +384,13 @@ class Directory(FSCollector):
                     l.append(res)
         return l
 
+    def _ignore(self, path):
+        ignore_paths = self.config.getconftest_pathlist("collect_ignore", path=path)
+        return ignore_paths and path in ignore_paths 
+
     def consider(self, path):
+        if self._ignore(path):
+            return
         if path.check(file=1):
             res = self.consider_file(path)
         elif path.check(dir=1):
@@ -392,10 +398,11 @@ class Directory(FSCollector):
         else:
             res = None            
         if isinstance(res, list):
-            # throw out identical modules
+            # throw out identical results
             l = []
             for x in res:
                 if x not in l:
+                    assert x.parent == self, "wrong collection tree construction"
                     l.append(x)
             res = l 
         return res
@@ -406,10 +413,8 @@ class Directory(FSCollector):
     def consider_dir(self, path, usefilters=None):
         if usefilters is not None:
             py.log._apiwarn("0.99", "usefilters argument not needed")
-        res = self.config.hook.pytest_collect_recurse(path=path, parent=self)
-        if res is None or res:
-            return self.config.hook.pytest_collect_directory(
-                path=path, parent=self)
+        return self.config.hook.pytest_collect_directory(
+            path=path, parent=self)
 
 class Item(Node): 
     """ a basic test item. """

py/test/plugin/hookspec.py

@@ -15,8 +15,7 @@ def pytest_configure(config):
     """
 
 def pytest_unconfigure(config):
-    """ called before test process is exited. 
-    """
+    """ called before test process is exited.  """
 
 # ------------------------------------------------------------------------------
 # test Session related hooks 
@@ -29,24 +28,17 @@ def pytest_sessionfinish(session, exitstatus, excrepr=None):
     """ whole test run finishes. """
 
 def pytest_deselected(items):
-    """ collected items that were deselected (by keyword). """
+    """ repeatedly called for test items deselected by keyword. """
 
 # ------------------------------------------------------------------------------
 # collection hooks
 # ------------------------------------------------------------------------------
 
+def pytest_collect_directory(path, parent):
+    """ return Collection node or None for the given path. """
 
 def pytest_collect_file(path, parent):
-    """ return Collection node or None. """
-
-def pytest_collect_recurse(path, parent):
-    """ return True/False to cause/prevent recursion into given directory. 
-        return None if you do not want to make the decision. 
-    """ 
-pytest_collect_recurse.firstresult = True
-
-def pytest_collect_directory(path, parent):
-    """ return Collection node or None. """
+    """ return Collection node or None for the given path. """
 
 def pytest_collectstart(collector):
     """ collector starts collecting. """
@@ -71,7 +63,7 @@ def pytest_pycollect_makeitem(collector, name, obj):
 pytest_pycollect_makeitem.firstresult = True
 
 def pytest_pyfunc_call(pyfuncitem):
-    """ perform function call with the given function arguments. """ 
+    """ perform function call to the with the given function arguments. """ 
 pytest_pyfunc_call.firstresult = True
 
 def pytest_generate_tests(metafunc):

py/test/plugin/pytest_default.py

@@ -19,24 +19,18 @@ def pytest_collect_file(path, parent):
         if ext == ".py":
             return parent.Module(path, parent=parent) 
 
-def pytest_collect_recurse(path, parent):
-    #excludelist = parent._config.getvalue_pathlist('dir_exclude', path)
-    #if excludelist and path in excludelist:
-    #    return 
-    if not parent.recfilter(path):
-        # check if cmdline specified this dir or a subdir directly
-        for arg in parent.config.args:
-            if path == arg or arg.relto(path):
-                break
-        else:
-            return False 
-    return True
-  
 def pytest_collect_directory(path, parent):
     # XXX reconsider the following comment 
     # not use parent.Directory here as we generally 
     # want dir/conftest.py to be able to 
     # define Directory(dir) already 
+    if not parent.recfilter(path): # by default special ".cvs", ... 
+        # check if cmdline specified this dir or a subdir directly
+        for arg in parent.config.args:
+            if path == arg or arg.relto(path):
+                break
+        else:
+            return 
     Directory = parent.config.getvalue('Directory', path) 
     return Directory(path, parent=parent)
 

py/test/testing/test_collect.py

@@ -205,17 +205,22 @@ class TestCustomConftests:
         assert item.name == "hello.xxx"
         assert item.__class__.__name__ == "CustomItem"
 
-    def test_avoid_directory_on_option(self, testdir):
+    def test_collectignore_exclude_on_option(self, testdir):
         testdir.makeconftest("""
+            collect_ignore = ['hello', 'test_world.py']
             def pytest_addoption(parser):
                 parser.addoption("--XX", action="store_true", default=False)
-            def pytest_collect_recurse(path, parent):
-                return parent.config.getvalue("XX")
+            def pytest_configure(config):
+                if config.getvalue("XX"):
+                    collect_ignore[:] = []
         """)
         testdir.mkdir("hello")
+        testdir.makepyfile(test_world="#")
         reprec = testdir.inline_run(testdir.tmpdir)
         names = [rep.collector.name for rep in reprec.getreports("pytest_collectreport")]
         assert 'hello' not in names 
+        assert 'test_world.py' not in names 
         reprec = testdir.inline_run(testdir.tmpdir, "--XX")
         names = [rep.collector.name for rep in reprec.getreports("pytest_collectreport")]
         assert 'hello' in names 
+        assert 'test_world.py' in names