remove superflous collect_by_name, and improve some docs

--HG--
branch : trunk

doc/customize.txt

@@ -334,13 +334,23 @@ Reference of important objects involved in hooks
 .. autoclass:: pytest.plugin.config.Parser
     :members:
 
-.. autoclass:: pytest.plugin.session.File
+.. autoclass:: pytest.plugin.session.Node(name, parent)
-    :inherited-members:
+    :members:
 
-.. autoclass:: pytest.plugin.session.Item
+.. 
-    :inherited-members:
+    .. autoclass:: pytest.plugin.session.File(fspath, parent)
+        :members:
 
-.. autoclass:: pytest.plugin.python.Function
+    .. autoclass:: pytest.plugin.session.Item(name, parent)
+        :members:
+
+    .. autoclass:: pytest.plugin.python.Module(name, parent)
+        :members:
+
+    .. autoclass:: pytest.plugin.python.Class(name, parent)
+        :members:
+
+    .. autoclass:: pytest.plugin.python.Function(name, parent)
         :members:
 
 .. autoclass:: pytest.plugin.runner.CallInfo

pytest/plugin/config.py

@@ -244,7 +244,6 @@ class CmdOptions(object):
 
 class Config(object):
     """ access to configuration values, pluginmanager and plugin hooks.  """
-    Option = py.std.optparse.Option
     basetemp = None
 
     def __init__(self, pluginmanager=None):
@@ -353,7 +352,9 @@ class Config(object):
                 keep=0, rootdir=basetemp, lock_timeout=None)
 
     def getini(self, name):
-        """ return configuration value from an ini file. """
+        """ return configuration value from an ini file. If the
+        specified name hasn't been registered through a prior ``parse.addini``
+        call (usually from a plugin), a ValueError is raised. """
         try:
             description, type = self._parser._inidict[name]
         except KeyError:
@@ -391,7 +392,8 @@ class Config(object):
         return self._conftest.rget(name, path)
 
     def getvalue(self, name, path=None):
-        """ return 'name' value looked up from command line 'options'.
+        """ return ``name`` value looked set from command line options.
+
         (deprecated) if we can't find the option also lookup
         the name in a matching conftest file.
         """

pytest/plugin/pytester.py

@@ -385,6 +385,11 @@ class TmpTestdir:
         #config.pluginmanager.do_unconfigure(config)
         return node
 
+    def collect_by_name(self, modcol, name):
+        for colitem in modcol._memocollect():
+            if colitem.name == name:
+                return colitem
+
     def popen(self, cmdargs, stdout, stderr, **kw):
         if not hasattr(py.std, 'subprocess'):
             py.test.skip("no subprocess module")

pytest/plugin/session.py

@@ -446,13 +446,8 @@ class Collector(Node):
         """
         raise NotImplementedError("abstract")
 
-    def collect_by_name(self, name):
-        for colitem in self._memocollect():
-            if colitem.name == name:
-                return colitem
-
     def repr_failure(self, excinfo):
-        """ represent a failure. """
+        """ represent a collection failure. """
         if excinfo.errisinstance(self.CollectError):
             exc = excinfo.value
             return str(exc.args[0])
@@ -525,8 +520,7 @@ class Directory(FSCollector):
 
 class Item(Node):
     """ a basic test invocation item. Note that for a single function
-    there might be multiple test invocation items. Attributes:
+    there might be multiple test invocation items.
-    
     """
     def reportinfo(self):
         return self.fspath, None, ""

testing/plugin/test_python.py

@@ -268,9 +268,9 @@ class TestSorting:
             def test_pass(): pass
             def test_fail(): assert 0
         """)
-        fn1 = modcol.collect_by_name("test_pass")
+        fn1 = testdir.collect_by_name(modcol, "test_pass")
         assert isinstance(fn1, py.test.collect.Function)
-        fn2 = modcol.collect_by_name("test_pass")
+        fn2 = testdir.collect_by_name(modcol, "test_pass")
         assert isinstance(fn2, py.test.collect.Function)
 
         assert fn1 == fn2
@@ -279,7 +279,7 @@ class TestSorting:
             assert cmp(fn1, fn2) == 0
         assert hash(fn1) == hash(fn2)
 
-        fn3 = modcol.collect_by_name("test_fail")
+        fn3 = testdir.collect_by_name(modcol, "test_fail")
         assert isinstance(fn3, py.test.collect.Function)
         assert not (fn1 == fn3)
         assert fn1 != fn3
@@ -1092,7 +1092,7 @@ class TestReportInfo:
             class TestClass:
                 def test_hello(self): pass
         """)
-        classcol = modcol.collect_by_name("TestClass")
+        classcol = testdir.collect_by_name(modcol, "TestClass")
         fspath, lineno, msg = classcol.reportinfo()
         assert fspath == modcol.fspath
         assert lineno == 1
@@ -1106,7 +1106,7 @@ class TestReportInfo:
                     assert x
                 yield check, 3
         """)
-        gencol = modcol.collect_by_name("test_gen")
+        gencol = testdir.collect_by_name(modcol, "test_gen")
         fspath, lineno, modpath = gencol.reportinfo()
         assert fspath == modcol.fspath
         assert lineno == 1

testing/test_collect.py

@@ -28,9 +28,9 @@ class TestCollector:
             def test_pass(): pass
             def test_fail(): assert 0
         """)
-        fn1 = modcol.collect_by_name("test_pass")
+        fn1 = testdir.collect_by_name(modcol, "test_pass")
         assert isinstance(fn1, py.test.collect.Function)
-        fn2 = modcol.collect_by_name("test_pass")
+        fn2 = testdir.collect_by_name(modcol, "test_pass")
         assert isinstance(fn2, py.test.collect.Function)
 
         assert fn1 == fn2
@@ -39,7 +39,7 @@ class TestCollector:
             assert cmp(fn1, fn2) == 0
         assert hash(fn1) == hash(fn2)
 
-        fn3 = modcol.collect_by_name("test_fail")
+        fn3 = testdir.collect_by_name(modcol, "test_fail")
         assert isinstance(fn3, py.test.collect.Function)
         assert not (fn1 == fn3)
         assert fn1 != fn3
@@ -57,8 +57,9 @@ class TestCollector:
                  def test_foo():
                      pass
         """)
-        cls = modcol.collect_by_name("TestClass")
+        cls = testdir.collect_by_name(modcol, "TestClass")
-        fn = cls.collect_by_name("()").collect_by_name("test_foo")
+        fn = testdir.collect_by_name(
+            testdir.collect_by_name(cls, "()"), "test_foo")
 
         parent = fn.getparent(py.test.collect.Module)
         assert parent is modcol