Document COPY differences and async use

diff --git a/docs/conf.py b/docs/conf.py
index f2269993d16a8b00d0caf27937e9858b1e70dfc7..772e2efeb337a38f57dd36207b545fe0511900ca 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -71,4 +71,7 @@ html_static_path = ["_static"]
 # The reST default role (used for this markup: `text`) to use for all documents.
 default_role = "obj"
 
-intersphinx_mapping = {"py": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "py": ("https://docs.python.org/3", None),
+    "pg2": ("https://www.psycopg.org/docs/", None),
+}

diff --git a/docs/from_pg2.rst b/docs/from_pg2.rst
index 32c60e80709aa2cb4c19abfe2fb8e97023fadd81..130b2445d9dd64703393c25ba9cd9678d42db325 100644 (file)
--- a/docs/from_pg2.rst
+++ b/docs/from_pg2.rst
@@ -57,6 +57,21 @@ Builtin data types should work as expected; if you have wrapped a custom data
 type you should check the :ref:`Adaptation` topic.
 
 
+Copy is no more file-based
+--------------------------
+
+`psycopg2` exposes :ref:`a few copy methods <pg2:copy>` to interact with
+PostgreSQL :sql:`COPY`. The interface doesn't make easy to load
+dynamically-generated data to the database.
+
+There is now a single `~psycopg3.Cursor.copy()` method, which is similar to
+`~cursor.copy_expert()`, which accepts parameters like `!execute()` and
+returns an object to read/write data, block-wise or record-wise. The different
+usage pattern also enables :sql:`COPY` to be used in async interactions.
+
+See :ref:`copy` for the details.
+
+
 Other differences
 -----------------
 

diff --git a/docs/usage.rst b/docs/usage.rst
index d1d1f87abccc5dd5886555036d135ea449d211e0..83934d3cbd1556ce1804abf17f052e1d90e04b65 100644 (file)
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -206,7 +206,18 @@ produce `!bytes`:
             f.write(data)
 
 Asynchronous operations are supported using the same patterns on an
-`AsyncConnection`.
+`AsyncConnection`. For instance, if `!f` is an object supporting an
+asynchronous `!read()` method and returning :sql:`COPY` data, a fully-async
+copy operation could be:
+
+.. code:: python
+
+    async with (await cursor.copy("COPY data FROM STDIN")) as copy:
+        data = await f.read()
+        if not data:
+            break
+
+        await copy.write(data)
 
 Binary data can be produced and consumed using :sql:`FORMAT BINARY` in the
 :sql:`COPY` command: see :ref:`binary-data` for details and limitations.