From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 14 Jul 2021 00:46:50 +0000 (+0200)
Subject: Move "from psycopg2" docs page under basic
X-Git-Tag: 3.0.dev1~9
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=cb29d7222355e031703bbedb509a3c5075158fcf;p=thirdparty%2Fpsycopg.git

Move "from psycopg2" docs page under basic

And tweak it a bit.
---

diff --git a/docs/from_pg2.rst b/docs/basic/from_pg2.rst
similarity index 71%
rename from docs/from_pg2.rst
rename to docs/basic/from_pg2.rst
index 765d71638..6e569061a 100644
--- a/docs/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -1,6 +1,9 @@
 .. index::
     pair: psycopg2; Differences
 
+.. currentmodule:: psycopg
+
+
 Differences from ``psycopg2``
 =============================
 
@@ -62,8 +65,14 @@ The adaptation system has been completely rewritten, in order to address
 server-side parameters adaptation, but also to consider performance,
 flexibility, ease of customization.
 
-Builtin data types should work as expected; if you have wrapped a custom data
-type you should check the :ref:`adaptation` topic.
+The behaviour with builtin data should be as expected; if you have customised
+the way to adapt data, or you have your own extension types, you should look
+at the new objects involved in adaptation.
+
+.. seealso::
+
+    - :ref:`types-adaptation` for the basic behaviour.
+    - :ref:`adaptation` for more advanced use.
 
 
 .. _diff-copy:
@@ -75,12 +84,12 @@ Copy is no more file-based
 PostgreSQL :sql:`COPY`. The interface doesn't make easy to load
 dynamically-generated data to the database.
 
-There is now a single `~psycopg.Cursor.copy()` method, which is similar to
+There is now a single `~Cursor.copy()` method, which is similar to
 `!psycopg2` `!copy_expert()` in accepting a free-form :sql:`COPY` command 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.
+.. seealso:: See :ref:`copy` for the details.
 
 
 .. _diff-with:
@@ -88,11 +97,20 @@ See :ref:`copy` for the details.
 ``with`` connection
 -------------------
 
-When the connection is used as context manager, at the end of the context
-the connection will be closed. In `!psycopg2` only the transaction is closed,
-so a connection can be used in several contexts, but the behaviour is
-surprising for people used to several other Python classes wrapping
-resources, such as files.
+In `!psycopg2`, using the syntax :ref:`with connection <pg2:with>`,
+only the transaction is closed, not the connection. This behaviour is
+surprising for people used to several other Python classes wrapping resources,
+such as files.
+
+In psycopg3, using :ref:`with connection <with-connection>` will close the
+connection at the end of the `!with` block, making handling the connection
+resources more familiar.
+
+In order to manage transactions as blocks you can use the
+`Connection.transaction()` method, which allows for finer control, for
+instance to use nested transactions.
+
+.. seealso:: See :ref:`transaction-block` for details.
 
 
 .. _diff-callproc:
@@ -100,11 +118,10 @@ resources, such as files.
 ``callproc()`` is gone
 ----------------------
 
-`cursor.callproc()` is not implemented. The method has a simplistic
-semantic which doesn't account for PostgreSQL positional parameters,
-procedures, set-returning functions. Use a normal
-`~psycopg.Cursor.execute()` with :sql:`SELECT function_name(...)` or
-:sql:`CALL procedure_name(...)` instead.
+`cursor.callproc()` is not implemented. The method has a simplistic semantic
+which doesn't account for PostgreSQL positional parameters, procedures,
+set-returning functions... Use a normal `~Cursor.execute()` with :sql:`SELECT
+function_name(...)` or :sql:`CALL procedure_name(...)` instead.
 
 
 What's new in Psycopg 3
diff --git a/docs/basic/index.rst b/docs/basic/index.rst
index 32f04e1eb..33f78ff9a 100644
--- a/docs/basic/index.rst
+++ b/docs/basic/index.rst
@@ -17,3 +17,4 @@ the database <usage>` or :ref:`loading data using COPY <copy>`.
     adapt
     transactions
     copy
+    from_pg2
diff --git a/docs/index.rst b/docs/index.rst
index 5ec0769c5..f4c4a1752 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -29,7 +29,6 @@ Documentation
     basic/index
     advanced/index
     api/index
-    from_pg2
 
 
 Indices and tables