From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 15 Dec 2020 13:52:15 +0000 (-0500)
Subject: Use .expression accessor for hybrid example
X-Git-Tag: rel_1_4_0b2~98
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=688b4ca6a7f2e32c580d616c6dea1e68b7398fd2;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 83562502ab..8679d907a6 100644
--- 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 4280cb76e6..92650c1d05 100644
--- 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}
         )