Clean up API documentation in several places

oztc · Feb 4, 2012 · 15282bb · 15282bb
1 parent 2f3ce70
commit 15282bb
Show file tree

Hide file tree

Showing 11 changed files with 65 additions and 101 deletions.
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -15,5 +15,4 @@ Pycassa Modules
    pycassa/batch
    pycassa/types
    pycassa/util
-   pycassa/connection
    pycassa/logging/pycassa_logger
diff --git a/doc/api/pycassa/connection.rst b/doc/api/pycassa/connection.rst
diff --git a/doc/api/pycassa/types.rst b/doc/api/pycassa/types.rst
@@ -1,5 +1,17 @@
-:mod:`pycassa.types` -- Column Types for ColumnFamilyMaps
-=========================================================
+:mod:`pycassa.types` -- Data Type Descriptions
+==============================================
 
 .. automodule:: pycassa.types
-    :members:
+
+.. autoclass:: pycassa.types.CassandraType(reversed=False, default=None)
+.. autoclass:: pycassa.types.BytesType()
+.. autoclass:: pycassa.types.AsciiType()
+.. autoclass:: pycassa.types.UTF8Type()
+.. autoclass:: pycassa.types.LongType()
+.. autoclass:: pycassa.types.IntegerType()
+.. autoclass:: pycassa.types.DoubleType()
+.. autoclass:: pycassa.types.FloatType()
+.. autoclass:: pycassa.types.DateType()
+.. autoclass:: pycassa.types.TimeUUIDType()
+.. autoclass:: pycassa.types.LexicalUUIDType()
+.. autoclass:: pycassa.types.CompositeType(*components)
diff --git a/doc/conf.py b/doc/conf.py
@@ -13,8 +13,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
-              'sphinx.ext.todo', 'doc.sphinxtogithub']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'doc.sphinxtogithub']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -62,7 +61,7 @@
 #modindex_common_prefix = []
 
 # -- Options for extensions ----------------------------------------------------
-autoclass_content = 'init'
+autoclass_content = 'both'
 
 # -- Options for HTML output ---------------------------------------------------
 

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,7 +1,6 @@
 pycassa |release| Documentation
 ===============================
-
-**pycassa** is a Python client for
+pycassa is a Python client for
 `Apache Cassandra <http://cassandra.apache.org>`_.
 The latest release of pycassa is fully compatible with Cassandra 0.8 and
 1.0, and is compatible with the data API of Cassandra 0.7.
@@ -64,13 +63,6 @@ following command from the root directory of pycassa:
 
   $ python setup.py doc
 
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
 .. toctree::
    :hidden:
 

diff --git a/pycassa/__init__.py b/pycassa/__init__.py
@@ -1,6 +1,6 @@
 from pycassa.columnfamily import *
 from pycassa.columnfamilymap import *
-from pycassa.types import *
+#from pycassa.types import *
 from pycassa.index import *
 from pycassa.pool import *
 from pycassa.system_manager import *

diff --git a/pycassa/batch.py b/pycassa/batch.py
@@ -73,18 +73,15 @@ class Mutator(object):
 
     Queues insert/update/remove operations and executes them when the queue
     is full or `send` is called explicitly.
-
     """
 
     def __init__(self, pool, queue_size=100, write_consistency_level=None, allow_retries=True):
-        """Creates a new Mutator object.
-
+        """
         `pool` is the :class:`~pycassa.pool.ConnectionPool` that will be used
         for operations.
 
         After `queue_size` operations, :meth:`send()` will be executed
         automatically.  Use 0 to disable automatic sends.
-
         """
         self._buffer = []
         self._lock = threading.RLock()
@@ -176,16 +173,13 @@ def remove(self, column_family, key, columns=None, super_column=None, timestamp=
 class CfMutator(Mutator):
     """
     A :class:`~pycassa.batch.Mutator` that deals only with one column family.
-
     """
 
     def __init__(self, column_family, queue_size=100, write_consistency_level=None,
                  allow_retries=True):
-        """ A :class:`~pycassa.batch.Mutator` that deals only with one column family.
-
+        """
         `column_family` is the :class:`~pycassa.columnfamily.ColumnFamily`
         that all operations will be executed on.
-
         """
         wcl = write_consistency_level or column_family.write_consistency_level
         super(CfMutator, self).__init__(column_family.pool, queue_size=queue_size,

diff --git a/pycassa/columnfamily.py b/pycassa/columnfamily.py
@@ -58,7 +58,11 @@ def gm_timestamp():
     return int(time.time() * 1e6)
 
 class ColumnFamily(object):
-    """ An abstraction of a Cassandra column family or super column family. """
+    """
+    An abstraction of a Cassandra column family or super column family.
+    Operations on this, such as :meth:`get` or :meth:`insert` will get data from or
+    insert data into the corresponding Cassandra column family.
+    """
 
     buffer_size = 1024
     """ When calling :meth:`get_range()` or :meth:`get_indexed_slices()`,
@@ -116,6 +120,9 @@ class ColumnFamily(object):
     """ Whether to retry failed counter mutations. Counter mutations are
     not idempotent so retrying could result in double counting.
     By default, this is :const:`False`.
+
+    .. versionadded:: 1.5.0
+
     """
 
     def _set_column_name_class(self, t):
@@ -249,15 +256,13 @@ def _get_key_validation_class(self):
 
     def __init__(self, pool, column_family, **kwargs):
         """
-        An abstraction of a Cassandra column family or super column family.
-        Operations on this, such as :meth:`get` or :meth:`insert` will get data from or
-        insert data into the corresponding Cassandra column family with
-        name `column_family`.
-
         `pool` is a :class:`~pycassa.pool.ConnectionPool` that the column
-        family will use for all operations.  A connection is drawn from the
-        pool before each operations and is returned afterwards.  Note that
-        the keyspace to be used is determined by the pool.
+        family will use for all operations. A connection is drawn from the
+        pool before each operations and is returned afterwards.
+
+        `column_family` should be the name of the column family that you
+        want to use in Cassandra. Note that the keyspace to be used is
+        determined by the pool.
         """
 
         self.pool = pool

diff --git a/pycassa/columnfamilymap.py b/pycassa/columnfamilymap.py
@@ -23,14 +23,14 @@ def create_instance(cls, **kwargs):
     return instance
 
 class ColumnFamilyMap(ColumnFamily):
-    """ Maps an existing class to a column family. """
+    """
+    Maps an existing class to a column family.  Class fields become columns,
+    and instances of that class can be represented as rows in standard column
+    families or super columns in super column families.
+    """
 
     def __init__(self, cls, pool, column_family, raw_columns=False, **kwargs):
         """
-        Maps an existing class to a column family.  Class fields become columns,
-        and instances of that class can be represented as rows in standard column
-        families or super columns in super column families.
-
         Instances of `cls` are returned from :meth:`get()`, :meth:`multiget()`,
         :meth:`get_range()` and :meth:`get_indexed_slices()`.
 
@@ -41,7 +41,6 @@ def __init__(self, cls, pool, column_family, raw_columns=False, **kwargs):
 
         If `raw_columns` is ``True``, all columns will be fetched into the
         `raw_columns` field in requests.
-
         """
         ColumnFamily.__init__(self, pool, column_family, **kwargs)
 

diff --git a/pycassa/pool.py b/pycassa/pool.py
@@ -21,8 +21,12 @@
 
 class ConnectionWrapper(Connection):
     """
-    A wrapper class for :class:`Connection`s that adds pooling functionality.
+    Creates a wrapper for a :class:`~.pycassa.connection.Connection`
+    object, adding pooling related functionality while still allowing
+    access to the thrift API calls.
 
+    These should not be created directly, only obtained through
+    Pool's :meth:`~.ConnectionPool.get()` method.
     """
 
     # These mark the state of the connection so that we can
@@ -33,15 +37,6 @@ class ConnectionWrapper(Connection):
     _DISPOSED = 2
 
     def __init__(self, pool, max_retries, *args, **kwargs):
-        """
-        Creates a wrapper for a :class:`~.pycassa.connection.Connection`
-        object, adding pooling related functionality while still allowing
-        access to the thrift API calls.
-
-        These should not be created directly, only obtained through
-        Pool's :meth:`~.ConnectionPool.get()` method.
-
-        """
         self._pool = pool
         self._retry_count = 0
         self.max_retries = max_retries
@@ -252,8 +247,6 @@ def __init__(self, keyspace,
                  prefill=True,
                  **kwargs):
         """
-        Constructs a pool that maintains a queue of open connections.
-
         All connections in the pool will be opened to `keyspace`.
 
         `server_list` is a sequence of servers in the form ``"host:port"`` that

diff --git a/pycassa/types.py b/pycassa/types.py
@@ -11,38 +11,34 @@
 
     >>> class IntString(pycassa.types.CassandraType):
     ...
-    ...     @staticmethod
-    ...     def pack(intval):
-    ...         return str(intval)
+    ...    @staticmethod
+    ...    def pack(intval):
+    ...        return str(intval)
     ...
-    ...     @staticmethod
-    ...     def unpack(strval):
-    ...         return int(strval)
+    ...    @staticmethod
+    ...    def unpack(strval):
+    ...        return int(strval)
 
 """
 
 import pycassa.marshal as marshal
 
 class CassandraType(object):
+    """
+    A data type that Cassandra is aware of and knows
+    how to validate and sort. All of the other classes in this
+    module are subclasses of this class.
 
-    def __init__(self, reversed=False, default=None):
-        """
-        A data type that Cassandra is aware of and knows
-        how to validate and sort.
-
-        If `reversed` is true and this is used as a column comparator,
-        the columns will be sorted in reverse order.
-
-        This is also used to specify fields to be persisted when
-        a class is used with :class:`~.ColumnFamilyMap`.
+    If `reversed` is true and this is used as a column comparator,
+    the columns will be sorted in reverse order.
 
-        The `default` parameter only applies to use of this
-        with ColumnFamilyMap, where `default` is used if a row
-        does not contain a column corresponding to this item.
 
-        .. versionadded:: 1.2.0
+    The `default` parameter only applies to use of this
+    with ColumnFamilyMap, where `default` is used if a row
+    does not contain a column corresponding to this item.
+    """
 
-        """
+    def __init__(self, reversed=False, default=None):
         self.reversed = reversed
         self.default = default
         if not hasattr(self.__class__, 'pack'):
@@ -96,40 +92,22 @@ class CounterColumnType(CassandraType):
     pass
 
 class DoubleType(CassandraType):
-    """
-    Stores data as an 8 byte double.
-
-    .. versionadded:: 1.2.0
-
-    """
+    """ Stores data as an 8 byte double """
     pass
 
 class FloatType(CassandraType):
-    """
-    Stores data as an 4 byte float.
-
-    .. versionadded:: 1.2.0
-
-    """
+    """ Stores data as an 4 byte float """
     pass
 
 class BooleanType(CassandraType):
-    """
-    Stores data as a 1 byte boolean.
-
-    .. versionadded:: 1.2.0
-
-    """
+    """ Stores data as a 1 byte boolean """
     pass
 
 class DateType(CassandraType):
     """
     An 8 byte timestamp. This will be returned
     as a :class:`datetime.datetime` instance by pycassa. Either
     :class:`datetime` instances or timestamps will be accepted.
-
-    .. versionadded:: 1.2.0
-
     """
     pass
 
@@ -145,8 +123,6 @@ class CompositeType(CassandraType):
 
     .. seealso:: :ref:`composite-types`
 
-    .. versionadded:: 1.2.0
-
     """
 
     def __init__(self, *components):