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

diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py
index 83562502ab8e82dd7275185013248c6600b98d01..8679d907a6e72cdf383b685aa1e5cbdfef22a26a 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 4280cb76e6ecd09a2bd97353bd7998346fd87265..92650c1d054a1da4d1c12a21e5dfc64956ac90f6 100644 (file)
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -203,6 +203,14 @@ class QueryableAttribute(
 
     @util.memoized_property
     def expression(self):
+        """The SQL expression object represented by this
+        :class:`.QueryableAttribute`.
+
+        This will typically be an instance of a :class:`_sql.ColumnElement`
+        subclass representing a column expression.
+
+        """
+
         return self.comparator.__clause_element__()._annotate(
             {"orm_key": self.key, "entity_namespace": self._entity_namespace}
         )