[Assorted-commits] SF.net SVN: assorted:[1450] python-commons/trunk/src/commons

[<yan...@us...>]

Revision: 1450
          http://assorted.svn.sourceforge.net/assorted/?rev=1450&view=rev
Author:   yangzhang
Date:     2009-06-03 17:37:26 +0000 (Wed, 03 Jun 2009)

Log Message:
-----------
fixed documentation issues

Modified Paths:
--------------
    python-commons/trunk/src/commons/async.py
    python-commons/trunk/src/commons/control.py
    python-commons/trunk/src/commons/decs.py
    python-commons/trunk/src/commons/files.py
    python-commons/trunk/src/commons/log.py
    python-commons/trunk/src/commons/misc.py
    python-commons/trunk/src/commons/path.py
    python-commons/trunk/src/commons/seqs.py
    python-commons/trunk/src/commons/servers.py
    python-commons/trunk/src/commons/sqlhash.py
    python-commons/trunk/src/commons/startup.py

Modified: python-commons/trunk/src/commons/async.py
===================================================================
--- python-commons/trunk/src/commons/async.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/async.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -15,7 +15,7 @@
     @param seconds: The amount of time in seconds to sleep.
     @type seconds: float
 
-    @return: The L{defer.Deferred} that will be fired on wake-up.
+    @return: The C{defer.Deferred} that will be fired on wake-up.
     @rtype: defer.Deferred
     """
     d = defer.Deferred()

Modified: python-commons/trunk/src/commons/control.py
===================================================================
--- python-commons/trunk/src/commons/control.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/control.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -17,7 +17,7 @@
     @classmethod
     def sleep( cls ):
         """
-        Calls L{time.sleep} for 100000 seconds at a time in a
+        Calls C{time.sleep} for 100000 seconds at a time in a
         while-true loop.
         """
         while True:

Modified: python-commons/trunk/src/commons/decs.py
===================================================================
--- python-commons/trunk/src/commons/decs.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/decs.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -76,7 +76,7 @@
     to return anything.
 
     Also, if the procedure returns a boolean, it will be wrapped in
-    L{xmlrpclib.Boolean}.
+    C{xmlrpclib.Boolean}.
 
     @param func: The procedure to decorate.
     @type func: function
@@ -119,7 +119,7 @@
     @param deserializer: The function te deserialize the cache file contents
                          into the return value.  This should take the file
                          object and return a string.
-    type: deserializer: function
+    @type deserializer: function
 
     @param pathfunc: Returns the path where the files should be saved.  This
                      should be able to take the same arguments as the original

Modified: python-commons/trunk/src/commons/files.py
===================================================================
--- python-commons/trunk/src/commons/files.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/files.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -67,7 +67,7 @@
     @param do_create_subdir: If C{True}, then creates a
     sub-sub-directory within the temporary sub-directory (and returns
     the path to that). The sub-sub-directory's name is randomized
-    (uses L{tempfile.mkdtemp}).
+    (uses C{tempfile.mkdtemp}).
     @type do_create_subdir: bool
 
     @return: The path to the temporary (sub-)sub-directory.

Modified: python-commons/trunk/src/commons/log.py
===================================================================
--- python-commons/trunk/src/commons/log.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/log.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -57,7 +57,7 @@
 
 def tailor_logs( flag, *prefix ):
     """
-    Avoid repetitive typing! Usage:
+    Avoid repetitive typing! Usage::
 
       debug,info,warning,_,_ = tailor_logs('myflag','some','prefix')
     """
@@ -94,7 +94,7 @@
     @type do_server: bool
 
     @param flags: The set of flags on which to lower the threshold to
-    L{logging.DEBUG}.
+    C{logging.DEBUG}.
     @type flags: iterable
 
     @param path: The path of the log file (only considered if

Modified: python-commons/trunk/src/commons/misc.py
===================================================================
--- python-commons/trunk/src/commons/misc.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/misc.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -79,15 +79,15 @@
     """
     A simple timer for code sections.
 
-    @param output: The resulting time is put into index 0 of L{output}.
-    @type output: index-writeable
+    Example::
 
-    Example:
+      t = [0]
+      with wall_clock(t):
+        sleep(1)
+      print "the sleep operation took %d seconds" % t[0]
 
-        t = [0]
-        with wall_clock(t):
-            sleep(1)
-        print "the sleep operation took %d seconds" % t[0]
+    @param output: The resulting time is put into index 0 of C{output}.
+    @type output: index-writeable
     """
     start = time()
     try:

Modified: python-commons/trunk/src/commons/path.py
===================================================================
--- python-commons/trunk/src/commons/path.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/path.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -1,19 +1,20 @@
 """ path.py - An object representing a path to a file or directory.
 
-Example:
+Example::
 
-from path import path
-d = path('/home/guido/bin')
-for f in d.files('*.py'):
+  from path import path
+  d = path('/home/guido/bin')
+  for f in d.files('*.py'):
     f.chmod(0755)
 
 This module requires Python 2.6 or later.
 
 
 URL:     http://www.jorendorff.com/articles/python/path
-Author:  Jason Orendorff <jason.orendorff\x40gmail\x2ecom> (and others - see the url!)
-         Yang Zhang <yaaang\x40gmail\x2ecom>
-Date:    2009
+
+@author: Jason Orendorff <jason.orendorff\x40gmail\x2ecom> (and others - see the url!)
+@author: Yang Zhang <yaaang\x40gmail\x2ecom>
+@date:   2009
 """
 
 
@@ -497,15 +498,14 @@
     def fnmatch(self, pattern):
         """ Return True if self.name matches the given pattern.
 
-        pattern - A filename pattern with wildcards,
-            for example '*.py'.
+        @param pattern: A filename pattern with wildcards, for example '*.py'.
         """
         return fnmatch.fnmatch(self.name, pattern)
 
     def glob(self, pattern):
         """ Return a list of path objects that match the pattern.
 
-        pattern - a path relative to this directory, with wildcards.
+        @param pattern: A path relative to this directory, with wildcards.
 
         For example, path('/users').glob('*/bin/*') returns a list
         of all the files users have in their bin directories.
@@ -552,11 +552,11 @@
 
         Optional arguments:
 
-        encoding - The Unicode encoding (or character set) of
+        @param encoding: The Unicode encoding (or character set) of
             the file.  If present, the content of the file is
             decoded and returned as a unicode object; otherwise
             it is returned as an 8-bit str.
-        errors - How to handle Unicode errors; see help(str.decode)
+        @param errors: How to handle Unicode errors; see help(str.decode)
             for the options.  Default is 'strict'.
         """
         if encoding is None:
@@ -673,19 +673,18 @@
     def lines(self, encoding=None, errors='strict', retain=True):
         r""" Open this file, read all lines, return them in a list.
 
-        Optional arguments:
-            encoding - The Unicode encoding (or character set) of
+        This uses 'U' mode in Python 2.3 and later.
+
+        @param encoding: The Unicode encoding (or character set) of
                 the file.  The default is None, meaning the content
                 of the file is read as 8-bit characters and returned
                 as a list of (non-Unicode) str objects.
-            errors - How to handle Unicode errors; see help(str.decode)
+        @param errors: How to handle Unicode errors; see help(str.decode)
                 for the options.  Default is 'strict'
-            retain - If true, retain newline characters; but all newline
+        @param retain: If true, retain newline characters; but all newline
                 character combinations ('\r', '\n', '\r\n') are
                 translated to '\n'.  If false, newline characters are
                 stripped off.  Default is True.
-
-        This uses 'U' mode in Python 2.3 and later.
         """
         if encoding is None and retain:
             f = self.open(_textmode)
@@ -705,15 +704,15 @@
         This puts a platform-specific newline sequence on every line.
         See 'linesep' below.
 
-        lines - A list of strings.
+        @param lines: A list of strings.
 
-        encoding - A Unicode encoding to use.  This applies only if
+        @param encoding: A Unicode encoding to use.  This applies only if
             'lines' contains any Unicode strings.
 
-        errors - How to handle errors in Unicode encoding.  This
+        @param errors: How to handle errors in Unicode encoding.  This
             also applies only to Unicode strings.
 
-        linesep - The desired line-ending.  This line-ending is
+        @param linesep: The desired line-ending.  This line-ending is
             applied to every line.  If a line already has any
             standard line ending ('\r', '\n', '\r\n', u'\x85',
             u'\r\x85', u'\u2028'), that will be stripped off and
@@ -722,13 +721,13 @@
             Unix, etc.)  Specify None to write the lines as-is,
             like file.writelines().
 
-        Use the keyword argument append=True to append lines to the
-        file.  The default is to overwrite the file.  Warning:
-        When you use this with Unicode data, if the encoding of the
-        existing data in the file is different from the encoding
-        you specify with the encoding= parameter, the result is
-        mixed-encoding data, which can really confuse someone trying
-        to read the file later.
+        @param append: Append lines to the
+            file.  The default is to overwrite the file.  Warning:
+            When you use this with Unicode data, if the encoding of the
+            existing data in the file is different from the encoding
+            you specify with the encoding= parameter, the result is
+            mixed-encoding data, which can really confuse someone trying
+            to read the file later.
         """
         if append:
             mode = 'ab'

Modified: python-commons/trunk/src/commons/seqs.py
===================================================================
--- python-commons/trunk/src/commons/seqs.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/seqs.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -50,7 +50,7 @@
     """
     Given a reader function L{read}, reads in pickled objects from it. I am a
     generator which yields unpickled objects. I assume that the pickling
-    is "safe," done using L{safe_pickle}.
+    is "safe," done using L{safe_pickler}.
 
     @param read: The reader function that reads from a stream. It should take
     a single argument, the number of bytes to consume.
@@ -220,7 +220,7 @@
         @return: The next number in the sequence.
         @rtype: int
 
-        @throw ClosedError: If I was previously L{close}d.
+        @raise ClosedError: If I was previously L{close}d.
         """
         if self.log is None:
             raise ClosedError()
@@ -239,7 +239,7 @@
         L{seqno}).
         @rtype: int
 
-        @throw ClosedError: If I was previously L{close}d.
+        @raise ClosedError: If I was previously L{close}d.
         """
         if self.log is None:
             raise ClosedError()
@@ -315,7 +315,7 @@
 
 def flatten( stream ):
     """
-    For each item yielded by L{gen}, if that item is itself an
+    For each item yielded by L{stream}, if that item is itself an
     iterator/generator, then I will recurse into C{flatten(gen)};
     otherwise, I'll yield the yielded item. Thus, I essentially
     "flatten" out a tree of iterators.

Modified: python-commons/trunk/src/commons/servers.py
===================================================================
--- python-commons/trunk/src/commons/servers.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/servers.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -85,7 +85,7 @@
 
     def __init__( self, timeout, do_catch ):
         """
-        @param timeout: The amount of time to spend in L{select.select}.
+        @param timeout: The amount of time to spend in C{select.select}.
         @type timeout: int
 
         @param do_catch: Whether exceptions should be swallowed in the loop.
@@ -143,7 +143,7 @@
     Base class for stoppable TCP stream servers.
 
     This class supports interrupts because it times out the blocking call to
-    L{select.select}, and checks whether the program is terminating.
+    C{select.select}, and checks whether the program is terminating.
     """
 
     allow_reuse_address = True

Modified: python-commons/trunk/src/commons/sqlhash.py
===================================================================
--- python-commons/trunk/src/commons/sqlhash.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/sqlhash.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -6,12 +6,11 @@
 used they are implicitly converted to the default encoding before being
 stored.
 
-Issues:
-
-    # ??? how to coordinate with whichdb
-    # ??? Size of text fields fixed or varchar (do we need blobs)
-    # ??? does default encoding affect str-->bytes or PySqlite3 always use UTF-8
-    # ??? if pure python overhead and pysqlite overhead is too high, rewrite in C
+@todo Issues:
+    - ??? how to coordinate with whichdb
+    - ??? Size of text fields fixed or varchar (do we need blobs)
+    - ??? does default encoding affect str-->bytes or PySqlite3 always use UTF-8
+    - ??? if pure python overhead and pysqlite overhead is too high, rewrite in C
 '''
 
 __all__ = ['error', 'open']

Modified: python-commons/trunk/src/commons/startup.py
===================================================================
--- python-commons/trunk/src/commons/startup.py	2009-06-03 17:13:32 UTC (rev 1449)
+++ python-commons/trunk/src/commons/startup.py	2009-06-03 17:37:26 UTC (rev 1450)
@@ -122,9 +122,9 @@
     """
     A feature-ful program starter. Configures logging and psyco, then
     runs the C{main} function defined in the caller's module, passing
-    in L{sys.argv}.  If the C{PYDBG} environment variable is set, then
-    runs C{main} in L{pdb}.  If the C{PYPROF} environment variable is
-    set, then runs C{main} in L{profile}.  Finally, exits with
+    in C{sys.argv}.  If the C{PYDBG} environment variable is set, then
+    runs C{main} in C{pdb}.  If the C{PYPROF} environment variable is
+    set, then runs C{main} in C{cProfile}.  Finally, exits with
     C{main}'s return value.
 
     For example::


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.