Use .expression accessor for hybrid example

hybrids since 1.1 use InstrumentedAttribute at the expression
level, so this doc needed to illustrate how to get at the
SQL expression.  Also added a docstring for
QueryableAttribute.expression.

Fixes: #5773
Change-Id: I4941d245ec947999abfa8e13f047e06a0bd47e5b
(cherry picked from commit 688b4ca6a7f2e32c580d616c6dea1e68b7398fd2)

diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py
index c654313cf14221cdd61214f61d0a4b300baac5c9..578b7c2731daa76690ae3ecc44305d296a0fcd51 100644 (file)
--- a/lib/sqlalchemy/ext/hybrid.py
+++ b/lib/sqlalchemy/ext/hybrid.py
@@ -64,9 +64,10 @@ mechanics::
 When dealing with the ``Interval`` class itself, the :class:`.hybrid_property`
 descriptor evaluates the function body given the ``Interval`` class as
 the argument, which when evaluated with SQLAlchemy expression mechanics
+(here using the :attr:`.QueryableAttribute.expression` accessor)
 returns a new SQL expression::
 
-    >>> print(Interval.length)
+    >>> print(Interval.length.expression)
     interval."end" - interval.start
 
     >>> print(Session().query(Interval).filter(Interval.length > 10))

diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 15476a2c46de4b6290ce89d4834ba0208f756545..22aecc844a1d96659548906252d31fe3443ef4f5 100644 (file)
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -176,6 +176,13 @@ class QueryableAttribute(
 
     @property
     def expression(self):
+        """The SQL expression object represented by this
+        :class:`.QueryableAttribute`.
+
+        This will typically be an instance of a :class:`.ColumnElement`
+        subclass representing a column expression.
+
+        """
         return self.comparator.__clause_element__()
 
     def __clause_element__(self):