Adding upstream version 3.1.7.upstream/3.1.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 256 insertions, 0 deletions

diff --git a/docs/api/objects.rst b/docs/api/objects.rst
new file mode 100644
index 0000000..f085ed9
--- /dev/null
+++ b/docs/api/objects.rst
@@ -0,0 +1,256 @@
+.. 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:: pipeline_status
+
+    .. autoattribute:: backend_pid
+    .. autoattribute:: vendor
+
+        Normally it is `PostgreSQL`; it may be different if connected to
+        a different database.
+
+        .. versionadded:: 3.1
+
+    .. autoattribute:: server_version
+
+        The number is formed by converting the major, minor, and revision
+        numbers into two-decimal-digit numbers and appending them together.
+        Starting from PostgreSQL 10 the minor version was dropped, so the
+        second group of digits is always 00. For example, version 9.3.5 is
+        returned as 90305, version 10.2 as 100002.
+
+    .. 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
+
+
+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.
+
+
+Pipeline-related objects
+------------------------
+
+See :ref:`pipeline-mode` for details.
+
+.. autoclass:: Pipeline
+
+    This objects is returned by `Connection.pipeline()`.
+
+    .. automethod:: sync
+    .. automethod:: is_supported
+
+
+.. autoclass:: AsyncPipeline
+
+    This objects is returned by `AsyncConnection.pipeline()`.
+
+    .. automethod:: sync
+
+
+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.