doc patch from [ticket:1651]

2 files changed, 46 insertions, 1 deletions

diff --git a/lib/sqlalchemy/databases/postgres.py b/lib/sqlalchemy/databases/postgres.py
index 51c7401fe..cc963a6fd 100644
--- a/lib/sqlalchemy/databases/postgres.py
+++ b/lib/sqlalchemy/databases/postgres.py
@@ -86,6 +86,15 @@ Transactions
 
 The PostgreSQL dialect fully supports SAVEPOINT and two-phase commit operations.
 
+Arrays
+------
+
+The PostgreSQL dialect supports ``ARRAY`` types with the :class:`~sqlalchemy.databases.postgres.PGArray` datatype::.
+E.g. to represent ``INTEGER[]``, use ``PGArray(Integer)``. This is also the
+correct type representation for ``INTEGER[][]`` and ``INTEGER[3][][4]``, so
+dimensionality and range limits do not matter. (In particular, do not
+try to represent ``INTEGER[][]`` with ``PGArray(PGArray(Integer))``.)
+
 
 """
 
@@ -210,9 +219,26 @@ class PGDoublePrecision(sqltypes.Float):
         return "DOUBLE PRECISION"
     
 class PGArray(sqltypes.MutableType, sqltypes.Concatenable, sqltypes.TypeEngine):
+    """PostgreSQL ARRAY type."""
     def __init__(self, item_type, mutable=True):
+        """Construct an ARRAY.
+
+        Example:
+
+          Column('myarray', PGArray(Integer))
+
+        Arguments are:
+
+        :param item_type: The data type of items of this array. Note that dimensionality is irrelevant here, so
+                          multi-dimensional arrays like `INTEGER[][]`, are constructed as `PGArray(Integer)`, not as
+                          `PGArray(PGArray(Integer))` or such. The type mapping figures out on the fly
+        :param mutable:   Defaults to True: specify whether lists passed to this class should be considered mutable.
+                          If so, then they are shallow-copied.
+        """
         if isinstance(item_type, type):
             item_type = item_type()
+        if isinstance(item_type, PGArray):
+            raise ValueError('Do not nest PGArray types; PGArray(basetype) handles multi-dimensional arrays of basetype')
         self.item_type = item_type
         self.mutable = mutable
 
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 69b8303f6..37ad7977f 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -132,7 +132,7 @@ class Dialect(object):
         from generic to database-specific.
 
         Subclasses will usually use the
-        :func:`~sqlalchemy.types.adapt_type` method in the types module to
+        :func:`~sqlalchemy.types.adapt_type()` function in the types module to
         make this job easy.
         """
 
@@ -399,6 +399,17 @@ class ExecutionContext(object):
 
         raise NotImplementedError()
 
+    def get_rowcount(self):
+        """Return the number of rows produced (by a SELECT query)
+        or affected (by an INSERT/UPDATE/DELETE statement).
+
+        Note that this row count may not be properly implemented in some dialects;
+        this is indicated by :meth:`supports_sane_rowcount` and
+        :meth:`supports_sane_multi_rowcount`
+        """
+
+        raise NotImplementedError()
+
 
 class Compiled(object):
     """Represent a compiled SQL expression.
@@ -1416,6 +1427,14 @@ class ResultProxy(object):
     
     @property
     def rowcount(self):
+        """Return ``get_rowcount()`` from the underlying ExecutionContext.
+
+        See ExecutionContext for details.
+
+        Note that this row count may not be properly implemented in some dialects;
+        this is indicated by :meth:`~sqlalchemy.engine.base.ResultProxy.supports_sane_rowcount`
+        and :meth:`~sqlalchemy.engine.base.ResultProxy.supports_sane_multi_rowcount`
+        """
         if self._rowcount is None:
             return self.context.get_rowcount()
         else: