From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 18 Mar 2026 19:30:54 +0000 (-0400)
Subject: clarify the Result.closed attribute
X-Git-Tag: rel_2_0_49~15
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=6d0f61fd171dc34827cd402f5e18cdd15ec0683e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

clarify the Result.closed attribute

document that Result.returns_rows is usually what people
want when they are looking for this.

References: #13184
Change-Id: Ia0b23e7482115bca3f93d20e21e53598aa9d084c
(cherry picked from commit 4840e6a206741eb7fe54e47067f61a57dd36c68d)
---

diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py
index 801fa4ff9e..5da66febb1 100644
--- a/lib/sqlalchemy/engine/cursor.py
+++ b/lib/sqlalchemy/engine/cursor.py
@@ -2218,6 +2218,11 @@ class CursorResult(Result[_T]):
         using the MSSQL / pyodbc dialect a SELECT is emitted inline in
         order to retrieve an inserted primary key value.
 
+        .. seealso::
+
+            :meth:`.Result.close`
+
+            :attr:`.Result.closed`
 
         """
         return self._metadata.returns_rows
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index b0788a6071..f4f968ed53 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -966,7 +966,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]):
         self.close()
 
     def close(self) -> None:
-        """close this :class:`_engine.Result`.
+        """Hard close this :class:`_engine.Result`.
 
         The behavior of this method is implementation specific, and is
         not implemented by default.    The method should generally end
@@ -993,9 +993,19 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]):
 
     @property
     def closed(self) -> bool:
-        """return ``True`` if this :class:`_engine.Result` reports .closed
+        """Return ``True`` if this :class:`_engine.Result` was **hard closed**
+        by explicitly calling the :meth:`close` method.
 
-        .. versionadded:: 1.4.43
+        The attribute is **not** True if the :class:`_engine.Result` was only
+        **soft closed**; a "soft close" is the style of close that takes place
+        for example when the :class:`.CursorResult` is returned for a DML
+        only statement without RETURNING, or when all result rows are fetched.
+
+        .. seealso::
+
+            :attr:`.CursorResult.returns_rows` -  attribute specific to
+            :class:`.CursorResult` which indicates if the result is one that
+            may return zero or more rows
 
         """
         raise NotImplementedError()
@@ -1661,10 +1671,13 @@ class FilterResult(ResultInternal[_R]):
 
     @property
     def closed(self) -> bool:
-        """Return ``True`` if the underlying :class:`_engine.Result` reports
-        closed
+        """Return ``True`` if this :class:`_engine.Result` being
+        proxied by this :class:`_engine.FilterResult` was
+        **hard closed** by explicitly calling the :meth:`_engine.Result.close`
+        method.
 
-        .. versionadded:: 1.4.43
+        This is a direct proxy for the :attr:`_engine.Result.closed` attribute;
+        see that attribute for details.
 
         """
         return self._real_result.closed
@@ -2239,10 +2252,20 @@ class IteratorResult(Result[_TP]):
 
     @property
     def closed(self) -> bool:
-        """Return ``True`` if this :class:`_engine.IteratorResult` has
-        been closed
+        """Return ``True`` if this :class:`_engine.IteratorResult` was
+        **hard closed** by explicitly calling the :meth:`_engine.Result.close`
+        method.
 
-        .. versionadded:: 1.4.43
+        The attribute is **not** True if the :class:`_engine.Result` was only
+        **soft closed**; a "soft close" is the style of close that takes place
+        for example when the :class:`.CursorResult` is returned for a DML
+        only statement without RETURNING, or when all result rows are fetched.
+
+        .. seealso::
+
+            :attr:`.CursorResult.returns_rows` -  attribute specific to
+            :class:`.CursorResult` which indicates if the result is one that
+            may return zero or more rows
 
         """
         return self._hard_closed