NamedCursor renamed to ServerCursor

In psycopg2 they are not a separate class as they are in psycopg3.

They still need a mandatory name, but having a name is not their
defining trait.

diff --git a/psycopg3/psycopg3/__init__.py b/psycopg3/psycopg3/__init__.py
index b2c4e85af20375e770ee1789fd401756ac972e10..a8dfce76b82fef12ad14c160e71b8f934db3bb3a 100644 (file)
--- a/psycopg3/psycopg3/__init__.py
+++ b/psycopg3/psycopg3/__init__.py
@@ -15,6 +15,7 @@ from .errors import InternalError, ProgrammingError, NotSupportedError
 from ._column import Column
 from .connection import AsyncConnection, Connection, Notify
 from .transaction import Rollback, Transaction, AsyncTransaction
+from .server_cursor import AsyncServerCursor, ServerCursor
 
 from .dbapi20 import BINARY, DATETIME, NUMBER, ROWID, STRING, BinaryDumper
 from .dbapi20 import Binary, Date, DateFromTicks, Time, TimeFromTicks
@@ -40,6 +41,7 @@ __all__ = [
     "AsyncConnection",
     "AsyncCopy",
     "AsyncCursor",
+    "AsyncServerCursor",
     "AsyncTransaction",
     "Column",
     "Connection",
@@ -47,5 +49,6 @@ __all__ = [
     "Cursor",
     "Notify",
     "Rollback",
+    "ServerCursor",
     "Transaction",
 ]

diff --git a/psycopg3/psycopg3/connection.py b/psycopg3/psycopg3/connection.py
index 0cc44d377e63e001853e4e041eef423254ebf185..71df504703c9cae2441677f43f7853f9b4495ed8 100644 (file)
--- a/psycopg3/psycopg3/connection.py
+++ b/psycopg3/psycopg3/connection.py
@@ -34,7 +34,7 @@ from .cursor import Cursor, AsyncCursor
 from .conninfo import make_conninfo
 from .generators import notifies
 from .transaction import Transaction, AsyncTransaction
-from .named_cursor import NamedCursor, AsyncNamedCursor
+from .server_cursor import ServerCursor, AsyncServerCursor
 from ._preparing import PrepareManager
 
 logger = logging.getLogger(__name__)
@@ -449,18 +449,18 @@ class Connection(BaseConnection):
         ...
 
     @overload
-    def cursor(self, name: str, *, binary: bool = False) -> NamedCursor:
+    def cursor(self, name: str, *, binary: bool = False) -> ServerCursor:
         ...
 
     def cursor(
         self, name: str = "", *, binary: bool = False
-    ) -> Union[Cursor, NamedCursor]:
+    ) -> Union[Cursor, ServerCursor]:
         """
         Return a new `Cursor` to send commands and queries to the connection.
         """
         format = Format.BINARY if binary else Format.TEXT
         if name:
-            return NamedCursor(self, name=name, format=format)
+            return ServerCursor(self, name=name, format=format)
         else:
             return Cursor(self, format=format)
 
@@ -591,18 +591,18 @@ class AsyncConnection(BaseConnection):
         ...
 
     @overload
-    def cursor(self, name: str, *, binary: bool = False) -> AsyncNamedCursor:
+    def cursor(self, name: str, *, binary: bool = False) -> AsyncServerCursor:
         ...
 
     def cursor(
         self, name: str = "", *, binary: bool = False
-    ) -> Union[AsyncCursor, AsyncNamedCursor]:
+    ) -> Union[AsyncCursor, AsyncServerCursor]:
         """
         Return a new `AsyncCursor` to send commands and queries to the connection.
         """
         format = Format.BINARY if binary else Format.TEXT
         if name:
-            return AsyncNamedCursor(self, name=name, format=format)
+            return AsyncServerCursor(self, name=name, format=format)
         else:
             return AsyncCursor(self, format=format)
 

diff --git a/psycopg3/psycopg3/named_cursor.py b/psycopg3/psycopg3/server_cursor.py
similarity index 90%
rename from psycopg3/psycopg3/named_cursor.py
rename to psycopg3/psycopg3/server_cursor.py
index abb3d1cd6a12aba275287395701c739bb3193f4e..cffda31341d8aa1da876b49458f3a3c49facf9d5 100644 (file)
--- a/psycopg3/psycopg3/named_cursor.py
+++ b/psycopg3/psycopg3/server_cursor.py
@@ -1,5 +1,5 @@
 """
-psycopg3 named cursor objects (server-side cursors)
+psycopg3 server-side cursor objects.
 """
 
 # Copyright (C) 2020-2021 The Psycopg Team
@@ -22,9 +22,9 @@ if TYPE_CHECKING:
 DEFAULT_ITERSIZE = 100
 
 
-class NamedCursorHelper(Generic[ConnectionType]):
+class ServerCursorHelper(Generic[ConnectionType]):
     __slots__ = ("name", "described")
-    """Helper object for common NamedCursor code.
+    """Helper object for common ServerCursor code.
 
     TODO: this should be a mixin, but couldn't find a way to work it
     correctly with the generic.
@@ -40,7 +40,7 @@ class NamedCursorHelper(Generic[ConnectionType]):
         query: Query,
         params: Optional[Params] = None,
     ) -> PQGen[None]:
-        """Generator implementing `NamedCursor.execute()`."""
+        """Generator implementing `ServerCursor.execute()`."""
         conn = cur._conn
         yield from cur._start_query(query)
         pgq = cur._convert_query(query, params)
@@ -132,7 +132,7 @@ class NamedCursorHelper(Generic[ConnectionType]):
         )
 
 
-class NamedCursor(BaseCursor["Connection"]):
+class ServerCursor(BaseCursor["Connection"]):
     __module__ = "psycopg3"
     __slots__ = ("_helper", "itersize")
 
@@ -144,18 +144,20 @@ class NamedCursor(BaseCursor["Connection"]):
         format: Format = Format.TEXT,
     ):
         super().__init__(connection, format=format)
-        self._helper: NamedCursorHelper["Connection"] = NamedCursorHelper(name)
+        self._helper: ServerCursorHelper["Connection"] = ServerCursorHelper(
+            name
+        )
         self.itersize = DEFAULT_ITERSIZE
 
     def __del__(self) -> None:
         if not self._closed:
             warnings.warn(
-                f"named cursor {self} was deleted while still open."
+                f"the server-side cursor {self} was deleted while still open."
                 f" Please use 'with' or '.close()' to close the cursor properly",
                 ResourceWarning,
             )
 
-    def __enter__(self) -> "NamedCursor":
+    def __enter__(self) -> "ServerCursor":
         return self
 
     def __exit__(
@@ -185,7 +187,7 @@ class NamedCursor(BaseCursor["Connection"]):
         *,
         scrollable: bool = True,
         hold: bool = False,
-    ) -> "NamedCursor":
+    ) -> "ServerCursor":
         """
         Execute a query or command to the database.
         """
@@ -197,7 +199,9 @@ class NamedCursor(BaseCursor["Connection"]):
         return self
 
     def executemany(self, query: Query, params_seq: Sequence[Params]) -> None:
-        raise e.NotSupportedError("executemany not supported on named cursors")
+        raise e.NotSupportedError(
+            "executemany not supported on server-side cursors"
+        )
 
     def fetchone(self) -> Optional[Sequence[Any]]:
         with self._conn.lock:
@@ -244,7 +248,7 @@ class NamedCursor(BaseCursor["Connection"]):
             self._pos = value
 
 
-class AsyncNamedCursor(BaseCursor["AsyncConnection"]):
+class AsyncServerCursor(BaseCursor["AsyncConnection"]):
     __module__ = "psycopg3"
     __slots__ = ("_helper", "itersize")
 
@@ -256,19 +260,19 @@ class AsyncNamedCursor(BaseCursor["AsyncConnection"]):
         format: Format = Format.TEXT,
     ):
         super().__init__(connection, format=format)
-        self._helper: NamedCursorHelper["AsyncConnection"]
-        self._helper = NamedCursorHelper(name)
+        self._helper: ServerCursorHelper["AsyncConnection"]
+        self._helper = ServerCursorHelper(name)
         self.itersize = DEFAULT_ITERSIZE
 
     def __del__(self) -> None:
         if not self._closed:
             warnings.warn(
-                f"named cursor {self} was deleted while still open."
+                f"the server-side cursor {self} was deleted while still open."
                 f" Please use 'with' or '.close()' to close the cursor properly",
                 ResourceWarning,
             )
 
-    async def __aenter__(self) -> "AsyncNamedCursor":
+    async def __aenter__(self) -> "AsyncServerCursor":
         return self
 
     async def __aexit__(
@@ -298,7 +302,7 @@ class AsyncNamedCursor(BaseCursor["AsyncConnection"]):
         *,
         scrollable: bool = True,
         hold: bool = False,
-    ) -> "AsyncNamedCursor":
+    ) -> "AsyncServerCursor":
         """
         Execute a query or command to the database.
         """
@@ -314,7 +318,9 @@ class AsyncNamedCursor(BaseCursor["AsyncConnection"]):
     async def executemany(
         self, query: Query, params_seq: Sequence[Params]
     ) -> None:
-        raise e.NotSupportedError("executemany not supported on named cursors")
+        raise e.NotSupportedError(
+            "executemany not supported on server-side cursors"
+        )
 
     async def fetchone(self) -> Optional[Sequence[Any]]:
         async with self._conn.lock:

diff --git a/tests/test_named_cursor.py b/tests/test_server_cursor.py
similarity index 100%
rename from tests/test_named_cursor.py
rename to tests/test_server_cursor.py

diff --git a/tests/test_named_cursor_async.py b/tests/test_server_cursor_async.py
similarity index 100%
rename from tests/test_named_cursor_async.py
rename to tests/test_server_cursor_async.py