* streamlining plugin docstrings

* better organisation of example directory, also does not break
  whole-test run anymore

--HG--
branch : 1.0.x

CHANGELOG

@@ -1,9 +1,15 @@
 Changes between 1.0.0b7 and 1.0.0b8
 =====================================
 
-* docs: refined funcargs doc, use the term 
+* if plugins use "py.test.importorskip" for importing 
-  "factory" instead of "provider",  added a new 
+  a dependency only a warning will be issued instead 
-  talk/tutorial doc page 
+  of exiting the testing process. 
+
+* docs: 
+  - refined funcargs doc , use the term "factory" instead 
+    of "provider"
+  - added a new talk/tutorial doc page 
+  - better plugin docstrings
 
 * fixed teardown problem related to partially failing funcarg setups 
   (thanks MrTopf for reporting), "pytest_runtest_teardown" is now 

MANIFEST

@@ -33,7 +33,11 @@ doc/test/talks.txt
 doc/test/test.txt
 doc/test/xunit_setup.txt
 doc/xml.txt
+example/assertion/failure_demo.py
+example/assertion/test_failures.py
+example/assertion/test_setup_flow_example.py
 example/execnet/popen_read_multiple.py
+example/funcarg/conftest.py
 example/funcarg/costlysetup/conftest.py
 example/funcarg/costlysetup/sub1/test_quick.py
 example/funcarg/costlysetup/sub2/test_two.py
@@ -53,9 +57,6 @@ example/funcarg/test_simpleprovider.py
 example/genhtml.py
 example/genhtmlcss.py
 example/genxml.py
-example/pytest/failure_demo.py
-example/pytest/test_failures.py
-example/pytest/test_setup_flow_example.py
 py/LICENSE
 py/__init__.py
 py/_com.py

example/assertion/test_failures.py

@@ -9,6 +9,6 @@ def test_failure_demo_fails_properly(testdir):
     passed, skipped, failed = reprec.countoutcomes() 
     assert passed == 0 
     assert failed == 20, failed
-    colreports = reprec.getnamed("collectionreport")
+    colreports = reprec.getreports("pytest_collectreport")
     failed = len([x.failed for x in colreports])
     assert failed == 5

example/funcarg/conftest.py

@@ -0,0 +1,3 @@
+import py
+
+collect_ignore = 'mysetup', 'mysetup2', 'test_simpleprovider.py', 'parametrize'

py/test/plugin/pytest_default.py

@@ -1,4 +1,4 @@
-""" Plugin implementing defaults and general options. """ 
+""" default hooks and general py.test options. """ 
 
 import py
 
@@ -115,7 +115,7 @@ def pytest_addoption(parser):
 def pytest_configure(config):
     fixoptions(config)
     setsession(config)
-    loadplugins(config)
+    #xxxloadplugins(config)
 
 def fixoptions(config):
     if config.option.numprocesses:
@@ -124,7 +124,7 @@ def fixoptions(config):
     if config.option.distload:
         config.option.dist = "load"
 
-def loadplugins(config):
+def xxxloadplugins(config):
     for name in config.getvalue("plugin"):
         print "importing", name
         config.pluginmanager.import_plugin(name)

py/test/plugin/pytest_doctest.py

@@ -1,5 +1,5 @@
 """
-automatically collect and execute doctests. 
+collect and execute doctests from modules and test files. 
 """
 
 import py

py/test/plugin/pytest_execnetcleanup.py

@@ -1,5 +1,5 @@
 """
-cleanup gateways that were instantiated during a test function run. 
+cleanup execnet gateways during test function runs.
 """
 import py
 

py/test/plugin/pytest_figleaf.py

@@ -3,8 +3,7 @@ write and report coverage data using the 'figleaf' module.
 """
 import py
 
-figleaf = py.test.importorskip("figleaf")
+figleaf = py.test.importorskip("figleaf.annote_html")
-import figleaf.annotate_html
 
 def pytest_addoption(parser):
     group = parser.addgroup('figleaf options')

py/test/plugin/pytest_hooklog.py

@@ -1,4 +1,4 @@
-""" log calling of plugin hooks to a file. """ 
+""" log invocations of extension hooks to a file. """ 
 import py
 
 def pytest_addoption(parser):

py/test/plugin/pytest_iocapture.py

@@ -1,6 +1,5 @@
 """
-'capsys' and 'capfd' funcargs for capturing stdout/stderror either
+'capsys' and 'capfd' funcargs for capturing stdout/stderror.
-by intercepting sys.stdout/stderr or File Descriptors 1/2. 
 
 Calling the reset() method of the capture funcargs gives 
 a out/err tuple of strings representing the captured streams. 

py/test/plugin/pytest_keyword.py

@@ -1,6 +1,5 @@
 """
     py.test.mark / keyword plugin 
-
 """
 import py
 

py/test/plugin/pytest_monkeypatch.py

@@ -1,13 +1,13 @@
 """
-    "monkeypatch" funcarg for safely patching objects, 
+safely patch object attributes, dicts and environment variables. 
-    dictionaries and environment variables during the execution of 
-    a test.  "monkeypatch" has three helper functions: 
 
-        monkeypatch.setattr(obj, name, value) 
+the "monkeypatch" funcarg has three helper functions: 
-        monkeypatch.setitem(obj, name, value) 
-        monkeypatch.setenv(name, value) 
 
-    After the test has run modifications will be undone. 
+    monkeypatch.setattr(obj, name, value) 
+    monkeypatch.setitem(obj, name, value) 
+    monkeypatch.setenv(name, value) 
+
+After the test has run modifications will be undone. 
 """
 import os
 

py/test/plugin/pytest_pdb.py

@@ -1,6 +1,5 @@
 """
-interactive debugging with a PDB prompt. 
+interactive debugging with the Python Debugger.
-
 """
 import py
 import pdb, sys, linecache

py/test/plugin/pytest_pocoo.py

@@ -1,5 +1,5 @@
 """
-py.test plugin for sending testing failure information to paste.pocoo.org 
+submit failure information to paste.pocoo.org 
 """
 import py
 

py/test/plugin/pytest_pytester.py

@@ -1,5 +1,5 @@
 """
-funcargs and support code for testing py.test functionality. 
+funcargs and support code for testing py.test's own functionality. 
 """
 
 import py

py/test/plugin/pytest_recwarn.py

@@ -1,5 +1,5 @@
 """
-help performing checks for deprecation and other warnings. Provides: 
+helpers for asserting deprecation and other warnings. 
 
     recwarn: function argument where one can call recwarn.pop() to get
              the last warning that would have been shown. 

py/test/plugin/pytest_restdoc.py

@@ -1,6 +1,5 @@
 """
-perform ReST specific tests on .txt files, including
+perform ReST syntax, local and remote reference tests on .rst/.txt files. 
-linkchecks and remote URL checks. 
 """
 import py
 
@@ -17,7 +16,7 @@ def pytest_addoption(parser):
            help="force generation of html files.")
 
 def pytest_collect_file(path, parent):
-    if path.ext == ".txt":
+    if path.ext in (".txt", ".rst"):
         project = getproject(path)
         if project is not None:
             return ReSTFile(path, parent=parent, project=project)

py/test/plugin/pytest_runner.py

@@ -1,5 +1,5 @@
 """ 
-collect and run test items and creating reports. 
+collect and run test items and create reports. 
 """
 
 import py

py/test/plugin/pytest_terminal.py

@@ -1,3 +1,6 @@
+"""
+terminal reporting of the full testing process.
+"""
 import py
 import sys
 

py/test/pluginmanager.py

@@ -3,6 +3,7 @@ managing loading and interacting with pytest plugins.
 """
 import py
 from py.__.test.plugin import hookspec
+from py.__.test.outcome import Skipped
 
 def check_old_use(mod, modname):
     clsname = modname[len('pytest_'):].capitalize() + "Plugin" 
@@ -96,10 +97,20 @@ class PluginManager(object):
         modname = canonical_importname(spec)
         if modname in self.impname2plugin:
             return
-        mod = importplugin(modname)
+        try:
-        check_old_use(mod, modname) 
+            mod = importplugin(modname)
-        self.register(mod)
+        except KeyboardInterrupt:
-        self.consider_module(mod)
+            raise
+        except Skipped, e:
+            self._warn("could not import plugin %r, reason: %r" %(
+                (modname, e.msg)))
+        else:
+            check_old_use(mod, modname) 
+            self.register(mod)
+            self.consider_module(mod)
+
+    def _warn(self, msg):
+        print "===WARNING=== %s" % (msg,)
 
     def _checkplugin(self, plugin):
         # =====================================================
@@ -243,3 +254,36 @@ def formatdef(func):
         py.std.inspect.formatargspec(*py.std.inspect.getargspec(func))
     )
 
+if __name__ == "__main__":
+    import py.__.test.plugin
+    basedir = py.path.local(py.__.test.plugin.__file__).dirpath()
+    name2text = {}
+    for p in basedir.listdir("pytest_*"):
+        if p.ext == ".py" or (
+           p.check(dir=1) and p.join("__init__.py").check()):
+            impname = p.purebasename 
+            if impname.find("__") != -1:
+                continue
+            try:
+                plugin = importplugin(impname)
+            except (ImportError, py.__.test.outcome.Skipped):
+                name2text[impname] = "IMPORT ERROR"
+            else:
+                doc = plugin.__doc__ or ""
+                doc = doc.strip()
+                name2text[impname] = doc
+           
+    for name in sorted(name2text.keys()):
+        text = name2text[name]
+        if name[0] == "_":
+            continue
+        print "%-20s %s" % (name, text.split("\n")[0])
+
+        #text = py.std.textwrap.wrap(name2text[name], 
+        #    width = 80,
+        #    initial_indent="%s: " % name, 
+        #    replace_whitespace = False)
+        #for line in text:
+        #    print line
+     
+

py/test/testing/test_pluginmanager.py

@@ -7,12 +7,27 @@ class TestBootstrapping:
         monkeypatch.setitem(os.environ, 'PYTEST_PLUGINS', 'nonexistingmodule')
         py.test.raises(ImportError, "pluginmanager.consider_env()")
 
-    def test_preparse_args(self, monkeypatch):
+    def test_preparse_args(self):
         pluginmanager = PluginManager()
         py.test.raises(ImportError, """
             pluginmanager.consider_preparse(["xyz", "-p", "hello123"])
         """)
 
+    def test_plugin_skip(self, testdir, monkeypatch):
+        testdir.makepyfile(pytest_skipping1="""
+            import py
+            py.test.skip("hello")
+        """)
+        result = testdir.runpytest("-p", "skipping1")
+        result.stdout.fnmatch_lines([
+            "*WARNING*could not import plugin*skipping1*hello*"
+        ])
+        monkeypatch.setenv("PYTEST_PLUGINS", "skipping1")
+        result = testdir.runpytest()
+        result.stdout.fnmatch_lines([
+            "*WARNING*could not import plugin*skipping1*hello*"
+        ])
+
     def test_consider_env_plugin_instantiation(self, testdir, monkeypatch):
         pluginmanager = PluginManager()
         testdir.syspathinsert()