From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 8 Jan 2011 20:54:00 +0000 (-0500)
Subject: - add docstrings for _coerce_compared_value
X-Git-Tag: rel_0_6_6~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=94b5187b863217f95b8addb92bba9732f8ee9040;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add docstrings for _coerce_compared_value
---

diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py
index 1385d191f2..c4266089b2 100644
--- a/lib/sqlalchemy/types.py
+++ b/lib/sqlalchemy/types.py
@@ -117,6 +117,25 @@ class AbstractType(Visitable):
             return self.__class__
 
     def _coerce_compared_value(self, op, value):
+        """Suggest a type for a 'coerced' Python value in an expression.
+        
+        Given an operator and value, gives the type a chance
+        to return a type which the value should be coerced into.
+        
+        The default behavior here is conservative; if the right-hand
+        side is already coerced into a SQL type based on its 
+        Python type, it is usually left alone.
+        
+        End-user functionality extension here should generally be via
+        :class:`.TypeDecorator`, which provides more liberal behavior in that
+        it defaults to coercing the other side of the expression into this
+        type, thus applying special Python conversions above and beyond those
+        needed by the DBAPI to both ides. It also provides the public method
+        :meth:`.TypeDecorator.coerce_compared_value` which is intended for
+        end-user customization of this behavior.
+        
+        """
+
         _coerced_type = type_map.get(type(value), NULLTYPE)
         if _coerced_type is NULLTYPE or _coerced_type._type_affinity \
             is self._type_affinity:
@@ -480,6 +499,8 @@ class TypeDecorator(AbstractType):
         return self
 
     def _coerce_compared_value(self, op, value):
+        """See :meth:`.AbstractType._coerce_compared_value` for a description."""
+
         return self.coerce_compared_value(op, value)
 
     def copy(self):
@@ -1314,6 +1335,8 @@ class _Binary(TypeEngine):
     # end Py2K
 
     def _coerce_compared_value(self, op, value):
+        """See :meth:`.AbstractType._coerce_compared_value` for a description."""
+
         if isinstance(value, basestring):
             return self
         else:
@@ -1806,6 +1829,8 @@ class Interval(_DateAffinity, TypeDecorator):
         return Interval
 
     def _coerce_compared_value(self, op, value):
+        """See :meth:`.AbstractType._coerce_compared_value` for a description."""
+
         return self.impl._coerce_compared_value(op, value)