[Checkins] SVN: zope.dottedname/trunk/ - tidy up docs

[Chris Withers]

Log message for revision 93550:
  - tidy up docs
  - add more tests
  - correct pypi url
  - ignore egg-info directories.

Changed:
  U   zope.dottedname/trunk/CHANGES.txt
  U   zope.dottedname/trunk/README.txt
  U   zope.dottedname/trunk/setup.py
  _U  zope.dottedname/trunk/src/
  D   zope.dottedname/trunk/src/zope/dottedname/resolve.txt
  U   zope.dottedname/trunk/src/zope/dottedname/tests.py

-=-
Modified: zope.dottedname/trunk/CHANGES.txt
===================================================================
--- zope.dottedname/trunk/CHANGES.txt	2008-12-02 18:33:31 UTC (rev 93549)
+++ zope.dottedname/trunk/CHANGES.txt	2008-12-02 21:09:23 UTC (rev 93550)
@@ -1,4 +1,3 @@
-=======
 CHANGES
 =======
 

Modified: zope.dottedname/trunk/README.txt
===================================================================
--- zope.dottedname/trunk/README.txt	2008-12-02 18:33:31 UTC (rev 93549)
+++ zope.dottedname/trunk/README.txt	2008-12-02 21:09:23 UTC (rev 93550)
@@ -2,10 +2,60 @@
 Dotted Name Resolution
 ======================
 
-Overview
---------
+The ``zope.dottedname`` module provides one function, ``resolve`` that
+resolves strings containing dotted names into the appropriate python
+object. 
 
-The ``zope.dottedname.resolve`` module provides a function for resolving
-dotted names.  Dotted names are resolved by importing modules and by
-getting attributes from imported modules.  Names with leading dots are
-relative.
+Dotted names are resolved by importing modules and by getting
+attributes from imported modules. Names may be relative, provided the
+module they are relative to is supplied.
+
+Here are some examples of importing absolute names:
+
+>>> from zope.dottedname.resolve import resolve
+
+>>> resolve('unittest')
+<module 'unittest' from '...'>
+
+>>> resolve('datetime.datetime')
+<type 'datetime.datetime'>
+
+>>> resolve('datetime.datetime.now')
+<built-in method now of type object at ...>
+
+>>> resolve('non existent module')
+Traceback (most recent call last):
+...
+ImportError: No module named non existent module
+
+>>> resolve('__doc__')
+Traceback (most recent call last):
+...
+ImportError: No module named __doc__
+
+>>> resolve('datetime.foo')
+Traceback (most recent call last):
+...
+ImportError: No module named foo
+
+>>> resolve('os.path.split').__name__
+'split'
+
+Here are some examples of importing relative names:
+
+>>> resolve('.split', 'os.path')
+<function split at ...>
+
+>>> resolve('..system', 'os.path')
+<built-in function system>
+
+>>> resolve('...datetime', 'os.path')
+<module 'datetime' (built-in)>
+
+NB: When relative names are imported, a module the name is relative to
+**must** be supplied:
+
+>>> resolve('.split').__name__
+Traceback (most recent call last):
+...
+ValueError: relative name without base module

Modified: zope.dottedname/trunk/setup.py
===================================================================
--- zope.dottedname/trunk/setup.py	2008-12-02 18:33:31 UTC (rev 93549)
+++ zope.dottedname/trunk/setup.py	2008-12-02 21:09:23 UTC (rev 93550)
@@ -26,15 +26,9 @@
       author='Zope Corporation and Contributors',
       author_email='zope3-dev at zope.org',
       description='Resolver for Python dotted names.',
-      long_description=(
-          read('README.txt')
-          + '\n\n' +
-          'Detailed Documentation' +
-          '----------------------'
-          + '\n\n' +
-          read('src', 'zope', 'dottedname', 'resolve.txt')
-          + '\n\n' +
-          read('CHANGES.txt')
+      long_description='\n\n'.join(
+          read('README.txt'),
+          read('CHANGES.txt'),
           ),
       keywords = 'resolve dotted name',
       classifiers = [
@@ -47,7 +41,7 @@
           'Operating System :: OS Independent',
           'Topic :: Internet :: WWW/HTTP',
           'Framework :: Zope3'],
-      url='http://cheeseshop.python.org/pypi/zope.dottedname',
+      url='http://pypi.python.org/pypi/zope.dottedname',
       license='ZPL 2.1',
       packages=find_packages('src'),
       package_dir = {'': 'src'},


Property changes on: zope.dottedname/trunk/src
___________________________________________________________________
Added: svn:ignore
   + *.egg-info


Deleted: zope.dottedname/trunk/src/zope/dottedname/resolve.txt
===================================================================
--- zope.dottedname/trunk/src/zope/dottedname/resolve.txt	2008-12-02 18:33:31 UTC (rev 93549)
+++ zope.dottedname/trunk/src/zope/dottedname/resolve.txt	2008-12-02 21:09:23 UTC (rev 93550)
@@ -1,32 +0,0 @@
-Resolution of dotted names
-==========================
-
-The ``zope.dottedname.resolve`` module provides a function for resolving
-dotted names.  Dotted names are resolved by importing modules and by
-getting attributes from imported modules.  Names with leading dots are
-relative.
-
-To illustrate, we'll use the dotted name resolver to access objects in
-the ``os`` module::
-
-    >>> from zope.dottedname.resolve import resolve
-    >>> resolve('os.path.split').__name__
-    'split'
-
-Here, we used an absolute name.  We can also using a relative name::
-
-    >>> resolve('.split').__name__
-    Traceback (most recent call last):
-    ...
-    ValueError: relative name without base module
-
-But we need to provide the module the name is relative to::
-
-    >>> resolve('.split', 'os.path').__name__
-    'split'
-
-    >>> resolve('..system', 'os.path').__name__
-    'system'
-
-    >>> resolve('...datetime', 'os.path').__name__
-    'datetime'

Modified: zope.dottedname/trunk/src/zope/dottedname/tests.py
===================================================================
--- zope.dottedname/trunk/src/zope/dottedname/tests.py	2008-12-02 18:33:31 UTC (rev 93549)
+++ zope.dottedname/trunk/src/zope/dottedname/tests.py	2008-12-02 21:09:23 UTC (rev 93550)
@@ -15,12 +15,15 @@
 
 $Id$
 """
-import unittest
-from zope.testing import doctest
+import os,unittest
+from zope.testing.doctest import DocFileSuite,REPORT_NDIFF,ELLIPSIS
 
 def test_suite():
     return unittest.TestSuite((
-        doctest.DocFileSuite('resolve.txt'),
+        DocFileSuite(
+            os.path.abspath(os.path.join(os.path.dirname(__file__),'..','..','..','README.txt')),
+            optionflags=REPORT_NDIFF|ELLIPSIS
+            ),
         ))
 
 if __name__ == '__main__':