[Python-checkins] r54352 - in python/trunk: Lib/pydoc.py Misc/NEWS

[georg.brandl]

Author: georg.brandl
Date: Tue Mar 13 21:02:57 2007
New Revision: 54352

Modified:
   python/trunk/Lib/pydoc.py
   python/trunk/Misc/NEWS
Log:
Patch #1530482: add pydoc.render_doc() which returns the documentation
for a thing instead of paging it to stdout, which pydoc.doc() does.


Modified: python/trunk/Lib/pydoc.py
==============================================================================
--- python/trunk/Lib/pydoc.py	(original)
+++ python/trunk/Lib/pydoc.py	Tue Mar 13 21:02:57 2007
@@ -1461,31 +1461,35 @@
     else:
         return thing, getattr(thing, '__name__', None)
 
+def render_doc(thing, title='Python Library Documentation: %s', forceload=0):
+    """Render text documentation, given an object or a path to an object."""
+    object, name = resolve(thing, forceload)
+    desc = describe(object)
+    module = inspect.getmodule(object)
+    if name and '.' in name:
+        desc += ' in ' + name[:name.rfind('.')]
+    elif module and module is not object:
+        desc += ' in module ' + module.__name__
+    if type(object) is _OLD_INSTANCE_TYPE:
+        # If the passed object is an instance of an old-style class,
+        # document its available methods instead of its value.
+        object = object.__class__
+    elif not (inspect.ismodule(object) or
+              inspect.isclass(object) or
+              inspect.isroutine(object) or
+              inspect.isgetsetdescriptor(object) or
+              inspect.ismemberdescriptor(object) or
+              isinstance(object, property)):
+        # If the passed object is a piece of data or an instance,
+        # document its available methods instead of its value.
+        object = type(object)
+        desc += ' object'
+    return title % desc + '\n\n' + text.document(object, name)
+
 def doc(thing, title='Python Library Documentation: %s', forceload=0):
     """Display text documentation, given an object or a path to an object."""
     try:
-        object, name = resolve(thing, forceload)
-        desc = describe(object)
-        module = inspect.getmodule(object)
-        if name and '.' in name:
-            desc += ' in ' + name[:name.rfind('.')]
-        elif module and module is not object:
-            desc += ' in module ' + module.__name__
-        if type(object) is _OLD_INSTANCE_TYPE:
-            # If the passed object is an instance of an old-style class,
-            # document its available methods instead of its value.
-            object = object.__class__
-        elif not (inspect.ismodule(object) or
-                  inspect.isclass(object) or
-                  inspect.isroutine(object) or
-                  inspect.isgetsetdescriptor(object) or
-                  inspect.ismemberdescriptor(object) or
-                  isinstance(object, property)):
-            # If the passed object is a piece of data or an instance,
-            # document its available methods instead of its value.
-            object = type(object)
-            desc += ' object'
-        pager(title % desc + '\n\n' + text.document(object, name))
+        pager(render_doc(thing, title, forceload))
     except (ImportError, ErrorDuringImport), value:
         print value
 

Modified: python/trunk/Misc/NEWS
==============================================================================
--- python/trunk/Misc/NEWS	(original)
+++ python/trunk/Misc/NEWS	Tue Mar 13 21:02:57 2007
@@ -168,6 +168,9 @@
 Library
 -------
 
+- Patch #1530482: add pydoc.render_doc() which returns the documentation
+  for a thing instead of paging it to stdout, which pydoc.doc() does.
+
 - Patch #1533909: the timeit module now accepts callables in addition to
   strings for the code to time and the setup code. Also added two
   convenience functions for instantiating a Timer and calling its methods.