your cake. Don't tell me I didn't warn you.
.. autoattribute:: oid
- :annotation: int
.. admonition:: todo
close the connection automatically when the block is exited.
.. autoattribute:: closed
- :annotation: bool
-
.. autoattribute:: broken
- :annotation: bool
.. method:: cursor(*, binary: bool = False, row_factory: Optional[RowFactory] = None) -> Cursor
.. automethod:: commit()
.. automethod:: rollback()
- .. automethod:: transaction(savepoint_name: Optional[str] = None, force_rollback: bool = False) -> Transaction
+ .. automethod:: transaction
.. note:: It must be called as ``with conn.transaction() as tx: ...``
or `rollback()`.
.. autoattribute:: autocommit
- :annotation: bool
The property is writable for sync connections, read-only for async
ones: you should call ``await`` `~AsyncConnection.set_autocommit`\
.. rubric:: Checking and configuring the connection state
.. autoattribute:: client_encoding
- :annotation: str
The property is writable for sync connections, read-only for async
ones: you should call ``await`` `~AsyncConnection.set_client_encoding`\
TODO
-
.. automethod:: fileno
.. autoattribute:: prepare_threshold
- :annotation: Optional[int]
See :ref:`prepared-statements` for details.
.. autoattribute:: prepared_max
- :annotation: int
If more queries need to be prepared, old ones are deallocated__.
.. rubric:: Methods you can use to do something cool
+ .. automethod:: cancel
+
.. automethod:: notifies
Notifies are recevied after using :sql:`LISTEN` in a connection, when
listened channels.
.. automethod:: add_notify_handler
+
+ :param callback: a callable taking a `Notify` parameter.
+
.. automethod:: remove_notify_handler
See :ref:`async-notify` for details.
- .. automethod:: cancel
.. automethod:: add_notice_handler
- The argument of the callback is a `~psycopg3.errors.Diagnostic` object
- containing all the details about the notice.
+ :param callback: a callable taking a `~psycopg3.errors.Diagnostic`
+ object containing all the details about the notice.
.. automethod:: remove_notice_handler
.. automethod:: commit
.. automethod:: rollback
- .. automethod:: transaction(savepoint_name: Optional[str] = None, force_rollback: bool = False) -> AsyncTransaction
+ .. automethod:: transaction
.. note:: It must be called as ``async with conn.transaction() as tx: ...``.
.. autoproperty:: savepoint_name
.. autoattribute:: connection
- :annotation: Connection
.. autoclass:: AsyncTransaction()
+ .. autoattribute:: connection
+
.. autoexception:: Rollback
It can be used as
to close the cursor automatically when the block is exited.
.. autoattribute:: closed
- :annotation: bool
.. rubric:: Methods to send commands
.. note:: cursors are iterable objects, so just using ``for record in
cursor`` syntax will iterate on the records in the current recordset.
+ .. autoproperty:: row_factory
+
+ The property affects the objects returned by the `fetchone()`,
+ `fetchmany()`, `fetchall()` methods. The default
+ (`~psycopg3.rows.tuple_row`) returns a tuple for each record fetched.
+
+ See :ref:`row-factories` for details.
+
.. automethod:: fetchone
.. automethod:: fetchmany
.. automethod:: fetchall
.. rubric:: Information about the data
- .. attribute:: description
- :type: Optional[List[Column]]
+ .. autoattribute:: description
A list of objects describing each column of the current queryset.
`!None` if the last operation didn't return a queryset.
.. autoattribute:: rowcount
- :annotation: int
-
.. autoattribute:: rownumber
- :annotation: int
.. autoattribute:: query
- :annotation: Optional[bytes]
The query will be in PostgreSQL format (with ``$1``, ``$2``...
parameters), the parameters will *not* be merged to the query: see
`params`.
.. autoattribute:: params
- :annotation: Optional[List[Optional[bytes]]]
The parameters are adapted to PostgreSQL format.
documented the differences:
.. autoattribute:: name
- :annotation: str
.. automethod:: close
batches of `itersize` to reduce the number of server roundtrips.
.. autoattribute:: itersize
- :annotation: int
Number of records to fetch at time when iterating on the cursor. The
default is 100.
--------------
.. autodata:: __impl__
- :annotation: str:
The choice of implementation is automatic but can be forced setting the
:envvar:`PSYCOPG3_IMPL` env var.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
+ "sphinx_autodoc_typehints",
"sql_role",
"pg3_docs",
"libpq_docs",
import os
import re
+import logging
import importlib
from typing import Dict
from collections import deque
recover_defined_module(psycopg3)
monkeypatch_autodoc()
+ # Disable warnings in sphinx_autodoc_typehints because it doesn't seem that
+ # there is a workaround for: "WARNING: Cannot resolve forward reference in
+ # type annotations"
+ logger = logging.getLogger("sphinx.sphinx_autodoc_typehints")
+ logger.setLevel(logging.ERROR)
+
# Classes which may have __module__ overwritten
recovered_classes: Dict[type, str] = {}
Sphinx >= 3.3, < 3.4
docutils >= 0.16, < 0.17
+sphinx-autodoc-typehints >= 1.12, < 1.13
furo
context.connection if context else None
)
- self.oid = self._oid
+ self.oid: int = self._oid
"""The oid to pass to the server, if known."""
@abstractmethod
transaction. If `!None`, one will be chosen automatically.
:param force_rollback: Roll back the transaction at the end of the
block even if there were no error (e.g. to try a no-op process).
+ :rtype: Transaction
"""
with Transaction(self, savepoint_name, force_rollback) as tx:
yield tx
) -> AsyncIterator[AsyncTransaction]:
"""
Start a context block with a new transaction or nested transaction.
+
+ :rtype: AsyncTransaction
"""
tx = AsyncTransaction(self, savepoint_name, force_rollback)
async with tx:
@property
def row_factory(self) -> RowFactory:
+ """Writable attribute to control how result rows are formed."""
return self._row_factory
@row_factory.setter
Return the next record from the current recordset.
Return `!None` the recordset is finished.
+
+ :rtype: Optional[Row], with Row defined by `row_factory`
"""
self._check_result()
record = self._tx.load_row(self._pos)
self._pos += 1
return record # type: ignore[no-any-return]
- def fetchmany(self, size: int = 0) -> Sequence[Row]:
+ 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`
"""
self._check_result()
assert self.pgresult
self._pos += len(records)
return records
- def fetchall(self) -> Sequence[Row]:
+ def fetchall(self) -> List[Row]:
"""
Return all the remaining records from the current recordset.
+
+ :rtype: Sequence[Row], with Row defined by `row_factory`
"""
self._check_result()
assert self.pgresult
def copy(self, statement: Query) -> Iterator[Copy]:
"""
Initiate a :sql:`COPY` operation and return an object to manage it.
+
+ :rtype: Copy
"""
with self._conn.lock:
self._conn.wait(self._start_copy_gen(statement))
@asynccontextmanager
async def copy(self, statement: Query) -> AsyncIterator[AsyncCopy]:
+ """
+ :rtype: AsyncCopy
+ """
async with self._conn.lock:
await self._conn.wait(self._start_copy_gen(statement))
super().__init__(connection, format=format, row_factory=row_factory)
self._helper: ServerCursorHelper["Connection"]
self._helper = ServerCursorHelper(name)
- self.itersize = DEFAULT_ITERSIZE
+ self.itersize: int = DEFAULT_ITERSIZE
def __del__(self) -> None:
if not self._closed:
super().__init__(connection, format=format, row_factory=row_factory)
self._helper: ServerCursorHelper["AsyncConnection"]
self._helper = ServerCursorHelper(name)
- self.itersize = DEFAULT_ITERSIZE
+ self.itersize: int = DEFAULT_ITERSIZE
def __del__(self) -> None:
if not self._closed:
self.force_rollback = force_rollback
self._entered = self._exited = False
- @property
- def connection(self) -> ConnectionType:
- """The connection the object is managing."""
- return self._conn
-
@property
def savepoint_name(self) -> Optional[str]:
"""
__module__ = "psycopg3"
+ @property
+ def connection(self) -> "Connection":
+ """The connection the object is managing."""
+ return self._conn
+
def __enter__(self) -> "Transaction":
with self._conn.lock:
self._conn.wait(self._enter_gen())
__module__ = "psycopg3"
+ @property
+ def connection(self) -> "AsyncConnection":
+ return self._conn
+
async def __aenter__(self) -> "AsyncTransaction":
async with self._conn.lock:
await self._conn.wait(self._enter_gen())
projects / thirdparty / psycopg.git / commitdiff
