From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 19 Aug 2023 17:19:48 +0000 (+0100)
Subject: docs: add docstrings from sync cursor to async
X-Git-Tag: pool-3.2.0~12^2~46
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3a906331b699609e92c588f724588d7f19f6b61b;p=thirdparty%2Fpsycopg.git

docs: add docstrings from sync cursor to async
---

diff --git a/psycopg/psycopg/cursor_async.py b/psycopg/psycopg/cursor_async.py
index 5289bb62a..2589aefca 100644
--- a/psycopg/psycopg/cursor_async.py
+++ b/psycopg/psycopg/cursor_async.py
@@ -62,10 +62,14 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         await self.close()
 
     async def close(self) -> None:
+        """
+        Close the current cursor and free associated resources.
+        """
         self._close()
 
     @property
     def row_factory(self) -> AsyncRowFactory[Row]:
+        """Writable attribute to control how result rows are formed."""
         return self._row_factory
 
     @row_factory.setter
@@ -85,6 +89,9 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         prepare: Optional[bool] = None,
         binary: Optional[bool] = None,
     ) -> _Self:
+        """
+        Execute a query or command to the database.
+        """
         try:
             async with self._conn.lock:
                 await self._conn.wait(
@@ -101,6 +108,9 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         *,
         returning: bool = False,
     ) -> None:
+        """
+        Execute the same command with a sequence of input data.
+        """
         try:
             if Pipeline.is_supported():
                 # If there is already a pipeline, ride it, in order to avoid
@@ -132,6 +142,9 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         *,
         binary: Optional[bool] = None,
     ) -> AsyncIterator[Row]:
+        """
+        Iterate row-by-row on a result from the database.
+        """
         if self._pgconn.pipeline_status:
             raise e.ProgrammingError("stream() cannot be used in pipeline mode")
 
@@ -171,6 +184,13 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
                         pass
 
     async def fetchone(self) -> Optional[Row]:
+        """
+        Return the next record from the current recordset.
+
+        Return `!None` the recordset is finished.
+
+        :rtype: Optional[Row], with Row defined by `row_factory`
+        """
         await self._fetch_pipeline()
         self._check_result_for_fetch()
         record = self._tx.load_row(self._pos, self._make_row)
@@ -179,6 +199,13 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         return record
 
     async def fetchmany(self, size: int = 0) -> List[Row]:
+        """
+        Return the next `!size` records from the current recordset.
+
+        `!size` default to `!self.arraysize` if not specified.
+
+        :rtype: Sequence[Row], with Row defined by `row_factory`
+        """
         await self._fetch_pipeline()
         self._check_result_for_fetch()
         assert self.pgresult
@@ -194,6 +221,11 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         return records
 
     async def fetchall(self) -> List[Row]:
+        """
+        Return all the remaining records from the current recordset.
+
+        :rtype: Sequence[Row], with Row defined by `row_factory`
+        """
         await self._fetch_pipeline()
         self._check_result_for_fetch()
         assert self.pgresult
@@ -216,6 +248,16 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
             yield row
 
     async def scroll(self, value: int, mode: str = "relative") -> None:
+        """
+        Move the cursor in the result set to a new position according to mode.
+
+        If `!mode` is ``'relative'`` (default), `!value` is taken as offset to
+        the current position in the result set; if set to ``'absolute'``,
+        `!value` states an absolute target position.
+
+        Raise `!IndexError` in case a scroll operation would leave the result
+        set. In this case the position will not change.
+        """
         await self._fetch_pipeline()
         self._scroll(value, mode)
 
@@ -228,6 +270,8 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         writer: Optional[AsyncCopyWriter] = None,
     ) -> AsyncIterator[AsyncCopy]:
         """
+        Initiate a :sql:`COPY` operation and return an object to manage it.
+
         :rtype: AsyncCopy
         """
         try:
@@ -239,6 +283,8 @@ class AsyncCursor(BaseCursor["AsyncConnection[Any]", Row]):
         except e._NO_TRACEBACK as ex:
             raise ex.with_traceback(None)
 
+        # If a fresher result has been set on the cursor by the Copy object,
+        # read its properties (especially rowcount).
         self._select_current_result(0)
 
     async def _fetch_pipeline(self) -> None: