[svn r37290] * allow only CAPITAL letters for short options

* documentation and test for it
* streamlined documentation a bit

--HG--
branch : trunk

py/doc/test.txt

@@ -485,6 +485,28 @@ writing conftest.py files
 
 XXX
 
+adding custom options
++++++++++++++++++++++++
+
+To register a project-specific command line option 
+you may have the following code within a ``conftest.py`` file::
+
+    import py
+    Option = py.test.config.Option
+    option = py.test.config.addoptions("pypy options",
+        Option('-V', '--view', action="store_true", dest="view", default=False,
+               help="view translation tests' flow graphs with Pygame"),
+    )
+
+and you can then access ``option.view`` like this:: 
+
+    if option.view:
+        print "view this!"
+
+The option will be available if you type ``py.test -h``
+Note that you may only register upper case short
+options.  ``py.test`` reserves all lower 
+case short options for its own cross-project usage. 
 
 customizing the collecting and running process 
 -----------------------------------------------
@@ -671,7 +693,7 @@ The options that you need to specify in that conftest.py file are:
 
 * **`dist_hosts`**: a required list of ssh addresses (which each may
   include a path, default path is: ``$HOME/pytestcache-HOSTNAME``)
-* `dist_rsync_roots` - a list of packages to copy to the remote machines.
+* `dist_rsyncroots` - a list of packages to copy to the remote machines.
 * `dist_remotepython` - the remote python executable to run.
 * `dist_nicelevel` - process priority of remote nodes. 
 * `dist_boxing` - will run each single test in a separate process 
@@ -681,7 +703,7 @@ The options that you need to specify in that conftest.py file are:
 Sample configuration::
 
     dist_hosts = ['localhost', 'user@someserver:/tmp/somedir']
-    dist_rsync_roots = ['pypy', 'py']
+    dist_rsyncroots = ['pypy', 'py']
     dist_remotepython = 'python2.4'
     dist_nicelevel = 10 
     dist_boxing = True

py/test/config.py

@@ -2,6 +2,7 @@ from __future__ import generators
 
 import py
 from conftesthandle import Conftest
+from py.__.test.defaultconftest import adddefaultoptions
 
 optparse = py.compat.optparse
 
@@ -42,8 +43,8 @@ class Config(object):
         assert not self._initialized, (
                 "can only parse cmdline args once per Config object")
         self._initialized = True
+        adddefaultoptions(self)
         self.conftest.setinitial(args) 
-        self.conftest.rget('adddefaultoptions')()
         args = [str(x) for x in args]
         cmdlineoption, args = self._parser.parse_args(args) 
         self.option.__dict__.update(vars(cmdlineoption))
@@ -89,6 +90,16 @@ class Config(object):
         """ add a named group of options to the current testing session. 
             This function gets invoked during testing session initialization. 
         """ 
+        for spec in specs:
+            for shortopt in spec._short_opts:
+                if not shortopt.isupper(): 
+                    raise ValueError(
+                        "custom options must be capital letter "
+                        "got %r" %(spec,)
+                    )
+        return self._addoptions(groupname, *specs)
+
+    def _addoptions(self, groupname, *specs):
         optgroup = optparse.OptionGroup(self._parser, groupname) 
         optgroup.add_options(specs) 
         self._parser.add_option_group(optgroup)

py/test/defaultconftest.py

@@ -28,9 +28,9 @@ _dist_import_pypy = False # used for regenerating JS application
 
 # ===================================================
 
-Option = py.test.config.Option
+def adddefaultoptions(config):
-def adddefaultoptions():
+    Option = config.Option 
-    py.test.config.addoptions('general options',
+    config._addoptions('general options',
         Option('-v', '--verbose',
                action="count", dest="verbose", default=0,
                help="increase verbosity."),
@@ -68,7 +68,7 @@ def adddefaultoptions():
                help="trace considerations of conftest.py files."),
     )
 
-    py.test.config.addoptions('EXPERIMENTAL options',
+    config._addoptions('EXPERIMENTAL options',
         Option('-f', '--looponfailing',
                action="store_true", dest="looponfailing", default=False,
                help="loop on failing test set."),

py/test/testing/test_config.py

@@ -17,20 +17,38 @@ def test_config_cmdline_options():
             option.tdest = True
         Option = py.test.config.Option
         option = py.test.config.addoptions("testing group", 
-            Option('-g', '--glong', action="store", default=42,
+            Option('-G', '--glong', action="store", default=42,
                    type="int", dest="gdest", help="g value."), 
             # XXX note: special case, option without a destination
-            Option('-t', '--tlong', action="callback", callback=_callback,
+            Option('-T', '--tlong', action="callback", callback=_callback,
                     help='t value'),
             )
         """))
     old = o.chdir() 
     try: 
-        config = py.test.config._reparse(['-g', '17'])
+        config = py.test.config._reparse(['-G', '17'])
     finally: 
         old.chdir() 
     assert config.option.gdest == 17 
 
+def test_config_cmdline_options_only_lowercase(): 
+    o = py.test.ensuretemp('test_config_cmdline_options_only_lowercase')
+    o.ensure("conftest.py").write(py.code.Source(""" 
+        import py
+        Option = py.test.config.Option
+        options = py.test.config.addoptions("testing group", 
+            Option('-g', '--glong', action="store", default=42,
+                   type="int", dest="gdest", help="g value."), 
+            )
+        """))
+    old = o.chdir() 
+    try: 
+        py.test.raises(ValueError, """
+            py.test.config._reparse(['-g', '17'])
+        """)
+    finally: 
+        old.chdir() 
+
 def test_parsing_again_fails():
     dir = py.test.ensuretemp("parsing_again_fails")
     config = py.test.config._reparse([str(dir)])
@@ -160,10 +178,10 @@ def test_config_rconfig():
     import py
     Option = py.test.config.Option
     option = py.test.config.addoptions("testing group", 
-            Option('-g', '--glong', action="store", default=42,
+            Option('-G', '--glong', action="store", default=42,
                    type="int", dest="gdest", help="g value."))
     """))
-    config = py.test.config._reparse([tmp, "-g", "11"])
+    config = py.test.config._reparse([tmp, "-G", "11"])
     assert config.option.gdest == 11
     repr = config.make_repr(conftestnames=[])
     config = py.test.config._reparse([tmp.dirpath()])