From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 14 Nov 2020 19:20:38 +0000 (+0000)
Subject: Document COPY differences and async use
X-Git-Tag: 3.0.dev0~359
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=922aacfb4e3a5882db01b0f64f7a06bc93601bfc;p=thirdparty%2Fpsycopg.git

Document COPY differences and async use
---

diff --git a/docs/conf.py b/docs/conf.py
index f2269993d..772e2efeb 100644
--- 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 32c60e807..130b2445d 100644
--- 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 d1d1f87ab..83934d3cb 100644
--- 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.