From 943259264f2e8aea2ab40d52ba5f3235269f9c09 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 17 Jan 2010 18:00:01 +0000
Subject: [PATCH] doc updates partially from [ticket:1651]

---
 doc/build/reference/dialects/postgresql.rst | 48 +++++++++++++++++++++
 lib/sqlalchemy/dialects/postgresql/base.py  | 25 +++++++++--
 lib/sqlalchemy/engine/base.py               | 26 ++++++++---
 3 files changed, 89 insertions(+), 10 deletions(-)

diff --git a/doc/build/reference/dialects/postgresql.rst b/doc/build/reference/dialects/postgresql.rst
index 7e00645d82..67a6c1e0bb 100644
--- a/doc/build/reference/dialects/postgresql.rst
+++ b/doc/build/reference/dialects/postgresql.rst
@@ -3,6 +3,54 @@ PostgreSQL
 
 .. automodule:: sqlalchemy.dialects.postgresql.base
 
+PostgresSQL Column Types
+------------------------
+
+.. autoclass:: ARRAY
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: BIT
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: BYTEA
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: CIDR
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: DOUBLE_PRECISION
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: ENUM
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: INET
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: INTERVAL
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: MACADDR
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: REAL
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: UUID
+    :members: __init__
+    :show-inheritance:
+
+
 psycopg2 Notes
 --------------
 
diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 00089815d7..308e23bae8 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -65,8 +65,6 @@ option to the Index constructor::
 
   Index('my_index', my_table.c.id, postgresql_where=tbl.c.value > 10)
 
-
-
 """
 
 import re
@@ -129,6 +127,27 @@ class ARRAY(sqltypes.MutableType, sqltypes.Concatenable, sqltypes.TypeEngine):
     __visit_name__ = 'ARRAY'
     
     def __init__(self, item_type, mutable=True):
+        """Construct an ARRAY.
+
+        E.g.::
+
+          Column('myarray', ARRAY(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
+          ``ARRAY(Integer)``, not as ``ARRAY(ARRAY(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, generic copy operations (typically used by the ORM) will
+          shallow-copy values.
+          
+        """
+        if isinstance(item_type, ARRAY):
+            raise ValueError("Do not nest ARRAY types; ARRAY(basetype) "
+                            "handles multi-dimensional arrays of basetype")
         if isinstance(item_type, type):
             item_type = item_type()
         self.item_type = item_type
@@ -903,7 +922,7 @@ class PGDialect(default.DefaultDialect):
             if coltype:
                 coltype = coltype(*args, **kwargs)
                 if is_array:
-                    coltype = PGArray(coltype)
+                    coltype = ARRAY(coltype)
             else:
                 util.warn("Did not recognize type '%s' of column '%s'" %
                           (attype, name))
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 564fa50a94..2210ba4083 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -173,7 +173,7 @@ class Dialect(object):
         """Transform a generic type to a dialect-specific type.
 
         Dialect classes 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.
 
         The returned result is cached *per dialect class* so can
@@ -581,6 +581,19 @@ 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 the 
+        ``supports_sane_rowcount`` and ``supports_sane_multi_rowcount``
+        dialect attributes.
+        
+        """
+
+        raise NotImplementedError()
+
 
 class Compiled(object):
     """Represent a compiled SQL or DDL expression.
@@ -1767,13 +1780,12 @@ class ResultProxy(object):
         uses and is not intended to provide the number of rows
         present from a SELECT.
         
-        Additionally, this value is only meaningful if the
-        dialect's supports_sane_rowcount flag is True for
-        single-parameter executions, or supports_sane_multi_rowcount
-        is true for multiple parameter executions - otherwise
-        results are undefined.
+        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()`.
         
-        rowcount may not work at this time for a statement
+        ``rowcount()`` also may not work at this time for a statement
         that uses ``returning()``.
         
         """
-- 
2.47.3