Merge lp:~cjwatson/storm/docstring-syntax into lp:storm

[Colin Watson]

Improve various docstrings, mainly fixing reST/epytext syntax.

[Ioana Lasc (ilasc)]

review: Approve

[Kristian Glass (doismellburning)]

review: Approve

=== modified file 'storm/cache.py'
--- storm/cache.py	2019-08-11 09:48:05 +0000
+++ storm/cache.py	2020-05-26 10:38:54 +0000
@@ -11,7 +11,7 @@
     This prevents recently used objects from being deallocated by Python
     even if the user isn't holding any strong references to it.  It does
     that by holding strong references to the objects referenced by the
-    last C{N} C{obj_info}s added to it (where C{N} is the cache size).
+    last C{N} C{obj_info}\ s added to it (where C{N} is the cache size).
     """
 
     def __init__(self, size=1000):
@@ -54,7 +54,7 @@
     def set_size(self, size):
         """Set the maximum number of objects that may be held in this cache.
 
-        If the size is reduced, older C{obj_info}s may be dropped from
+        If the size is reduced, older C{obj_info}\ s may be dropped from
         the cache to respect the new size.
         """
         if size == 0:
@@ -66,7 +66,7 @@
         self._size = size
 
     def get_cached(self):
-        """Return an ordered list of the currently cached C{obj_info}s.
+        """Return an ordered list of the currently cached C{obj_info}\ s.
 
         The most recently added objects come first in the list.
         """
@@ -103,7 +103,7 @@
         self._old_cache = {}
 
     def clear(self):
-        """See `storm.store.Cache.clear`.
+        """See L{Cache.clear}.
 
         Clears both the primary and the secondary caches.
         """
@@ -125,20 +125,20 @@
         self._new_cache.clear()
 
     def add(self, obj_info):
-        """See `storm.store.Cache.add`."""
+        """See L{Cache.add}."""
         if self._size != 0 and obj_info not in self._new_cache:
             if len(self._new_cache) >= self._size:
                 self._bump_generation()
             self._new_cache[obj_info] = obj_info.get_obj()
 
     def remove(self, obj_info):
-        """See `storm.store.Cache.remove`."""
+        """See L{Cache.remove}."""
         in_new_cache = self._new_cache.pop(obj_info, None) is not None
         in_old_cache = self._old_cache.pop(obj_info, None) is not None
         return in_new_cache or in_old_cache
 
     def set_size(self, size):
-        """See `storm.store.Cache.set_size`.
+        """See L{Cache.set_size}.
 
         After calling this, the cache may still contain more than `size`
         objects, but no more than twice that number.
@@ -152,7 +152,7 @@
         self._old_cache.clear()
 
     def get_cached(self):
-        """See `storm.store.Cache.get_cached`.
+        """See L{Cache.get_cached}.
 
         The result is a loosely-ordered list.  Any object in the primary
         generation comes before any object that is only in the secondary

=== modified file 'storm/database.py'
--- storm/database.py	2019-09-27 19:22:54 +0000
+++ storm/database.py	2020-05-26 10:38:54 +0000
@@ -377,7 +377,7 @@
             self._check_disconnect(trace, "connection_commit", self, xid)
 
     def recover(self):
-        """Return a list of L{Xid}s representing pending transactions."""
+        """Return a list of L{Xid}\ s representing pending transactions."""
         self._ensure_connected()
         raw_xids = self._check_disconnect(self._raw_connection.tpc_recover)
         return [Xid(raw_xid[0], raw_xid[1], raw_xid[2])
@@ -422,8 +422,9 @@
         It is acceptable to override this method in subclasses, but it
         is not intended to be used externally.
 
-        This delegates conversion to any L{Variable}s in the parameter
-        list, and passes through all other values untouched.
+        This delegates conversion to any
+        L{Variable <storm.variable.Variable>}\ s in the parameter list, and
+        passes through all other values untouched.
         """
         for param in params:
             if isinstance(param, Variable):
@@ -671,13 +672,23 @@
     """Create a database instance.
 
     @param uri: An URI instance, or a string describing the URI. Some examples:
-        - "sqlite:" An in memory sqlite database.
-        - "sqlite:example.db" A SQLite database called example.db
-        - "postgres:test" The database 'test' from the local postgres server.
-        - "postgres://user:password@host/test" The database test on machine host
-          with supplied user credentials, using postgres.
-        - "anything:..." Where 'anything' has previously been registered
-          with L{register_scheme}.
+
+    "sqlite:"
+        An in memory sqlite database.
+
+    "sqlite:example.db"
+        A SQLite database called example.db
+
+    "postgres:test"
+        The database 'test' from the local postgres server.
+
+    "postgres://user:password@host/test"
+        The database test on machine host with supplied user credentials,
+        using postgres.
+
+    "anything:..."
+        Where 'anything' has previously been registered with
+        L{register_scheme}.
     """
     if isinstance(uri, six.string_types):
         uri = URI(uri)

=== modified file 'storm/info.py'
--- storm/info.py	2019-09-17 09:35:10 +0000
+++ storm/info.py	2020-05-26 10:38:54 +0000
@@ -59,7 +59,7 @@
 
 
 class ClassInfo(dict):
-    """Persistent storm-related information of a class.
+    """Persistent Storm-related information of a class.
 
     The following attributes are defined:
 

=== modified file 'storm/references.py'
--- storm/references.py	2020-03-18 16:50:12 +0000
+++ storm/references.py	2020-05-26 10:38:54 +0000
@@ -408,8 +408,8 @@
           bar = Reference(bar_id, Bar.id)
           bar_title = Proxy(bar, Bar.title)
 
-    For most uses, Foo.bar_title should behave as if it were
-    a native property of Foo.
+    For most uses, C{Foo.bar_title} should behave as if it were
+    a native property of C{Foo}.
     """
 
     class RemoteProp(object):

=== modified file 'storm/store.py'
--- storm/store.py	2020-04-25 16:02:54 +0000
+++ storm/store.py	2020-05-26 10:38:54 +0000
@@ -105,7 +105,7 @@
     def execute(self, statement, params=None, noresult=False):
         """Execute a basic query.
 
-        This is just like L{storm.database.Database.execute}, except
+        This is just like L{storm.database.Connection.execute}, except
         that a flush is performed first.
         """
         if self._implicit_flush_block_count == 0:
@@ -119,16 +119,16 @@
     def begin(self, xid):
         """Start a new two-phase transaction.
 
-        @param xid: A L{Xid} instance holding identification data for the
-            new transaction.
+        @param xid: A L{Xid <storm.xid.Xid>} instance holding identification
+            data for the new transaction.
         """
         self._connection.begin(xid)
 
     def prepare(self):
         """Prepare a two-phase transaction for the final commit.
 
-        @note: It must be call inside a two-phase transaction started
-            with begin().
+        @note: It must be called inside a two-phase transaction started
+            with L{begin}.
         """
         self._connection.prepare()
 
@@ -627,7 +627,7 @@
         """Fill missing values in variables of the given obj_info.
 
         This method will verify which values are unset in obj_info,
-        and set them to AutoReload, or if it's part of the primary
+        and set them to L{AutoReload}, or if it's part of the primary
         key, query the database for the actual values.
 
         @param obj_info: ObjectInfo to have its values filled.
@@ -889,7 +889,7 @@
 
         This method is hooked into the obj_info to resolve variables
         set to lazy values when they're accessed.  It will first flush
-        the store, and then set all variables set to AutoReload to
+        the store, and then set all variables set to L{AutoReload} to
         their database values.
         """
         if lazy_value is not AutoReload and not isinstance(lazy_value, Expr):
@@ -1083,7 +1083,7 @@
         """Return a single item from the result set.
 
         @return: An arbitrary object or C{None} if one isn't available.
-        @seealso: one(), first(), and last().
+        @see: L{one}, L{first}, and L{last}.
         """
         select = self._get_select()
         select.limit = 1
@@ -1112,7 +1112,7 @@
 
         @raises UnorderedError: Raised if the result set isn't ordered.
         @return: The first object or C{None} if one isn't available.
-        @seealso: last(), one(), and any().
+        @see: L{last}, L{one}, and L{any}.
         """
         if self._order_by is Undef:
             raise UnorderedError("Can't use first() on unordered result set")
@@ -1124,7 +1124,7 @@
         @raises FeatureError: Raised if the result set has a C{LIMIT} set.
         @raises UnorderedError: Raised if the result set isn't ordered.
         @return: The last object or C{None} if one isn't available.
-        @seealso: first(), one(), and any().
+        @see: L{first}, L{one}, and L{any}.
         """
         if self._order_by is Undef:
             raise UnorderedError("Can't use last() on unordered result set")
@@ -1154,7 +1154,7 @@
         @raises NotOneError: Raised if the result set contains more than one
             item.
         @return: The object or C{None} if one isn't available.
-        @seealso: first(), one(), and any().
+        @see: L{first}, L{last}, and L{any}.
         """
         select = self._get_select()
         # limit could be 1 due to slicing, for instance.
@@ -1860,7 +1860,7 @@
 
 class block_access(object):
     """
-    Context manager blocks database access by one or more L{Store}s in the
+    Context manager blocks database access by one or more L{Store}\ s in the
     managed scope.
     """
 

=== modified file 'storm/testing.py'
--- storm/testing.py	2019-06-05 11:41:07 +0000
+++ storm/testing.py	2020-05-26 10:38:54 +0000
@@ -8,7 +8,7 @@
 class CaptureTracer(BaseStatementTracer, Fixture):
     """Trace SQL statements appending them to a C{list}.
 
-    Example:
+    Example::
 
         with CaptureTracer() as tracer:
             # Run queries

=== modified file 'storm/tracer.py'
--- storm/tracer.py	2019-08-11 16:57:24 +0000
+++ storm/tracer.py	2020-05-26 10:38:54 +0000
@@ -94,7 +94,7 @@
 
     def connection_raw_execute_error(self, connection, raw_cursor,
                                      statement, params, error):
-        """Raise TimeoutError if the given error was a timeout issue.
+        """Raise L{TimeoutError} if the given error was a timeout issue.
 
         Must be specialized in the backend.
         """
@@ -102,7 +102,7 @@
                                   "implemented" % self.__class__.__name__)
 
     def connection_commit(self, connection, xid=None):
-        """Reset Connection._timeout_tracer_remaining_time.
+        """Reset C{Connection._timeout_tracer_remaining_time}.
 
         @param connection: The L{Connection} to the database.
         @param xid: Optionally the L{Xid} of a previously prepared
@@ -111,7 +111,7 @@
         self._reset_timeout_tracer_remaining_time(connection)
 
     def connection_rollback(self, connection, xid=None):
-        """Reset Connection._timeout_tracer_remaining_time.
+        """Reset C{Connection._timeout_tracer_remaining_time}.
 
         @param connection: The L{Connection} to the database.
         @param xid: Optionally the L{Xid} of a previously prepared
@@ -197,7 +197,7 @@
     """Storm tracer class to insert executed statements into a L{Timeline}.
 
     For more information on timelines see the module at
-    http://pypi.python.org/pypi/timeline.
+    U{https://pypi.org/project/timeline/}.
 
     The timeline to use is obtained by calling the timeline_factory supplied to
     the constructor. This simple function takes no parameters and returns a

=== modified file 'storm/tz.py'
--- storm/tz.py	2019-09-17 09:35:10 +0000
+++ storm/tz.py	2020-05-26 10:38:54 +0000
@@ -1,6 +1,6 @@
+# Copyright (c) 2003-2005  Gustavo Niemeyer <[e-mail]>
+
 """
-Copyright (c) 2003-2005  Gustavo Niemeyer <[e-mail]>
-
 This module offers extensions to the standard python 2.3+
 datetime module.
 """

=== modified file 'storm/variables.py'
--- storm/variables.py	2020-02-10 15:30:23 +0000
+++ storm/variables.py	2020-05-26 10:38:54 +0000
@@ -133,7 +133,7 @@
         @type column: L{storm.expr.Column}
         @param column: The column that this variable represents. It's
             used for reporting better error messages.
-        @type event: L{EventSystem}
+        @type event: L{storm.event.EventSystem}
         @param event: The event system to broadcast messages with. If
             not specified, then no events will be broadcast.
         """

=== modified file 'storm/wsgi.py'
--- storm/wsgi.py	2019-06-05 11:41:07 +0000
+++ storm/wsgi.py	2020-05-26 10:38:54 +0000
@@ -29,23 +29,23 @@
 __all__ = ['make_app']
 
 def make_app(app):
-    """Capture the per-request timeline object needed for storm tracing.
+    """Capture the per-request timeline object needed for Storm tracing.
 
-    To use firstly make your app and then wrap it with this make_app::
+    To use firstly make your app and then wrap it with this C{make_app}::
 
        >>> app, find_timeline = make_app(app)
 
-    Then wrap the returned app with the timeline app (or anything that sets
-    environ['timeline.timeline'])::
+    Then wrap the returned app with the C{timeline} app (or anything that
+    sets C{environ['timeline.timeline']})::
 
        >>> app = timeline.wsgi.make_app(app)
 
-    Finally install a timeline tracer to capture storm queries::
+    Finally install a timeline tracer to capture Storm queries::
 
        >>> install_tracer(TimelineTracer(find_timeline))
 
     @return: A wrapped WSGI app and a timeline factory function for use with
-    TimelineTracer.
+        L{TimelineTracer <storm.tracer.TimelineTracer>}.
     """
     timeline_map = threading.local()
     def wrapper(environ, start_response):