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

diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py
index 72c1ad90aeef7eeed3ffa5aa29c29130552cf998..ef264ec559a285aeebf7ab5593a0bee6526f22b4 100644 (file)
--- a/lib/sqlalchemy/engine/cursor.py
+++ b/lib/sqlalchemy/engine/cursor.py
@@ -2334,6 +2334,11 @@ class CursorResult(Result[Unpack[_Ts]]):
         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 5c1cd85a583d9314594c509171d85fbdb5203ae6..471e2e4c65e31f625bd6790f3b8177b58cd3d333 100644 (file)
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -485,7 +485,7 @@ class Result(_WithKeys, ResultInternal[Row[Unpack[_Ts]]]):
         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
@@ -512,9 +512,19 @@ class Result(_WithKeys, ResultInternal[Row[Unpack[_Ts]]]):
 
     @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()
@@ -1194,10 +1204,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
@@ -1779,10 +1792,20 @@ class IteratorResult(Result[Unpack[_Ts]]):
 
     @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