- update docs for Numeric/Float, in particular warn against using mismatched

types (e.g. [ticket:2916])

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 0cc90f26b882bfbf7df7d8cacfeb2f5c6161e1db..d779caaeac1ce681642a05b6e155cce9c4bb1edd 100644 (file)
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -407,44 +407,41 @@ class BigInteger(Integer):
 
 
 class Numeric(_DateAffinity, TypeEngine):
-    """A type for fixed precision numbers.
+    """A type for fixed precision numbers, such as ``NUMERIC`` or ``DECIMAL``.
 
-    Typically generates DECIMAL or NUMERIC.  Returns
-    ``decimal.Decimal`` objects by default, applying
-    conversion as needed.
+    This type returns Python ``decimal.Decimal`` objects by default, unless the
+    :paramref:`.Numeric.asdecimal` flag is set to False, in which case they
+    are coerced to Python ``float`` objects.
 
     .. note::
 
-       The `cdecimal <http://pypi.python.org/pypi/cdecimal/>`_ library
-       is a high performing alternative to Python's built-in
-       ``decimal.Decimal`` type, which performs very poorly in high volume
-       situations. SQLAlchemy 0.7 is tested against ``cdecimal`` and supports
-       it fully. The type is not necessarily supported by DBAPI
-       implementations however, most of which contain an import for plain
-       ``decimal`` in their source code, even though some such as psycopg2
-       provide hooks for alternate adapters. SQLAlchemy imports ``decimal``
-       globally as well.  The most straightforward and
-       foolproof way to use "cdecimal" given current DBAPI and Python support
-       is to patch it directly into sys.modules before anything else is
-       imported::
+        The :class:`.Numeric` type is designed to receive data from a database
+        type that is explicitly known to be a decimal type
+        (e.g. ``DECIMAL``, ``NUMERIC``, others) and not a floating point
+        type (e.g. ``FLOAT``, ``REAL``, others).
+        If the database column on the server is in fact a floating-point type
+        type, such as ``FLOAT`` or ``REAL``, use the :class:`.Float`
+        type or a subclass, otherwise numeric coercion between ``float``/``Decimal``
+        may or may not function as expected.
+
+    .. note::
+
+       The Python ``decimal.Decimal`` class is generally slow
+       performing; cPython 3.3 has now switched to use the `cdecimal
+       <http://pypi.python.org/pypi/cdecimal/>`_ library natively. For
+       older Python versions, the ``cdecimal`` library can be patched
+       into any application where it will replace the ``decimal``
+       library fully, however this needs to be applied globally and
+       before any other modules have been imported, as follows::
 
            import sys
            import cdecimal
            sys.modules["decimal"] = cdecimal
 
-       While the global patch is a little ugly, it's particularly
-       important to use just one decimal library at a time since
-       Python Decimal and cdecimal Decimal objects
-       are not currently compatible *with each other*::
-
-           >>> import cdecimal
-           >>> import decimal
-           >>> decimal.Decimal("10") == cdecimal.Decimal("10")
-           False
-
-       SQLAlchemy will provide more natural support of
-       cdecimal if and when it becomes a standard part of Python
-       installations and is supported by all DBAPIs.
+       Note that the ``cdecimal`` and ``decimal`` libraries are **not
+       compatible with each other**, so patching ``cdecimal`` at the
+       global level is the only way it can be used effectively with
+       various DBAPIs that hardcode to import the ``decimal`` library.
 
     """
 
@@ -585,10 +582,22 @@ class Numeric(_DateAffinity, TypeEngine):
 
 
 class Float(Numeric):
-    """A type for ``float`` numbers.
+    """Type representing floating point types, such as ``FLOAT`` or ``REAL``.
+
+    This type returns Python ``float`` objects by default, unless the
+    :paramref:`.Float.asdecimal` flag is set to True, in which case they
+    are coerced to ``decimal.Decimal`` objects.
+
+    .. note::
 
-    Returns Python ``float`` objects by default, applying
-    conversion as needed.
+        The :class:`.Float` type is designed to receive data from a database
+        type that is explicitly known to be a floating point type
+        (e.g. ``FLOAT``, ``REAL``, others)
+        and not a decimal type (e.g. ``DECIMAL``, ``NUMERIC``, others).
+        If the database column on the server is in fact a Numeric
+        type, such as ``DECIMAL`` or ``NUMERIC``, use the :class:`.Numeric`
+        type or a subclass, otherwise numeric coercion between ``float``/``Decimal``
+        may or may not function as expected.
 
     """