From: Daniele Varrazzo Date: Fri, 20 Nov 2020 03:50:19 +0000 (+0000) Subject: Docs cleanup X-Git-Tag: 3.0.dev0~339 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0f76163432f37809adfe2316939aead08f104b93;p=thirdparty%2Fpsycopg.git Docs cleanup Including hiding the constructors of classes which aren't supposed to be initialised directly by the user. --- diff --git a/docs/connection.rst b/docs/connection.rst index 6d74ad49b..451e6fca6 100644 --- a/docs/connection.rst +++ b/docs/connection.rst @@ -16,7 +16,7 @@ Take a look to :ref:`transactions` for the details. The `!Connection` class ----------------------- -.. autoclass:: Connection +.. autoclass:: Connection() This class implements a `DBAPI-compliant interface`__. It is what you want to use if you write a "classic", blocking program (eventually using @@ -79,7 +79,7 @@ The `!Connection` class :annotation: bool The property is writable for sync connections, read-only for async - ones: you should call `!await` `~AsyncConnection.set_autocommit`\ + ones: you should call ``await`` `~AsyncConnection.set_autocommit`\ :samp:`({value})` instead. .. rubric:: Checking and configuring the connection state @@ -88,7 +88,7 @@ The `!Connection` class :annotation: str The property is writable for sync connections, read-only for async - ones: you should call `!await` `~AsyncConnection.set_client_encoding`\ + ones: you should call ``await`` `~AsyncConnection.set_client_encoding`\ :samp:`({value})` instead. .. attribute:: info @@ -118,25 +118,25 @@ The `!Connection` class The `!AsyncConnection` class ---------------------------- -.. autoclass:: AsyncConnection +.. autoclass:: AsyncConnection() This class implements a DBAPI-inspired interface, with all the blocking methods implemented as coroutines. Unless specified otherwise, non-blocking methods are shared with the `Connection` class. The following methods have the same behaviour of the matching `!Connection` - methods, but have an `async` interface. + methods, but should be called using the `await` keyword. .. automethod:: connect .. automethod:: close - .. note:: you can use `!async with` to close the connection + .. note:: you can use ``async with`` to close the connection automatically when the block is exited, but be careful about the async quirkness: see :ref:`with-statement` for details. .. automethod:: cursor - .. note:: you can use `!async with` to close the cursor + .. 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. @@ -155,18 +155,21 @@ The `!AsyncConnection` class Connection support objects -------------------------- -.. autoclass:: Notify +.. autoclass:: Notify() :members: channel, payload, pid + The objet is usually returned by `Connection.notifies()`. + + .. rubric:: Objects involved in :ref:`transactions` -.. autoclass:: Transaction(connection: Connection, savepoint_name: Optional[str] = None, force_rollback: bool = False) +.. autoclass:: Transaction() .. autoproperty:: savepoint_name .. autoattribute:: connection :annotation: Connection -.. autoclass:: AsyncTransaction(connection: AsyncConnection, savepoint_name: Optional[str] = None, force_rollback: bool = False) +.. autoclass:: AsyncTransaction() .. autoexception:: Rollback diff --git a/docs/cursor.rst b/docs/cursor.rst index 429dbf8d6..83a24f1ec 100644 --- a/docs/cursor.rst +++ b/docs/cursor.rst @@ -5,7 +5,7 @@ Cursor classes The `Cursor` and `AsyncCursor` classes are the main objects to send commands to a PostgreSQL database session. They are normally created by the -`~Connection.cursor()` method. +connection's `~Connection.cursor()` method. A `Connection` can create several cursors, but only one at time can perform operations, so they are not the best way to achieve parallelism (you may want @@ -17,7 +17,7 @@ uncommitted data. The `!Cursor` class ------------------- -.. autoclass:: Cursor +.. autoclass:: Cursor() This class implements `DBAPI-compliant interface`__. It is what the classic `Connection.cursor()` method returns. `AsyncConnection.cursor()` @@ -60,6 +60,8 @@ The `!Cursor` class .. automethod:: copy + It must be called as ``with cur.copy() as copy: ...`` + See :ref:`copy` for information about :sql:`COPY`. .. automethod:: callproc @@ -76,8 +78,8 @@ The `!Cursor` class 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`. - Cursors are iterable objects, so just using ``for var in cursor`` syntax - will iterate on the records in the current recordset. + .. note:: cursors are iterable objects, so just using ``for record in + cursor`` syntax will iterate on the records in the current recordset. .. automethod:: fetchone .. automethod:: fetchmany @@ -94,37 +96,45 @@ The `!Cursor` class The `!AsyncCursor` class ------------------------ -.. autoclass:: AsyncCursor +.. autoclass:: AsyncCursor() This class implements a DBAPI-inspired interface, with all the blocking methods implemented as coroutines. Unless specified otherwise, non-blocking methods are shared with the `Cursor` class. The following methods have the same behaviour of the matching `!Cursor` - methods, but have an `async` interface. + methods, but should be called using the `await` keyword. .. automethod:: close - .. note:: you can use `!async with` to close the cursor + .. 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 + + It must be called as ``async with cur.copy() as copy: ...`` + .. automethod:: callproc .. automethod:: fetchone .. automethod:: fetchmany .. automethod:: fetchall + .. note:: you can also use ``async for record in cursor`` to iterate on + the async cursor results. + Cursor support objects ---------------------- -.. autoclass:: Column +.. 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 + 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 @@ -136,18 +146,16 @@ Cursor support objects .. autoproperty:: scale -.. autoclass:: Copy +.. autoclass:: Copy() - The object is normally returned by `Cursor.copy()`. It can be used as a - context manager (useful to load data into a database using :sql:`COPY FROM`) - and can be iterated (useful to read data after a :sql:`COPY TO`). + The object is normally returned by ``with`` `Cursor.copy()`. See :ref:`copy` for details. .. automethod:: read - Alternatively, you can iterate on the `Copy` object to read its data - row by row. + Instead of using `!read()` you can even iterate on the object to read + its data row by row, using ``for row in copy: ...``. .. automethod:: write .. automethod:: write_row @@ -156,12 +164,16 @@ Cursor support objects see :ref:`adaptation` for details. -.. autoclass:: AsyncCopy +.. autoclass:: AsyncCopy() - The object is normally returned by `AsyncCursor.copy()`. Its methods are + The object is normally returned by ``async with`` `AsyncCursor.copy()`. Its methods are the same of the `Copy` object but offering an `asyncio` interface (`await`, `async for`, `async with`). .. automethod:: read + + Instead of using `!read()` you can even iterate on the object to read + its data row by row, using ``async for row in copy: ...``. + .. automethod:: write .. automethod:: write_row diff --git a/docs/usage.rst b/docs/usage.rst index e4c56bdd0..758ae4319 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -201,7 +201,7 @@ transaction, such as :sql:`CREATE DATABASE`, :sql:`VACUUM`, :sql:`CALL` on .. warning:: - By default even a simple :sql:`SELECT` will start a transaction: in + by default even a simple :sql:`SELECT` will start a transaction: in long-running programs, if no further action is taken, the session will remain *idle in transaction*, an undesirable condition for several reasons (locks are held by the session, tables bloat...). For long lived @@ -215,7 +215,7 @@ Transaction blocks ------------------ A more transparent way to make sure that transactions are finalised at the -right time is to use `!with` `Connection.transaction()` to create a +right time is to use ``with`` `Connection.transaction()` to create a transaction block. When the block is entered a transaction is started; when leaving the block the transaction is committed, or it is rolled back if an exception is raised inside the block. @@ -273,7 +273,7 @@ number of operations successfully processed. If `!unreliable_operation()` causes an error, including an operation causing a database error, all its changes will be reverted. The exception bubbles up -outside the block: in the example it is intercepted by the `!try` so that the +outside the block: in the example it is intercepted by the ``try`` so that the loop can complete. The outermost block is unaffected (unless other errors happen there). @@ -332,7 +332,7 @@ database from any Python iterable (a list of tuple, or any iterable of sequences): the Python values are adapted as they would be in normal querying. To perform such operation use a :sql:`COPY [table] FROM STDIN` with `Cursor.copy()` and use `~Copy.write_row()` on the resulting object in a -`!with` block. On exiting the block the operation will be concluded: +``with`` block. On exiting the block the operation will be concluded: .. code:: python diff --git a/psycopg3/psycopg3/copy.py b/psycopg3/psycopg3/copy.py index 5c7fd5161..7165120fc 100644 --- a/psycopg3/psycopg3/copy.py +++ b/psycopg3/psycopg3/copy.py @@ -128,7 +128,7 @@ class Copy(BaseCopy["Connection"]): """Manage a :sql:`COPY` operation.""" def read(self) -> bytes: - """Read a row after a :sql:`COPY TO` operation. + """Read a row of data after a :sql:`COPY TO` operation. Return an empty bytes string when the data is finished. """ @@ -147,7 +147,11 @@ class Copy(BaseCopy["Connection"]): return b"" def write(self, buffer: Union[str, bytes]) -> None: - """Write a block of data after a :sql:`COPY FROM` operation.""" + """Write a block of data after a :sql:`COPY FROM` operation. + + If the COPY is in binary format *buffer* must be `!bytes`. In text mode + it can be either `!bytes` or `!str`. + """ conn = self.connection conn.wait(copy_to(conn.pgconn, self._ensure_bytes(buffer)))