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_3_21~3
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=236bf7b5f118a6f34d8e56c4ebc5897e0a276b29;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
(cherry picked from commit 688b4ca6a7f2e32c580d616c6dea1e68b7398fd2)
---

diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py
index c654313cf1..578b7c2731 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 15476a2c46..22aecc844a 100644
--- 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):