From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 24 May 2014 13:54:20 +0000 (-0400)
Subject: - hyperlink all the column operators listed in the ORM tutorial common filter operato... 
X-Git-Tag: rel_1_0_0b1~430
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=931685bac9161056cda3337ca2515ae9add236d8;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- hyperlink all the column operators listed in the ORM tutorial common filter operators section
- add language to MATCH explicitly stating this operator varies by backend and is not available
on SQLite, as the tutorial defaults to SQLite to start with, fix #3059
- on the actual match() documentation fix this up to be more accurate, list some example renderings
for different backends.  again mention SQLite not supported
---

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 1fc05c4f86..f90dc48d2e 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -744,19 +744,19 @@ Common Filter Operators
 Here's a rundown of some of the most common operators used in
 :func:`~sqlalchemy.orm.query.Query.filter`:
 
-* equals::
+* :meth:`equals <.ColumnOperators.__eq__>`::
 
     query.filter(User.name == 'ed')
 
-* not equals::
+* :meth:`not equals <.ColumnOperators.__ne__>`::
 
     query.filter(User.name != 'ed')
 
-* LIKE::
+* :meth:`LIKE <.ColumnOperators.like>`::
 
     query.filter(User.name.like('%ed%'))
 
-* IN::
+* :meth:`IN <.ColumnOperators.in_>`::
 
     query.filter(User.name.in_(['ed', 'wendy', 'jack']))
 
@@ -765,25 +765,25 @@ Here's a rundown of some of the most common operators used in
             session.query(User.name).filter(User.name.like('%ed%'))
     ))
 
-* NOT IN::
+* :meth:`NOT IN <.ColumnOperators.notin_>`::
 
     query.filter(~User.name.in_(['ed', 'wendy', 'jack']))
 
-* IS NULL::
+* :meth:`IS NULL <.ColumnOperators.is_>`::
 
     query.filter(User.name == None)
 
     # alternatively, if pep8/linters are a concern
     query.filter(User.name.is_(None))
 
-* IS NOT NULL::
+* :meth:`IS NOT NULL <.ColumnOperators.isnot>`::
 
     query.filter(User.name != None)
 
     # alternatively, if pep8/linters are a concern
     query.filter(User.name.isnot(None))
 
-* AND::
+* :func:`AND <.sql.expression.and_>`::
 
     # use and_()
     from sqlalchemy import and_
@@ -795,16 +795,20 @@ Here's a rundown of some of the most common operators used in
     # or chain multiple filter()/filter_by() calls
     query.filter(User.name == 'ed').filter(User.fullname == 'Ed Jones')
 
-* OR::
+* :func:`OR <.sql.expression.or_>`::
 
     from sqlalchemy import or_
     query.filter(or_(User.name == 'ed', User.name == 'wendy'))
 
-* match::
+* :meth:`MATCH <.ColumnOperators.match>`::
 
     query.filter(User.name.match('wendy'))
 
- The contents of the match parameter are database backend specific.
+ .. note::
+
+    :meth:`~.ColumnOperators.match` uses a database-specific ``MATCH``
+    or ``CONTAINS`` function; its behavior will vary by backend and is not
+    available on some backends such as SQLite.
 
 Returning Lists and Scalars
 ---------------------------
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index 402610fa55..9ad30e49e2 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -518,11 +518,17 @@ class ColumnOperators(Operators):
         return self.operate(contains_op, other, **kwargs)
 
     def match(self, other, **kwargs):
-        """Implements the 'match' operator.
+        """Implements a database-specific 'match' operator.
 
-        In a column context, this produces a MATCH clause, i.e.
-        ``MATCH '<other>'``.  The allowed contents of ``other``
-        are database backend specific.
+        :meth:`~.ColumnOperators.match` attempts to resolve to
+        a MATCH-like function or operator provided by the backend.
+        Examples include:
+
+        * Postgresql - renders ``x @@ to_tsquery(y)``
+        * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
+        * Oracle - renders ``CONTAINS(x, y)``
+        * other backends may provide special implementations;
+          some backends such as SQLite have no support.
 
         """
         return self.operate(match_op, other, **kwargs)