From: Daniele Varrazzo Date: Sat, 2 Apr 2022 22:55:18 +0000 (+0200) Subject: docs: add page with misc objects documentation X-Git-Tag: 3.1~148 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3248ec5b42bf1272da7aba92b8905fe1d39a0d27;p=thirdparty%2Fpsycopg.git docs: add page with misc objects documentation Sorry that I broke some links, but the connection page was becoming unwieldy. --- diff --git a/docs/api/connections.rst b/docs/api/connections.rst index df44f58cf..5f3230068 100644 --- a/docs/api/connections.rst +++ b/docs/api/connections.rst @@ -451,188 +451,3 @@ The `!AsyncConnection` class .. automethod:: tpc_commit .. automethod:: tpc_rollback .. automethod:: tpc_recover - - -Connection support objects --------------------------- - -.. autoclass:: Notify() - - The object is usually returned by `Connection.notifies()`. - - .. attribute:: channel - :type: str - - The name of the channel on which the notification was received. - - .. attribute:: payload - :type: str - - The message attached to the notification. - - .. attribute:: pid - :type: int - - The PID of the backend process which sent the notification. - - -.. autoclass:: ConnectionInfo() - - The object is usually returned by `Connection.info`. - - .. autoattribute:: dsn - - .. note:: The `get_parameters()` method returns the same information - as a dict. - - .. autoattribute:: status - - The status can be one of a number of values. However, only two of - these are seen outside of an asynchronous connection procedure: - `~pq.ConnStatus.OK` and `~pq.ConnStatus.BAD`. A good connection to the - database has the status `!OK`. Ordinarily, an `!OK` status will remain - so until `Connection.close()`, but a communications failure might - result in the status changing to `!BAD` prematurely. - - .. autoattribute:: transaction_status - - The status can be `~pq.TransactionStatus.IDLE` (currently idle), - `~pq.TransactionStatus.ACTIVE` (a command is in progress), - `~pq.TransactionStatus.INTRANS` (idle, in a valid transaction block), - or `~pq.TransactionStatus.INERROR` (idle, in a failed transaction - block). `~pq.TransactionStatus.UNKNOWN` is reported if the connection - is bad. `!ACTIVE` is reported only when a query has been sent to the - server and not yet completed. - - .. autoattribute:: backend_pid - .. autoattribute:: server_version - .. autoattribute:: error_message - - .. automethod:: get_parameters - - .. note:: The `dsn` attribute returns the same information in the form - as a string. - - .. autoattribute:: timezone - - .. code:: pycon - - >>> conn.info.timezone - zoneinfo.ZoneInfo(key='Europe/Rome') - - .. autoattribute:: host - - This can be a host name, an IP address, or a directory path if the - connection is via Unix socket. (The path case can be distinguished - because it will always be an absolute path, beginning with ``/``.) - - .. autoattribute:: hostaddr - - Only available if the libpq used is at least from PostgreSQL 12. - Raise `~psycopg.NotSupportedError` otherwise. - - .. autoattribute:: port - .. autoattribute:: dbname - .. autoattribute:: user - .. autoattribute:: password - .. autoattribute:: options - .. automethod:: parameter_status - - Example of parameters are ``server_version``, - ``standard_conforming_strings``... See :pq:`PQparameterStatus()` for - all the available parameters. - - .. autoattribute:: encoding - - The value returned is always normalized to the Python codec - `~codecs.CodecInfo.name`:: - - conn.execute("SET client_encoding TO LATIN9") - conn.info.encoding - 'iso8859-15' - - A few PostgreSQL encodings are not available in Python and cannot be - selected (currently ``EUC_TW``, ``MULE_INTERNAL``). The PostgreSQL - ``SQL_ASCII`` encoding has the special meaning of "no encoding": see - :ref:`adapt-string` for details. - - .. seealso:: - - The `PostgreSQL supported encodings`__. - - .. __: https://www.postgresql.org/docs/current/multibyte.html - - -.. rubric:: Objects involved in :ref:`transactions` - -.. autoclass:: IsolationLevel - :members: - - The value is usually used with the `Connection.isolation_level` property. - - Check the PostgreSQL documentation for a description of the effects of the - different `levels of transaction isolation`__. - - .. __: https://www.postgresql.org/docs/current/transaction-iso.html - -.. autoclass:: Transaction() - - .. autoattribute:: savepoint_name - .. autoattribute:: connection - -.. autoclass:: AsyncTransaction() - - .. autoattribute:: connection - -.. autoexception:: Rollback - - It can be used as - - - ``raise Rollback``: roll back the operation that happened in the current - transaction block and continue the program after the block. - - - ``raise Rollback()``: same effect as above - - - :samp:`raise Rollback({tx})`: roll back any operation that happened in - the `Transaction` ``tx`` (returned by a statement such as :samp:`with - conn.transaction() as {tx}:` and all the blocks nested within. The - program will continue after the ``tx`` block. - - -.. autoclass:: Xid() - - See :ref:`two-phase-commit` for details. - - .. autoattribute:: format_id - - Format Identifier of the two-phase transaction. - - .. autoattribute:: gtrid - - Global Transaction Identifier of the two-phase transaction. - - If the Xid doesn't follow the XA standard, it will be the PostgreSQL - ID of the transaction (in which case `format_id` and `bqual` will be - `!None`). - - .. autoattribute:: bqual - - Branch Qualifier of the two-phase transaction. - - .. autoattribute:: prepared - - Timestamp at which the transaction was prepared for commit. - - Only available on transactions recovered by `~Connection.tpc_recover()`. - - .. autoattribute:: owner - - Named of the user that executed the transaction. - - Only available on recovered transactions. - - .. autoattribute:: database - - Named of the database in which the transaction was executed. - - Only available on recovered transactions. diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst index 5cd4bef02..282436c88 100644 --- a/docs/api/cursors.rst +++ b/docs/api/cursors.rst @@ -30,6 +30,8 @@ The `!Cursor` class ``await`` keywords to operate. .. __: dbapi-cursor_ + .. _dbapi-cursor: https://www.python.org/dev/peps/pep-0249/#cursor-objects + Cursors behave as context managers: on block exit they are closed and further operation will not be possible. Closing a cursor will not @@ -434,79 +436,3 @@ The `!AsyncServerCursor` class ... .. automethod:: scroll - - -The description `Column` object -------------------------------- - -.. autoclass:: Column() - - An object describing a column of data from a database result, `as described - by the DBAPI`__, so it can also be unpacked as a 7-items tuple. - - The object is returned by `Cursor.description`. - - .. __: https://www.python.org/dev/peps/pep-0249/#description - - .. autoattribute:: name - .. autoattribute:: type_code - .. autoattribute:: display_size - .. autoattribute:: internal_size - .. autoattribute:: precision - .. autoattribute:: scale - - -COPY-related objects --------------------- - -.. autoclass:: Copy() - - The object is normally returned by ``with`` `Cursor.copy()`. - - See :ref:`copy` for details. - - .. automethod:: write_row - - The data in the tuple will be converted as configured on the cursor; - see :ref:`adaptation` for details. - - .. automethod:: write - - .. versionchanged:: 3.1 - - accept `bytearray` and `memoryview` data as input too. - - .. automethod:: read - - Instead of using `!read()` you can iterate on the `!Copy` object to - read its data row by row, using ``for row in copy: ...``. - - .. automethod:: rows - - Equivalent of iterating on `read_row()` until it returns `!None` - - .. automethod:: read_row - .. automethod:: set_types - - -.. autoclass:: AsyncCopy() - - The object is normally returned by ``async with`` `AsyncCursor.copy()`. - Its methods are similar to the ones of the `Copy` object but offering an - `asyncio` interface (`await`, `async for`, `async with`). - - .. automethod:: write_row - .. automethod:: write - .. automethod:: read - - Instead of using `!read()` you can iterate on the `!AsyncCopy` object - to read its data row by row, using ``async for row in copy: ...``. - - .. automethod:: rows - - Use it as `async for record in copy.rows():` ... - - .. automethod:: read_row - - -.. _dbapi-cursor: https://www.python.org/dev/peps/pep-0249/#cursor-objects diff --git a/docs/api/index.rst b/docs/api/index.rst index 91335b87a..a487c10b6 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -14,6 +14,7 @@ This sections is a reference for all the public objects exposed by the module connections cursors + objects sql rows errors diff --git a/docs/api/objects.rst b/docs/api/objects.rst new file mode 100644 index 000000000..76dc1f1d6 --- /dev/null +++ b/docs/api/objects.rst @@ -0,0 +1,273 @@ +.. currentmodule:: psycopg + +Other top-level objects +======================= + +Connection information +---------------------- + +.. autoclass:: ConnectionInfo() + + The object is usually returned by `Connection.info`. + + .. autoattribute:: dsn + + .. note:: The `get_parameters()` method returns the same information + as a dict. + + .. autoattribute:: status + + The status can be one of a number of values. However, only two of + these are seen outside of an asynchronous connection procedure: + `~pq.ConnStatus.OK` and `~pq.ConnStatus.BAD`. A good connection to the + database has the status `!OK`. Ordinarily, an `!OK` status will remain + so until `Connection.close()`, but a communications failure might + result in the status changing to `!BAD` prematurely. + + .. autoattribute:: transaction_status + + The status can be `~pq.TransactionStatus.IDLE` (currently idle), + `~pq.TransactionStatus.ACTIVE` (a command is in progress), + `~pq.TransactionStatus.INTRANS` (idle, in a valid transaction block), + or `~pq.TransactionStatus.INERROR` (idle, in a failed transaction + block). `~pq.TransactionStatus.UNKNOWN` is reported if the connection + is bad. `!ACTIVE` is reported only when a query has been sent to the + server and not yet completed. + + .. autoattribute:: backend_pid + .. autoattribute:: server_version + .. autoattribute:: error_message + + .. automethod:: get_parameters + + .. note:: The `dsn` attribute returns the same information in the form + as a string. + + .. autoattribute:: timezone + + .. code:: pycon + + >>> conn.info.timezone + zoneinfo.ZoneInfo(key='Europe/Rome') + + .. autoattribute:: host + + This can be a host name, an IP address, or a directory path if the + connection is via Unix socket. (The path case can be distinguished + because it will always be an absolute path, beginning with ``/``.) + + .. autoattribute:: hostaddr + + Only available if the libpq used is at least from PostgreSQL 12. + Raise `~psycopg.NotSupportedError` otherwise. + + .. autoattribute:: port + .. autoattribute:: dbname + .. autoattribute:: user + .. autoattribute:: password + .. autoattribute:: options + .. automethod:: parameter_status + + Example of parameters are ``server_version``, + ``standard_conforming_strings``... See :pq:`PQparameterStatus()` for + all the available parameters. + + .. autoattribute:: encoding + + The value returned is always normalized to the Python codec + `~codecs.CodecInfo.name`:: + + conn.execute("SET client_encoding TO LATIN9") + conn.info.encoding + 'iso8859-15' + + A few PostgreSQL encodings are not available in Python and cannot be + selected (currently ``EUC_TW``, ``MULE_INTERNAL``). The PostgreSQL + ``SQL_ASCII`` encoding has the special meaning of "no encoding": see + :ref:`adapt-string` for details. + + .. seealso:: + + The `PostgreSQL supported encodings`__. + + .. __: https://www.postgresql.org/docs/current/multibyte.html + + +The description `Column` object +------------------------------- + +.. autoclass:: Column() + + An object describing a column of data from a database result, `as described + by the DBAPI`__, so it can also be unpacked as a 7-items tuple. + + The object is returned by `Cursor.description`. + + .. __: https://www.python.org/dev/peps/pep-0249/#description + + .. autoattribute:: name + .. autoattribute:: type_code + .. autoattribute:: display_size + .. autoattribute:: internal_size + .. autoattribute:: precision + .. autoattribute:: scale + + +COPY-related objects +-------------------- + +.. autoclass:: Copy() + + The object is normally returned by ``with`` `Cursor.copy()`. + + See :ref:`copy` for details. + + .. automethod:: write_row + + The data in the tuple will be converted as configured on the cursor; + see :ref:`adaptation` for details. + + .. automethod:: write + + .. versionchanged:: 3.1 + + accept `bytearray` and `memoryview` data as input too. + + .. automethod:: read + + Instead of using `!read()` you can iterate on the `!Copy` object to + read its data row by row, using ``for row in copy: ...``. + + .. automethod:: rows + + Equivalent of iterating on `read_row()` until it returns `!None` + + .. automethod:: read_row + .. automethod:: set_types + + +.. autoclass:: AsyncCopy() + + The object is normally returned by ``async with`` `AsyncCursor.copy()`. + Its methods are similar to the ones of the `Copy` object but offering an + `asyncio` interface (`await`, `async for`, `async with`). + + .. automethod:: write_row + .. automethod:: write + .. automethod:: read + + Instead of using `!read()` you can iterate on the `!AsyncCopy` object + to read its data row by row, using ``async for row in copy: ...``. + + .. automethod:: rows + + Use it as `async for record in copy.rows():` ... + + .. automethod:: read_row + + +Notifications +------------- + +.. autoclass:: Notify() + + The object is usually returned by `Connection.notifies()`. + + .. attribute:: channel + :type: str + + The name of the channel on which the notification was received. + + .. attribute:: payload + :type: str + + The message attached to the notification. + + .. attribute:: pid + :type: int + + The PID of the backend process which sent the notification. + + +Transaction-related objects +--------------------------- + +See :ref:`transactions` for details about these objects. + +.. autoclass:: IsolationLevel + :members: + + The value is usually used with the `Connection.isolation_level` property. + + Check the PostgreSQL documentation for a description of the effects of the + different `levels of transaction isolation`__. + + .. __: https://www.postgresql.org/docs/current/transaction-iso.html + + +.. autoclass:: Transaction() + + .. autoattribute:: savepoint_name + .. autoattribute:: connection + + +.. autoclass:: AsyncTransaction() + + .. autoattribute:: connection + + +.. autoexception:: Rollback + + It can be used as + + - ``raise Rollback``: roll back the operation that happened in the current + transaction block and continue the program after the block. + + - ``raise Rollback()``: same effect as above + + - :samp:`raise Rollback({tx})`: roll back any operation that happened in + the `Transaction` ``tx`` (returned by a statement such as :samp:`with + conn.transaction() as {tx}:` and all the blocks nested within. The + program will continue after the ``tx`` block. + + +Two-Phase Commit related objects +-------------------------------- + +.. autoclass:: Xid() + + See :ref:`two-phase-commit` for details. + + .. autoattribute:: format_id + + Format Identifier of the two-phase transaction. + + .. autoattribute:: gtrid + + Global Transaction Identifier of the two-phase transaction. + + If the Xid doesn't follow the XA standard, it will be the PostgreSQL + ID of the transaction (in which case `format_id` and `bqual` will be + `!None`). + + .. autoattribute:: bqual + + Branch Qualifier of the two-phase transaction. + + .. autoattribute:: prepared + + Timestamp at which the transaction was prepared for commit. + + Only available on transactions recovered by `~Connection.tpc_recover()`. + + .. autoattribute:: owner + + Named of the user that executed the transaction. + + Only available on recovered transactions. + + .. autoattribute:: database + + Named of the database in which the transaction was executed. + + Only available on recovered transactions.