adding docstrings to lib
authorandy
Fri, 12 Dec 2008 15:55:34 +0000
changeset 3029 eded59f94021
parent 3028 082f5208644e
child 3030 8bc2e0f9c080
adding docstrings to lib
docs/gen_epydoc
src/reportlab/lib/PyFontify.py
src/reportlab/lib/abag.py
src/reportlab/lib/attrmap.py
src/reportlab/lib/boxstuff.py
src/reportlab/lib/codecharts.py
src/reportlab/lib/colors.py
src/reportlab/lib/corp.py
src/reportlab/lib/enums.py
src/reportlab/lib/extformat.py
src/reportlab/lib/fontfinder.py
src/reportlab/lib/fonts.py
src/reportlab/lib/logger.py
src/reportlab/lib/normalDate.py
src/reportlab/lib/randomtext.py
src/reportlab/lib/rltempfile.py
src/reportlab/lib/rparsexml.py
src/reportlab/lib/sequencer.py
src/reportlab/lib/set_ops.py
src/reportlab/lib/styles.py
src/reportlab/lib/testutils.py
src/reportlab/lib/tocindex.py
src/reportlab/lib/units.py
src/reportlab/lib/utils.py
src/reportlab/lib/validators.py
src/reportlab/lib/xmllib.py
--- a/docs/gen_epydoc	Thu Dec 11 17:15:26 2008 +0000
+++ b/docs/gen_epydoc	Fri Dec 12 15:55:34 2008 +0000
@@ -1,2 +1,6 @@
 #!/bin/sh
+d=`dirname $0`
+[ x$d = x ] && d=`pwd`
+export PYTHONPATH=$d/../src
+
 epydoc --html reportlab --docformat=restructuredtext --no-private
--- a/src/reportlab/lib/PyFontify.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/PyFontify.py	Fri Dec 12 15:55:34 2008 +0000
@@ -1,4 +1,7 @@
-"""
+#Copyright ReportLab Europe Ltd. 2000-2008
+#see license.txt for license details
+__version__=''' $Id:$ '''
+__doc__="""
 Module to analyze Python source code; for syntax coloring tools.
 
 Interface::
--- a/src/reportlab/lib/abag.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/abag.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,11 +2,14 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/abag.py
 __version__=''' $Id$ '''
-
+__doc__='''Data structure to hold a collection of attributes, used by styles.'''
 class ABag:
     """
     'Attribute Bag' - a trivial BAG class for holding attributes.
 
+    This predates modern Python.  Doing this again, we'd use a subclass
+    of dict.
+
     You may initialize with keyword arguments.
     a = ABag(k0=v0,....,kx=vx,....) ==> getattr(a,'kx')==vx
 
--- a/src/reportlab/lib/attrmap.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/attrmap.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,6 +2,32 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/attrmap.py
 __version__=''' $Id$ '''
+__doc__='''Framework for objects whose assignments are checked. Used by graphics.
+
+We developed reportlab/graphics prior to Python 2 and metaclasses. For the
+graphics, we wanted to be able to declare the attributes of a class, check
+them on assignment, and convert from string arguments.  Examples of
+attrmap-based objects can be found in reportlab/graphics/shapes.  It lets
+us defined structures like the one below, which are seen more modern form in
+Django models and other frameworks.
+
+We'll probably replace this one day soon, hopefully with no impact on client
+code.
+
+class Rect(SolidShape):
+    """Rectangle, possibly with rounded corners."""
+
+    _attrMap = AttrMap(BASE=SolidShape,
+        x = AttrMapValue(isNumber),
+        y = AttrMapValue(isNumber),
+        width = AttrMapValue(isNumber),
+        height = AttrMapValue(isNumber),
+        rx = AttrMapValue(isNumber),
+        ry = AttrMapValue(isNumber),
+        )
+
+
+'''
 from UserDict import UserDict
 from reportlab.lib.validators import isAnything, _SequenceTypes, DerivedValue
 from reportlab import rl_config
--- a/src/reportlab/lib/boxstuff.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/boxstuff.py	Fri Dec 12 15:55:34 2008 +0000
@@ -1,6 +1,7 @@
 #Copyright ReportLab Europe Ltd. 2000-2006
 #see license.txt for license details
 __version__=''' $Id$ '''
+__doc__='''Utility functions to position and resize boxes within boxes'''
 def anchorAdjustXY(anchor,x,y,width,height):
     if anchor not in ('sw','s','se'):
         if anchor in ('e','c','w'):
--- a/src/reportlab/lib/codecharts.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/codecharts.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,7 +3,7 @@
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/codecharts.py
 #$Header $
 __version__=''' $Id '''
-__doc__="""Routines to print code page (character set) drawings.
+__doc__="""Routines to print code page (character set) drawings. Predates unicode.
 
 To be sure we can accurately represent characters in various encodings
 and fonts, we need some routines to display all those characters.
--- a/src/reportlab/lib/colors.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/colors.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,7 +2,17 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/colors.py
 __version__=''' $Id$ '''
+__doc__='''Defines standard colour-handling classes and colour names.
 
+We define standard classes to hold colours in two models:  RGB and CMYK.
+These can be constructed from several popular formats.  We also include
+
+- pre-built colour objects for the HTML standard colours
+
+- pre-built colours used in ReportLab's branding
+
+- various conversion and construction functions
+'''
 import string, math
 from types import StringType, ListType, TupleType
 from reportlab.lib.utils import fp_str
--- a/src/reportlab/lib/corp.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/corp.py	Fri Dec 12 15:55:34 2008 +0000
@@ -1,11 +1,13 @@
 #!/bin/env python
 #Copyright ReportLab Europe Ltd. 2000-2004
 #see license.txt for license details
-#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/corp.py
-""" This module includes some reusable routines for ReportLab's
+__version__=''' $Id$ '''
+__doc__="""Generate ReportLab logo in a variety of sizes and formats.
+
+
+This module includes some reusable routines for ReportLab's
  'Corporate Image' - the logo, standard page backdrops and
  so on - you are advised to do the same for your own company!"""
-__version__=''' $Id$ '''
 
 from reportlab.lib.units import inch,cm
 from reportlab.lib.validators import *
--- a/src/reportlab/lib/enums.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/enums.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,7 +3,7 @@
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/enums.py
 __version__=''' $Id$ '''
 __doc__="""
-holder for all reportlab's enumerated types
+Container for constants. Hardly used!
 """
 TA_LEFT = 0
 TA_CENTER = 1
--- a/src/reportlab/lib/extformat.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/extformat.py	Fri Dec 12 15:55:34 2008 +0000
@@ -1,6 +1,8 @@
 #Copyright ReportLab Europe Ltd. 2000-2004
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/extformat.py
+__version__='''$Id:$'''
+__doc__='''Apparently not used anywhere, purpose unknown!'''
 from tokenize import tokenprog
 import sys
 
--- a/src/reportlab/lib/fontfinder.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/fontfinder.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,7 +3,7 @@
 __version__=''' $Id$ '''
 
 #modification of users/robin/ttflist.py.
-"""This provides some general-purpose tools for finding fonts.
+__doc__="""This provides some general-purpose tools for finding fonts.
 
 The FontFinder object can search for font files.  It aims to build
 a catalogue of fonts which our framework can work with.  It may be useful
--- a/src/reportlab/lib/fonts.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/fonts.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,6 +3,16 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/fonts.py
 __version__=''' $Id$ '''
+__doc__='''Utilities to associate bold and italic versions of fonts into families
+
+Bold, italic and plain fonts are usually implemented in separate disk files;
+but non-trivial apps want <b>this</b> to do the right thing.   We therefore
+need to keep 'mappings' between the font family name and the right group
+of up to 4 implementation fonts to use.
+
+Most font-handling code lives in pdfbase, and this probably should too.
+
+'''
 import sys, os
 ###############################################################################
 #   A place to put useful font stuff
--- a/src/reportlab/lib/logger.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/logger.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,7 +3,7 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/logger.py
 __version__=''' $Id$ '''
-
+__doc__="Logging and warning framework, predating Python's logging package"
 from sys import stderr
 class Logger:
     '''
--- a/src/reportlab/lib/normalDate.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/normalDate.py	Fri Dec 12 15:55:34 2008 +0000
@@ -11,7 +11,7 @@
 # by Jeff Bauer of Rubicon Research and used
 # with his kind permission
 __version__=''' $Id$ '''
-
+__doc__="Jeff Bauer's lightweight date class, extended by us.  Predates Python's datetime module."
 
 
 _bigBangScalar = -4345732  # based on (-9999, 1, 1) BC/BCE minimum
--- a/src/reportlab/lib/randomtext.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/randomtext.py	Fri Dec 12 15:55:34 2008 +0000
@@ -8,7 +8,8 @@
 ###############################################################################
 #   generates so-called 'Greek Text' for use in filling documents.
 ###############################################################################
-"""
+__doc__="""Like Lorem Ipsum, but more fun and extensible.
+
 This module exposes a function randomText() which generates paragraphs.
 These can be used when testing out document templates and stylesheets.
 A number of 'themes' are provided - please contribute more!
--- a/src/reportlab/lib/rltempfile.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/rltempfile.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,6 +2,15 @@
 #see license.txt for license details
 # $URI:$
 __version__=''' $Id$ '''
+__doc__='''Helper for the test suite - determines where to write output.
+
+When our test suite runs as source, a script "test_foo.py" will typically
+create "test_foo.pdf" alongside it.  But if you are testing a package of
+compiled code inside a zip archive, this won't work.  This determines
+where to write test suite output, creating a subdirectory of /tmp/ or
+whatever if needed.
+
+'''
 _rl_tempdir=None
 __all__ = ('get_rl_tempdir', 'get_rl_tempdir')
 import os, tempfile
--- a/src/reportlab/lib/rparsexml.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/rparsexml.py	Fri Dec 12 15:55:34 2008 +0000
@@ -1,4 +1,15 @@
-"""Radically simple xml parsing
+"""Very simple and fast XML parser, used for intra-paragraph text.
+
+Devised by Aaron Watters in the bad old days before Python had fast
+parsers available.  Constructs the lightest possible in-memory
+representation; parses most files we have seen in pure python very
+quickly.
+
+The output structure is the same as the one produced by pyRXP,
+our validating C-based parser, which was written later.  It will
+use pyRXP if available.
+
+This is used to parse intra-paragraph markup.
 
 Example parse::
 
--- a/src/reportlab/lib/sequencer.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/sequencer.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,8 +2,7 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/sequencer.py
 __version__=''' $Id$ '''
-"""This module defines a single public class, Sequencer, which aids in
-numbering and formatting lists."""
+__doc__="""A Sequencer class counts things. It aids numbering and formatting lists."""
 __all__='''Sequencer getSequencer setSequencer'''.split()
 #
 # roman numbers conversion thanks to
--- a/src/reportlab/lib/set_ops.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/set_ops.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,6 +2,9 @@
 #Copyright ReportLab Europe Ltd. 2000-2004
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/set_ops.py
+__version__=''' $Id$ '''
+__doc__="""From before Python had a Set class..."""
+
 import types
 import string
 
--- a/src/reportlab/lib/styles.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/styles.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,7 +2,19 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/styles.py
 __version__=''' $Id$ '''
+__doc__='''Classes for ParagraphStyle and similar things.
 
+
+A style is a collection of attributes, but with some extra features
+to allow 'inheritance' from a parent, and to ensure nobody makes
+changes after construction.
+
+ParagraphStyle shows all the attributes available for formatting
+paragraphs.
+
+getSampleStyleSheet()  returns a stylesheet you can use for initial
+development, with a few basic heading and text styles.
+'''
 from reportlab.lib.colors import white, black
 from reportlab.lib.enums import TA_LEFT, TA_CENTER
 
--- a/src/reportlab/lib/testutils.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/testutils.py	Fri Dec 12 15:55:34 2008 +0000
@@ -1,8 +1,14 @@
 #Copyright ReportLab Europe Ltd. 2000-2008
 #see license.txt for license details
-"""Utilities for testing Python packages.
+__version__='''$Id$'''
+__doc__="""Provides support for the test suite.
+
+The test suite as a whole, and individual tests, need to share
+certain support functions.  We have to put these in here so they
+can always be imported, and so that individual tests need to import
+nothing more than "reportlab.whatever..."
 """
-__version__='''$Id$'''
+
 import sys, os, string, fnmatch, copy, re
 from ConfigParser import ConfigParser
 import unittest
--- a/src/reportlab/lib/tocindex.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/tocindex.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,11 +3,11 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/tocindex.py
 __version__=''' $Id$ '''
-__doc__=''
-"""
+__doc__="""Experimental Table-of-Contents and Index objects.
+
 This module will contain standard Table of Contents and Index objects.
 under development, and pending certain hooks adding in DocTemplate
-As of today, it onyl handles the formatting aspect of TOCs
+As of today, it only handles the formatting aspect of TOCs
 """
 
 import string
--- a/src/reportlab/lib/units.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/units.py	Fri Dec 12 15:55:34 2008 +0000
@@ -3,7 +3,14 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/units.py
 __version__=''' $Id$ '''
+__doc__='''Defines inch, cm, mm etc as multiples of a point
 
+You can now in user-friendly units by doing::
+
+    from reportlab.lib.units import inch
+    r = Rect(0, 0, 3 * inch, 6 * inch)
+
+'''
 inch = 72.0
 cm = inch / 2.54
 mm = cm * 0.1
--- a/src/reportlab/lib/utils.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/utils.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,6 +2,7 @@
 #see license.txt for license details
 # $URI:$
 __version__=''' $Id$ '''
+__doc__='''Gazillions of miscellaneous internal utility functions'''
 
 import string, os, sys, imp, time
 try:
--- a/src/reportlab/lib/validators.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/validators.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,10 +2,7 @@
 #see license.txt for license details
 #history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/lib/validators.py
 __version__=''' $Id$ '''
-"""
-This module contains some standard verifying functions which can be
-used in an attribute map.
-"""
+__doc__="""Standard verifying functions used by attrmap."""
 
 import string, sys, codecs
 from types import *
--- a/src/reportlab/lib/xmllib.py	Thu Dec 11 17:15:26 2008 +0000
+++ b/src/reportlab/lib/xmllib.py	Fri Dec 12 15:55:34 2008 +0000
@@ -2,6 +2,10 @@
 # Author: Sjoerd Mullender.
 
 # sgmlop support added by fredrik@pythonware.com (May 19, 1998)
+__version__=''' $Id$ '''
+__doc__='''From before xmllib was in the Python standard library.
+
+Probably ought to be removed'''
 
 import re
 import string