[Checkins] SVN: zope.testing/trunk/ Add a doctest for zope.testing.module, so that people know what it is

[Martijn Faassen]

Log message for revision 87775:
  Add a doctest for zope.testing.module, so that people know what it is
  about, and to fix a few bugs.
  

Changed:
  U   zope.testing/trunk/README.txt
  U   zope.testing/trunk/src/zope/testing/module.py
  A   zope.testing/trunk/src/zope/testing/module.txt
  U   zope.testing/trunk/src/zope/testing/tests.py

-=-
Modified: zope.testing/trunk/README.txt
===================================================================
--- zope.testing/trunk/README.txt	2008-06-25 20:06:55 UTC (rev 87774)
+++ zope.testing/trunk/README.txt	2008-06-25 20:53:43 UTC (rev 87775)
@@ -76,6 +76,17 @@
 - Unified unit tests with the layer support by introducing a real unit test
   layer.
 
+- Added a doctest for ``zope.testing.module``. There were several bugs
+  that were fixed:
+  
+  * ``README.txt`` was a really bad default argument for the module
+    name, as it is not a proper dotted name. The code would
+    immediately fail as it would look for the ``txt`` module in the
+    ``README`` package. The default is now ``__main__``.
+
+  * The tearDown function did not clean up the ``__name__`` entry in the
+    global dictionary.
+
 3.5.1 (2007/08/14)
 ==================
 

Modified: zope.testing/trunk/src/zope/testing/module.py
===================================================================
--- zope.testing/trunk/src/zope/testing/module.py	2008-06-25 20:06:55 UTC (rev 87774)
+++ zope.testing/trunk/src/zope/testing/module.py	2008-06-25 20:53:43 UTC (rev 87775)
@@ -27,7 +27,7 @@
         except KeyError:
             raise AttributeError(name)
 
-def setUp(test, name='README.txt'):
+def setUp(test, name='__main__'):
     dict = test.globs
     dict['__name__'] = name
     module = FakeModule(dict)
@@ -40,6 +40,7 @@
 def tearDown(test, name=None):
     if name is None:
         name = test.globs['__name__']
+    del test.globs['__name__']
     del sys.modules[name]
     if '.' in name:
         name = name.split('.')

Added: zope.testing/trunk/src/zope/testing/module.txt
===================================================================
--- zope.testing/trunk/src/zope/testing/module.txt	                        (rev 0)
+++ zope.testing/trunk/src/zope/testing/module.txt	2008-06-25 20:53:43 UTC (rev 87775)
@@ -0,0 +1,106 @@
+Module setup
+============
+
+Normally when you create a class in a doctest, it will have the
+``__module__`` attribute of ``'__builtin__'``. This is sometimes not
+desirable. Let's demonstrate the behavior::
+
+  >>> class Foo(object):
+  ...    pass
+
+  >>> Foo.__module__
+  '__builtin__'
+
+By using ``zope.testing.module.setUp`` this can be
+controlled. Normally you set up your tests with it, but in this case
+we'll just call it manually.
+
+To call this function manually, we need to set up a fake ``test``
+object.  This because the ``setUp`` function expects a test with at
+least the ``globs`` dictionary attribute being present. Let's make
+such a fake test object, using the globals of the doctest::
+
+  >>> class FakeTest(object):
+  ...     def __init__(self):
+  ...        self.globs = globals()
+
+  >>> test = FakeTest()
+
+We can now call the ``setUp`` function::
+
+  >>> from zope.testing.module import setUp
+  >>> setUp(test)
+
+We will now demonstrate that the ``__module__`` argument is something
+else, in this case the default, ``__main__``::
+
+  >>> class Foo(object):
+  ...     pass
+  >>> Foo.__module__
+  '__main__'
+
+Let's tear this down again::
+
+  >>> from zope.testing.module import tearDown
+  >>> tearDown(test)
+
+We should now be back to the original situation::
+
+  >>> class Foo(object):
+  ...    pass
+  >>> Foo.__module__
+  '__builtin__'
+
+Importing
+---------
+
+Let's now imagine a more complicated example, were we actually want to
+be able to import the fake module as well::
+
+  >>> setUp(test, 'fake')
+  >>> a = 'Hello world'
+
+The import should not fail::
+
+  >>> import fake
+  >>> fake.a
+  'Hello world'
+
+Let's tear it down again::
+
+  >>> tearDown(test)
+  >>> import fake
+  Traceback (most recent call last):
+    ...
+  ImportError: No module named fake
+
+If we enter a dotted name, it will actually try to place the fake
+module in that dotted name::
+
+  >>> setUp(test, 'zope.testing.unlikelymodulename')
+  >>> a = 'Bye world'
+  >>> import zope.testing.unlikelymodulename
+  >>> zope.testing.unlikelymodulename.a
+  'Bye world'
+  >>> from zope.testing import unlikelymodulename
+  >>> unlikelymodulename.a
+  'Bye world'
+  >>> tearDown(test)
+  >>> import zope.testing.unlikelymodulename
+  Traceback (most recent call last):
+    ...
+  ImportError: No module named unlikelymodulename
+
+This only works for packages that already exist::
+ 
+  >>> setUp(test, 'unlikelynamespacename.fake')
+  Traceback (most recent call last):
+    ...
+  KeyError: 'unlikelynamespacename'
+
+Even so, we still need to tear down::
+
+  >>> tearDown(test)
+  Traceback (most recent call last):
+    ...
+  KeyError: 'unlikelynamespacename'

Modified: zope.testing/trunk/src/zope/testing/tests.py
===================================================================
--- zope.testing/trunk/src/zope/testing/tests.py	2008-06-25 20:06:55 UTC (rev 87774)
+++ zope.testing/trunk/src/zope/testing/tests.py	2008-06-25 20:53:43 UTC (rev 87775)
@@ -21,7 +21,6 @@
 import unittest
 from zope.testing import doctest, testrunner
 
-
 def test_suite():
     return unittest.TestSuite((
         doctest.DocTestSuite('zope.testing.renormalizing'),
@@ -29,4 +28,5 @@
         doctest.DocTestSuite('zope.testing.loggingsupport'),
         doctest.DocTestSuite('zope.testing.server'),
         doctest.DocFileSuite('setupstack.txt'),
+        doctest.DocFileSuite('module.txt'),
         ))