.. automethod:: rollback()
.. automethod:: transaction(savepoint_name: Optional[str] = None, force_rollback: bool = False) -> Transaction
- It must be called as ``with conn.transaction() as tx: ...``
+ .. note:: it must be called as ``with conn.transaction() as tx: ...``
Inside a transaction block it will not be possible to call `commit()`
or `rollback()`.
.. automethod:: transaction(savepoint_name: Optional[str] = None, force_rollback: bool = False) -> AsyncTransaction
- 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
.. autoclass:: Notify()
:members: channel, payload, pid
- The objet is usually returned by `Connection.notifies()`.
+ The object is usually returned by `Connection.notifies()`.
.. rubric:: Objects involved in :ref:`transactions`
further operation will not be possible. Closing a cursor will not
terminate a transaction or a session though.
+ .. attribute:: connection
+ :type: Connection
+
+ The connection this cursor is using.
+
.. automethod:: close
.. note:: you can use :ref:`with conn.cursor(): ...<with-statement>`
.. rubric:: Methods to send commands
- .. automethod:: execute
+ .. automethod:: execute(query: Query, vars: Optional[Args]=None) -> Cursor
+
+ :param query: The query to execute
+ :type query: `!str`, `!bytes`, or `sql.Composable`
+ :param vars: The parameters to pass to the query, if any
+ :type vars: Mapping, Sequence
Return the cursor itself, so that it will be possible to chain a fetch
- operation after the call
+ operation after the call.
See :ref:`query-parameters` for all the details about executing
queries.
- .. automethod:: executemany
+ .. automethod:: executemany(query: Query, vars_seq: Sequence[Args]) -> Cursor
+
+ :param query: The query to execute
+ :type query: `!str`, `!bytes`, or `sql.Composable`
+ :param vars_seq: The parameters to pass to the query
+ :type vars_seq: Sequence of Mapping or Sequence
This is more efficient than performing separate queries, but in case of
several :sql:`INSERT` (and with some SQL creativity for massive
See :ref:`query-parameters` for all the details about executing
queries.
- .. automethod:: copy
-
- It must be called as ``with cur.copy() as copy: ...``
+ .. automethod:: copy(statement: Query, vars: Optional[Args]=None) -> Copy
- See :ref:`copy` for information about :sql:`COPY`.
+ :param statement: The copy operation to execute
+ :type statement: `!str`, `!bytes`, or `sql.Composable`
+ :param args: The parameters to pass to the query, if any
+ :type args: Mapping, Sequence
- .. automethod:: callproc
+ .. note:: it must be called as ``with cur.copy() as copy: ...``
- This method exists for DBAPI compatibility but it's not much different
- than calling `execute()` on a :sql:`SELECT myproc(%s, %s, ...)`, which
- will give you more flexibility in passing arguments and retrieving
- results. Don't bother...
+ See :ref:`copy` for information about :sql:`COPY`.
.. rubric:: Methods to retrieve results
.. rubric:: Information about the data
- .. autoproperty:: description
- .. autoproperty:: rowcount
+ .. attribute:: description
+ :type: Optional[List[Column]]
+
+ 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
The `!AsyncCursor` class
The following methods have the same behaviour of the matching `!Cursor`
methods, but should be called using the `await` keyword.
+ .. attribute:: connection
+ :type: AsyncConnection
+
.. automethod:: close
.. note:: you can use ``async with`` to close the cursor
automatically when the block is exited, but be careful about
the async quirkness: see :ref:`with-statement` for details.
- .. automethod:: execute
- .. automethod:: executemany
- .. automethod:: copy
+ .. automethod:: execute(query: Query, vars: Optional[Args]=None) -> AsyncCursor
+ .. automethod:: executemany(query: Query, vars_seq: Sequence[Args]) -> AsyncCursor
+ .. automethod:: copy(statement: Query, vars: Optional[Args]=None) -> AsyncCopy
- It must be called as ``async with cur.copy() as copy: ...``
+ .. note:: it must be called as ``async with cur.copy() as copy: ...``
- .. automethod:: callproc
.. automethod:: fetchone
.. automethod:: fetchmany
.. automethod:: fetchall
from psycopg3_c import _psycopg3
_psycopg3.register_builtin_c_loaders()
+
+
+# Note: defining the exported methods helps both Sphynx in documenting that
+# this is the canonical place to obtain them and should be used by MyPy too,
+# so that function signatures are consistent with the documentation.
+__all__ = [
+ "AsyncConnection",
+ "AsyncCopy",
+ "AsyncCursor",
+ "AsyncTransaction",
+ "Column",
+ "Connection",
+ "Copy",
+ "Cursor",
+ "Notify",
+ "Rollback",
+ "Transaction",
+]
execute: Callable[["PGconn"], PQGen[List["PGresult"]]]
if TYPE_CHECKING:
+ import psycopg3
from .pq.proto import PGconn, PGresult
- from .cursor import Cursor, AsyncCursor
if pq.__impl__ == "c":
from psycopg3_c import _psycopg3
NoticeHandler = Callable[[e.Diagnostic], None]
-NotifyHandler = Callable[[Notify], None]
+NotifyHandler = Callable[["psycopg3.Notify"], None]
class BaseConnection:
ConnStatus = pq.ConnStatus
TransactionStatus = pq.TransactionStatus
- cursor_factory: Union[Type["Cursor"], Type["AsyncCursor"]]
+ cursor_factory: Union[
+ Type["psycopg3.Cursor"], Type["psycopg3.AsyncCursor"]
+ ]
def __init__(self, pgconn: "PGconn"):
self.pgconn = pgconn # TODO: document this
Wrapper for a connection to the database.
"""
- cursor_factory: Type[cursor.Cursor]
+ cursor_factory: Type["psycopg3.Cursor"]
def __init__(self, pgconn: "PGconn"):
super().__init__(pgconn)
def cursor(
self, name: str = "", format: pq.Format = pq.Format.TEXT
- ) -> cursor.Cursor:
+ ) -> "psycopg3.Cursor":
"""
Return a new `Cursor` to send commands and queries to the connection.
"""
result, encoding=self.client_encoding
)
- def notifies(self) -> Iterator[Notify]:
+ def notifies(self) -> Iterator["psycopg3.Notify"]:
"""
Yield `Notify` objects as soon as they are received from the database.
"""
Asynchronous wrapper for a connection to the database.
"""
- cursor_factory: Type[cursor.AsyncCursor]
+ cursor_factory: Type["psycopg3.AsyncCursor"]
def __init__(self, pgconn: "PGconn"):
super().__init__(pgconn)
async def cursor(
self, name: str = "", format: pq.Format = pq.Format.TEXT
- ) -> cursor.AsyncCursor:
+ ) -> "psycopg3.AsyncCursor":
"""
Return a new `AsyncCursor` to send commands and queries to the connection.
"""
result, encoding=self.client_encoding
)
- async def notifies(self) -> AsyncIterator[Notify]:
+ async def notifies(self) -> AsyncIterator["psycopg3.Notify"]:
while 1:
async with self.lock:
ns = await self.wait(notifies(self.pgconn))
@property
def null_ok(self) -> Optional[bool]:
- """Always `None`"""
+ """Always `!None`"""
return None
def fetchone(self) -> Optional[Sequence[Any]]:
"""
- Return the next record from the current recordset, `None` if not available.
+ Return the next record from the current recordset.
+
+ Return `!None` the recordset is finished.
"""
self._check_result()
rv = self._transformer.load_row(self._pos)
self, statement: Query, vars: Optional[Params] = None
) -> Iterator[Copy]:
"""
- Initiate a :sql:`COPY` operation and return a `Copy` object to manage it.
+ Initiate a :sql:`COPY` operation and return an object to manage it.
"""
with self._start_copy(statement, vars) as copy:
yield copy
async def copy(
self, statement: Query, vars: Optional[Params] = None
) -> AsyncIterator[AsyncCopy]:
- """
- Initiate a :sql:`COPY` operation and return an `AsyncCopy` object.
- """
copy = await self._start_copy(statement, vars)
async with copy:
yield copy
@property
def savepoint_name(self) -> Optional[str]:
- """The name of the savepoint; `None` if handling the main transaction."""
+ """
+ The name of the savepoint; `!None` if handling the main transaction.
+ """
# Yes, it may change on __enter__. No, I don't care, because the
# un-entered state is outside the public interface.
return self._savepoint_name
projects / thirdparty / psycopg.git / commitdiff
