:return: A cursor of the class specified by `cursor_factory` (or
`server_cursor_factory` if *name* is specified).
- .. note:: You can use :ref:`with conn.cursor(): ...<usage>`
+ .. note::
+
+ You can use::
+
+ with conn.cursor() as cur:
+ ...
+
to close the cursor automatically when the block is exited.
.. autoattribute:: cursor_factory
.. automethod:: rollback
.. automethod:: transaction
- .. note:: It must be called as ``with conn.transaction() as tx: ...``
+ .. note::
+
+ The method must be called with a syntax such as::
+
+ with conn.transaction():
+ ...
+
+ with conn.transaction() as tx:
+ ...
+
+ The latter is useful if you need to interact with the
+ `Transaction` object. See :ref:`transaction-block` for details.
Inside a transaction block it will not be possible to call `commit()`
or `rollback()`.
scrollable: Optional[bool] = None, withhold: bool = False) -> AsyncServerCursor
:noindex:
- .. note:: You can use ``async with conn.cursor() as cur: ...`` to
- close the cursor automatically when the block is exited.
+ .. note::
+
+ You can use::
+
+ async with conn.cursor() as cur:
+ ...
+
+ to close the cursor automatically when the block is exited.
.. autoattribute:: cursor_factory
.. automethod:: transaction
- .. note:: It must be called as ``async with conn.transaction() as tx: ...``.
+ .. note::
+
+ It must be called as::
+
+ async with conn.transaction() as tx:
+ ...
.. automethod:: notifies
.. automethod:: set_client_encoding
.. automethod:: close
- .. note:: you can use :ref:`with conn.cursor(): ...<usage>`
- to close the cursor automatically when the block is exited.
+ .. note::
+
+ You can use::
+
+ with conn.cursor() as cur:
+ ...
+
+ to close the cursor automatically when the block is exited. See
+ :ref:`usage`.
.. autoattribute:: closed
:param statement: The copy operation to execute
:type statement: `!str`, `!bytes`, or `sql.Composable`
- .. note:: it must be called as ``with cur.copy() as copy: ...``
+ .. note::
+
+ The method must be called with::
+
+ with cursor.copy() as copy:
+ ...
See :ref:`copy` for information about :sql:`COPY`.
an exception if used with operations that don't return result, such as an
:sql:`INSERT` with no :sql:`RETURNING` or an :sql:`ALTER TABLE`.
- .. note:: cursors are iterable objects, so just using ``for record in
- cursor`` syntax will iterate on the records in the current recordset.
+ .. note::
+
+ Cursors are iterable objects, so just using the::
+
+ for record in cursor:
+ ...
+
+ syntax will iterate on the records in the current recordset.
.. autoattribute:: row_factory
.. warning:: Closing a server-side cursor is more important than
closing a client-side one because it also releases the resources
on the server, which otherwise might remain allocated until the
- end of the session (memory, locks). Using the `with conn.cursor():
- ...` pattern is especially useful so that the cursor is closed at
- the end of the block.
+ end of the session (memory, locks). Using the pattern::
+
+ with conn.cursor():
+ ...
+
+ is especially useful so that the cursor is closed at the end of
+ the block.
.. automethod:: execute(query, params=None, *) -> ServerCursor
:type params: Sequence or Mapping
Create a server cursor with given `name` and the *query* in argument.
- If using :sql:`DECLARE` is not appropriate you can avoid to use
+
+ If using :sql:`DECLARE` is not appropriate (for instance because the
+ cursor is returned by calling a stored procedure) you can avoid to use
`!execute()`, crete the cursor in other ways, and use directly the
`!fetch*()` methods instead. See :ref:`cursor-steal` for an example.
.. _FETCH: https://www.postgresql.org/docs/current/sql-fetch.html
- .. note:: You can also iterate on the cursor to read its result one at
- time with `for record in cur: ...`. In this case, the records are
- not fetched one at time from the server but they are retrieved in
- batches of `itersize` to reduce the number of server roundtrips.
+ .. note::
+
+ You can also iterate on the cursor to read its result one at
+ time with::
+
+ for record in cur:
+ ...
+
+ In this case, the records are not fetched one at time from the
+ server but they are retrieved in batches of `itersize` to reduce
+ the number of server roundtrips.
.. autoattribute:: itersize
.. automethod:: close
- .. note:: You can use ``async with conn.cursor(): ...`` to close the
- cursor automatically when the block is exited.
+ .. note::
+
+ You can use::
+
+ async with conn.cursor():
+ ...
+
+ to close the cursor automatically when the block is exited.
.. automethod:: execute(query, params=None, *, prepare=None) -> AsyncCursor
.. automethod:: executemany(query: Query, params_seq: Sequence[Args])
.. automethod:: copy(statement: Query) -> AsyncCopy
- .. note:: It must be called as ``async with cur.copy() as copy: ...``
+ .. note::
+
+ The method must be called with::
+
+ async with cursor.copy() as copy:
+ ...
.. automethod:: stream(query, params=None) -> AsyncIterable[Sequence[Any]]
- .. note:: It must be called as ``async for record in cur.stream(query):
- ...``
+ .. note::
+
+ The method must be called with::
+
+ async for record in cursor.stream(query):
+ ...
.. automethod:: fetchone
.. automethod:: fetchmany
.. automethod:: fetchall
.. automethod:: scroll
- .. note:: You can also use ``async for record in cursor: ...`` to iterate
- on the async cursor results.
+ .. note::
+
+ You can also use::
+
+ async for record in cursor:
+ ...
+
+ to iterate on the async cursor results.
The `!AsyncServerCursor` class
.. automethod:: close
- .. note:: You can close the cursor automatically using :samp:`async
- with conn.cursor({name}): ...`
+ .. note::
+ You can close the cursor automatically using::
+
+ async with conn.cursor("name") as cursor:
+ ...
.. automethod:: execute(query, params=None) -> AsyncServerCursor
.. automethod:: executemany(query: Query, params_seq: Sequence[Args])
.. automethod:: fetchmany
.. automethod:: fetchall
- .. note:: You can also iterate on the cursor using `async for record
- in cur: ...`.
+ .. note::
+
+ You can also iterate on the cursor using::
+
+ async for record in cur:
+ ...
.. automethod:: scroll
projects / thirdparty / psycopg.git / commitdiff
