From: Mike Bayer Date: Fri, 1 Sep 2017 14:52:16 +0000 (-0400) Subject: include a note about the importance of type coerce for custom ops X-Git-Tag: rel_1_1_14~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5dc3eed55e9d1dd8d1f6535c2d693e17684380cc;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git include a note about the importance of type coerce for custom ops Change-Id: Ia7dab65523d6a34fcc92ee785ffe03f7e2a33cfd (cherry picked from commit 56845d8cc2678c0aefd889a7fc711150661cd8e8) --- diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index 1628987d3c..65f46e43ff 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -617,7 +617,7 @@ The above illustrates the SQL that's generated for an the ``||`` operator now compiles as MySQL's ``concat()`` function. If you have come across an operator which really isn't available, you can -always use the :meth:`.ColumnOperators.op` method; this generates whatever operator you need: +always use the :meth:`.Operators.op` method; this generates whatever operator you need: .. sourcecode:: pycon+sql @@ -628,7 +628,17 @@ This function can also be used to make bitwise operators explicit. For example:: somecolumn.op('&')(0xff) -is a bitwise AND of the value in `somecolumn`. +is a bitwise AND of the value in ``somecolumn``. + +When using :meth:`.Operators.op`, the return type of the expression may be important, +especialy when the operator is used in an expression that will be sent as a result +column. For this case, be sure to make the type explicit, if not what's +normally expected, using :func:`.type_coerce`:: + + from sqlalchemy import type_coerce + expr = type_coerce(somecolumn.op('-%>')('foo'), MySpecialType()) + stmt = select([expr]) + Operator Customization ----------------------