[Python-checkins] r46664 - in python/trunk: Doc/lib/libdoctest.tex Lib/doctest.py Lib/test/test_doctest.py Misc/NEWS

Mon Jun 5 03:43:15 CEST 2006

Author: tim.peters
Date: Mon Jun 5 03:43:03 2006
New Revision: 46664
Modified:
 python/trunk/Doc/lib/libdoctest.tex
 python/trunk/Lib/doctest.py
 python/trunk/Lib/test/test_doctest.py
 python/trunk/Misc/NEWS
Log:
Remove doctest.testmod's deprecated (in 2.4) `isprivate`
argument. A lot of hair went into supporting that!
Modified: python/trunk/Doc/lib/libdoctest.tex
==============================================================================

--- python/trunk/Doc/lib/libdoctest.tex	(original)
+++ python/trunk/Doc/lib/libdoctest.tex	Mon Jun 5 03:43:03 2006
@@ -952,7 +952,7 @@
 
 \begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
 globs}\optional{, verbose}\optional{,
- isprivate}\optional{, report}\optional{,
+ report}\optional{,
 optionflags}\optional{, extraglobs}\optional{,
 raise_on_error}\optional{, exclude_empty}}
 
@@ -990,19 +990,14 @@
 for function \function{testfile()} above, except that \var{globs}
 defaults to \code{\var{m}.__dict__}.
 
- Optional argument \var{isprivate} specifies a function used to
- determine whether a name is private. The default function treats
- all names as public. \var{isprivate} can be set to
- \code{doctest.is_private} to skip over names that are
- private according to Python's underscore naming convention.
- \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it.
- If you need to skip tests based on name, filter the list returned by
- \code{DocTestFinder.find()} instead.}
-
 \versionchanged[The parameter \var{optionflags} was added]{2.3}
 
 \versionchanged[The parameters \var{extraglobs}, \var{raise_on_error}
 and \var{exclude_empty} were added]{2.4}
+
+ \versionchanged[The optional argument \var{isprivate}, deprecated
+ in 2.4, was removed]{2.5}
+
 \end{funcdesc}
 
 There's also a function to run the doctests associated with a single object.
Modified: python/trunk/Lib/doctest.py
==============================================================================
--- python/trunk/Lib/doctest.py	(original)
+++ python/trunk/Lib/doctest.py	Mon Jun 5 03:43:03 2006
@@ -63,7 +63,6 @@
 'REPORT_ONLY_FIRST_FAILURE',
 'REPORTING_FLAGS',
 # 1. Utility Functions
- 'is_private',
 # 2. Example & DocTest
 'Example',
 'DocTest',
@@ -101,11 +100,6 @@
 import warnings
 from StringIO import StringIO
 
-# Don't whine about the deprecated is_private function in this
-# module's tests.
-warnings.filterwarnings("ignore", "is_private", DeprecationWarning,
- __name__, 0)
-
 # There are 4 basic classes:
 # - Example: a <source, want> pair, plus an intra-docstring line number.
 # - DocTest: a collection of examples, parsed from a docstring, plus
@@ -178,35 +172,6 @@
 ## 1. Utility Functions
 ######################################################################
 
-def is_private(prefix, base):
- """prefix, base -> true iff name prefix + "." + base is "private".
-
- Prefix may be an empty string, and base does not contain a period.
- Prefix is ignored (although functions you write conforming to this
- protocol may make use of it).
- Return true iff base begins with an (at least one) underscore, but
- does not both begin and end with (at least) two underscores.
-
- >>> is_private("a.b", "my_func")
- False
- >>> is_private("____", "_my_func")
- True
- >>> is_private("someclass", "__init__")
- False
- >>> is_private("sometypo", "__init_")
- True
- >>> is_private("x.y.z", "_")
- True
- >>> is_private("_x.y.z", "__")
- False
- >>> is_private("", "") # senseless but consistent
- False
- """
- warnings.warn("is_private is deprecated; it wasn't useful; "
- "examine DocTestFinder.find() lists instead",
- DeprecationWarning, stacklevel=2)
- return base[:1] == "_" and not base[:2] == "__" == base[-2:]
-
 def _extract_future_flags(globs):
 """
 Return the compiler-flags associated with the future features that
@@ -759,7 +724,7 @@
 """
 
 def __init__(self, verbose=False, parser=DocTestParser(),
- recurse=True, _namefilter=None, exclude_empty=True):
+ recurse=True, exclude_empty=True):
 """
 Create a new doctest finder.
 
@@ -779,12 +744,8 @@
 self._verbose = verbose
 self._recurse = recurse
 self._exclude_empty = exclude_empty
- # _namefilter is undocumented, and exists only for temporary backward-
- # compatibility support of testmod's deprecated isprivate mess.
- self._namefilter = _namefilter
 
- def find(self, obj, name=None, module=None, globs=None,
- extraglobs=None):
+ def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
 """
 Return a list of the DocTests that are defined by the given
 object's docstring, or by any of its contained objects'
@@ -862,13 +823,6 @@
 self._find(tests, obj, name, module, source_lines, globs, {})
 return tests
 
- def _filter(self, obj, prefix, base):
- """
- Return true if the given object should not be examined.
- """
- return (self._namefilter is not None and
- self._namefilter(prefix, base))
-
 def _from_module(self, module, object):
 """
 Return true if the given object is defined in the given
@@ -910,9 +864,6 @@
 # Look for tests in a module's contained objects.
 if inspect.ismodule(obj) and self._recurse:
 for valname, val in obj.__dict__.items():
- # Check if this contained object should be ignored.
- if self._filter(val, name, valname):
- continue
 valname = '%s.%s' % (name, valname)
 # Recurse to functions & classes.
 if ((inspect.isfunction(val) or inspect.isclass(val)) and
@@ -941,9 +892,6 @@
 # Look for tests in a class's contained objects.
 if inspect.isclass(obj) and self._recurse:
 for valname, val in obj.__dict__.items():
- # Check if this contained object should be ignored.
- if self._filter(val, name, valname):
- continue
 # Special handling for staticmethod/classmethod.
 if isinstance(val, staticmethod):
 val = getattr(obj, valname)
@@ -1751,17 +1699,16 @@
 # class, updated by testmod.
 master = None
 
-def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None,
+def testmod(m=None, name=None, globs=None, verbose=None,
 report=True, optionflags=0, extraglobs=None,
 raise_on_error=False, exclude_empty=False):
- """m=None, name=None, globs=None, verbose=None, isprivate=None,
- report=True, optionflags=0, extraglobs=None, raise_on_error=False,
+ """m=None, name=None, globs=None, verbose=None, report=True,
+ optionflags=0, extraglobs=None, raise_on_error=False,
 exclude_empty=False
 
 Test examples in docstrings in functions and classes reachable
 from module m (or the current module if m is not supplied), starting
- with m.__doc__. Unless isprivate is specified, private names
- are not skipped.
+ with m.__doc__.
 
 Also test examples reachable from dict m.__test__ if it exists and is
 not None. m.__test__ maps names to functions, classes and strings;
@@ -1810,13 +1757,6 @@
 first unexpected exception or failure. This allows failures to be
 post-mortem debugged.
 
- Deprecated in Python 2.4:
- Optional keyword arg "isprivate" specifies a function used to
- determine whether a name is private. The default function is
- treat all functions as public. Optionally, "isprivate" can be
- set to doctest.is_private to skip over functions marked as private
- using the underscore naming convention; see its docs for details.
-
 Advanced tomfoolery: testmod runs methods of a local instance of
 class doctest.Tester, then merges the results into (or creates)
 global Tester instance doctest.master. Methods of doctest.master
@@ -1827,11 +1767,6 @@
 """
 global master
 
- if isprivate is not None:
- warnings.warn("the isprivate argument is deprecated; "
- "examine DocTestFinder.find() lists instead",
- DeprecationWarning)
-
 # If no module was given, then use __main__.
 if m is None:
 # DWA - m will still be None if this wasn't invoked from the command
@@ -1848,7 +1783,7 @@
 name = m.__name__
 
 # Find, parse, and run all tests in the given module.
- finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty)
+ finder = DocTestFinder(exclude_empty=exclude_empty)
 
 if raise_on_error:
 runner = DebugRunner(verbose=verbose, optionflags=optionflags)
@@ -2021,8 +1956,7 @@
 # actually used in any way.
 
 class Tester:
- def __init__(self, mod=None, globs=None, verbose=None,
- isprivate=None, optionflags=0):
+ def __init__(self, mod=None, globs=None, verbose=None, optionflags=0):
 
 warnings.warn("class Tester is deprecated; "
 "use class doctest.DocTestRunner instead",
@@ -2037,9 +1971,8 @@
 self.globs = globs
 
 self.verbose = verbose
- self.isprivate = isprivate
 self.optionflags = optionflags
- self.testfinder = DocTestFinder(_namefilter=isprivate)
+ self.testfinder = DocTestFinder()
 self.testrunner = DocTestRunner(verbose=verbose,
 optionflags=optionflags)
 
Modified: python/trunk/Lib/test/test_doctest.py
==============================================================================
--- python/trunk/Lib/test/test_doctest.py	(original)
+++ python/trunk/Lib/test/test_doctest.py	Mon Jun 5 03:43:03 2006
@@ -512,15 +512,11 @@
 >>> tests[1].name.split('.')[-1] in ['f', 'g']
 True
 
-Filter Functions
-~~~~~~~~~~~~~~~~
-A filter function can be used to restrict which objects get examined,
-but this is temporary, undocumented internal support for testmod's
-deprecated isprivate gimmick.
-
- >>> def namefilter(prefix, base):
- ... return base.startswith('a_')
- >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass)
+Empty Tests
+~~~~~~~~~~~
+By default, an object with no doctests doesn't create any tests:
+
+ >>> tests = doctest.DocTestFinder().find(SampleClass)
 >>> tests.sort()
 >>> for t in tests:
 ... print '%2s %s' % (len(t.examples), t.name)
@@ -528,6 +524,9 @@
 3 SampleClass.NestedClass
 1 SampleClass.NestedClass.__init__
 1 SampleClass.__init__
+ 2 SampleClass.a_classmethod
+ 1 SampleClass.a_property
+ 1 SampleClass.a_staticmethod
 1 SampleClass.double
 1 SampleClass.get
 
@@ -536,8 +535,7 @@
 is really to support backward compatibility in what doctest.master.summarize()
 displays.
 
- >>> tests = doctest.DocTestFinder(_namefilter=namefilter,
- ... exclude_empty=False).find(SampleClass)
+ >>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
 >>> tests.sort()
 >>> for t in tests:
 ... print '%2s %s' % (len(t.examples), t.name)
@@ -547,35 +545,12 @@
 0 SampleClass.NestedClass.get
 0 SampleClass.NestedClass.square
 1 SampleClass.__init__
- 1 SampleClass.double
- 1 SampleClass.get
-
-If a given object is filtered out, then none of the objects that it
-contains will be added either:
-
- >>> def namefilter(prefix, base):
- ... return base == 'NestedClass'
- >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass)
- >>> tests.sort()
- >>> for t in tests:
- ... print '%2s %s' % (len(t.examples), t.name)
- 3 SampleClass
- 1 SampleClass.__init__
 2 SampleClass.a_classmethod
 1 SampleClass.a_property
 1 SampleClass.a_staticmethod
 1 SampleClass.double
 1 SampleClass.get
 
-The filter function apply to contained objects, and *not* to the
-object explicitly passed to DocTestFinder:
-
- >>> def namefilter(prefix, base):
- ... return base == 'SampleClass'
- >>> tests = doctest.DocTestFinder(_namefilter=namefilter).find(SampleClass)
- >>> len(tests)
- 9
-
 Turning off Recursion
 ~~~~~~~~~~~~~~~~~~~~~
 DocTestFinder can be told not to look for tests in contained objects
@@ -1913,20 +1888,6 @@
 modified the test globals, which are a copy of the
 sample_doctest module dictionary. The test globals are
 automatically cleared for us after a test.
-
- Finally, you can provide an alternate test finder. Here we'll
- use a custom test_finder to to run just the test named bar.
- However, the test in the module docstring, and the two tests
- in the module __test__ dict, aren't filtered, so we actually
- run three tests besides bar's. The filtering mechanisms are
- poorly conceived, and will go away someday.
-
- >>> finder = doctest.DocTestFinder(
- ... _namefilter=lambda prefix, base: base!='bar')
- >>> suite = doctest.DocTestSuite('test.sample_doctest',
- ... test_finder=finder)
- >>> suite.run(unittest.TestResult())
- <unittest.TestResult run=4 errors=0 failures=1>
 """
 
 def test_DocFileSuite():
Modified: python/trunk/Misc/NEWS
==============================================================================
--- python/trunk/Misc/NEWS	(original)
+++ python/trunk/Misc/NEWS	Mon Jun 5 03:43:03 2006
@@ -106,6 +106,9 @@
 Library
 -------
 
+- The optional ``is_private`` argument to ``doctest.testmod()``, deprecated
+ in 2.4, was removed.
+
 - Patch #1359618: Speed up charmap encoder by using a trie structure
 for lookup.
 
