Simplify psycopg requirements guidance #162

Trim the requirements-psycopg section to the page's operational register:
drop the per-extra rationale, the runtime-preference exposition, the
startup-import note and the boxed admonitions, keeping the extras, the
three-file base layout, the pre-commit hooks and the lint.yml line.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013mEwtfE72tX2eUWEHJb1Zs

Author: jpmckinney

docs/docker/django.rst

@@ -46,7 +46,7 @@ When using the ``gthreads`` worker class, a main thread `handles the heartbeat <
 Number of threads
 ~~~~~~~~~~~~~~~~~
 
-Ensure your code is thread safe. Notably, `psycopg cursors are not thread safe <https://www.psycopg.org/psycopg3/docs/api/cursors.html>`__, though this isn't a concern for typical usage of `Django <https://docs.djangoproject.com/en/5.2/ref/databases/>`__.
+Ensure your code is thread safe. Notably, `psycopg cursors are not thread safe <https://www.psycopg.org/psycopg3/docs/advanced/async.html>`__, though this isn't a concern for typical usage of `Django <https://docs.djangoproject.com/en/5.2/ref/databases/>`__.
 
 `When using threads <https://docs.gunicorn.org/en/stable/design.html#how-many-threads>`__, the application is loaded by the worker and some memory is shared between its threads (thus consuming less memory than additional workers would).
 

docs/python/preferences.rst

@@ -29,11 +29,11 @@ Command-line interface
 DataFrames
   `Polars <https://pola.rs>`__, unless end-users are unfamiliar (`pandas <https://pandas.pydata.org/docs/>`__).
 Object Relational Mapper (ORM)
-  Django. If you don't need an ORM, use `psycopg <https://www.psycopg.org/psycopg3/docs/>`__ (psycopg 3). Do not use `SQLAlchemy <https://www.sqlalchemy.org/>`__, except with FastAPI or in low-level libraries with limited scope *where an ORM is needed*.
+  Django. If you don't need an ORM, use `psycopg <https://www.psycopg.org/psycopg3/docs/>`__. Do not use `SQLAlchemy <https://www.sqlalchemy.org/>`__, except with FastAPI or in low-level libraries with limited scope *where an ORM is needed*.
 
   .. note::
 
-     Use ``psycopg[c]`` in production and ``psycopg[binary]`` in development. :ref:`See instructions<requirements-psycopg>`.
+     Use ``psycopg[c]`` in production and ``psycopg[binary]`` in development, `as recommended and preferred <https://www.psycopg.org/psycopg3/docs/basic/install.html#local-installation>`__. :ref:`See instructions<requirements-psycopg>`.
 
 HTTP client
   `Requests <https://docs.python-requests.org/en/latest/>`__ for synchronous code and `niquests <https://niquests.readthedocs.io/en/latest/>`__ for asynchronous code, unless a framework uses another, like Scrapy (Twisted).

docs/python/requirements.rst

@@ -37,8 +37,6 @@ The requirements of *applications* (not :doc:`packages<packages>`) are managed b
 -  ``requirements.txt`` names all direct and indirect requirements needed in the production environment, all locked to specific versions by `uv <https://docs.astral.sh/uv/>`__.
 -  ``requirements_dev.txt`` names all direct and indirect requirements needed in the development environment, all locked to specific versions by ``uv``.
 
-Projects that install a different build of the same package in production and development – notably :ref:`psycopg<requirements-psycopg>` – add two more files, ``requirements_base.in`` and ``requirements_base.txt``, to hold the shared requirements.
-
 This ensures that:
 
 -  All environments use the same versions of production requirements, to ensure consistent and replicable deployments and to avoid errors or surprises during or after deployment due to differences between versions (e.g. a new version of Django requires upgrading application code).
@@ -116,36 +114,18 @@ If the project has a :ref:`requirements_base.in<requirements-psycopg>`, add shar
 psycopg
 ~~~~~~~
 
-`psycopg <https://www.psycopg.org/psycopg3/docs/>`__ (psycopg 3) replaces ``psycopg2``.
-
-``psycopg2`` and ``psycopg2-binary`` were two distributions of the same import name, so installing the binary distribution shadowed a source build. psycopg 3 is instead a **single package with extras**, which install differently-named modules:
-
-``psycopg``
-   Pure Python. Requires the ``libpq`` library at runtime.
-``psycopg[c]``
-   Compiled against the system ``libpq``. Requires a C compiler and the ``libpq`` development files at install time. This is the fast, faithful successor to a source-built ``psycopg2``.
-``psycopg[binary]``
-   A self-contained wheel that bundles ``libpq``. Requires no build step.
-
-At runtime, psycopg prefers the C implementation, then the binary, then the pure Python implementation. The old approach of inheriting the production lock and adding the binary distribution on top therefore **no longer selects the binary build**.
+Use `psycopg <https://www.psycopg.org/psycopg3/docs/>`__ (psycopg 3), not the older ``psycopg2``. It is a single package with extras: use ``psycopg[c]`` (compiled against the system ``libpq``) in production, and ``psycopg[binary]`` (a self-contained wheel) in development, keeping the ``psycopg`` version in sync.
 
-Instead, use ``psycopg[c]`` in production and ``psycopg[binary]`` in development (the build-free equivalent of ``psycopg2-binary``), keeping the core ``psycopg`` version in sync across the locked files.
-
-Three-tier layout
-^^^^^^^^^^^^^^^^^^
-
-Because each lock file is compiled independently, shared transitive dependencies can resolve to different versions unless they share a locked base. Split the requirements into three tiers:
+Unlike ``psycopg2`` and ``psycopg2-binary``, the extras install different modules, so you can't add the binary build on top of the production lock. Instead, share a locked base across three files:
 
 ``requirements_base.in``
-   The shared direct requirements (everything except psycopg). Compiles to ``requirements_base.txt``.
+   The requirements shared by both environments (everything except psycopg).
 ``requirements.in``
    ``-r requirements_base.txt`` and ``psycopg[c]``.
 ``requirements_dev.in``
    ``-r requirements_base.txt``, ``psycopg[binary]`` and the development-only tools.
 
-Both downstream files reference the locked ``requirements_base.txt`` (not ``requirements_base.in``), mirroring how ``requirements_dev.in`` references the locked ``requirements.txt``.
-
-Configure three ``pip-compile`` pre-commit hooks, base first, with ``files:`` patterns so that changing the base re-triggers the dependent locks:
+Compile the base first, so that the downstream locks pick up its versions. Order the ``pip-compile`` pre-commit hooks accordingly, and set ``files:`` patterns so that changing the base re-triggers the dependent locks:
 
 .. code-block:: yaml
    :caption: .pre-commit-config.yaml
@@ -163,33 +143,21 @@ Configure three ``pip-compile`` pre-commit hooks, base first, with ``files:`` pa
      args: [requirements_dev.in, -o, requirements_dev.txt]
      files: ^requirements(_base|_dev)?\.(in|txt)$
 
-Add the new file to the :ref:`requirements check<linting-ci>` in ``lint.yml``, so that it is not reported as missing:
+Add ``requirements_base.in`` to the :ref:`requirements check<linting-ci>` in ``lint.yml``:
 
 .. code-block:: yaml
    :caption: .github/workflows/lint.yml
 
    with:
      standard-maintenance-scripts-files: requirements_base.in
 
-.. attention::
-
-   Introducing ``requirements_base.txt`` makes the resolver re-pin every shared dependency, unless it is anchored to the existing lock. Compile the base against the pre-change ``requirements.txt``, and do not pass ``-U``/``--upgrade``:
-
-   .. code-block:: bash
-
-      uv pip compile -c requirements.txt requirements_base.in -o requirements_base.txt
-      uv pip compile requirements.in -o requirements.txt
-      uv pip compile requirements_dev.in -o requirements_dev.txt
-
-   The committed diff for a psycopg upgrade should touch only psycopg. Reviewers should reject incidental version bumps to other packages.
-
 .. note::
 
-   If a module that imports psycopg is loaded unconditionally at startup, the application needs a working psycopg just to run. Because ``requirements.txt`` pins ``psycopg[c]``, installing it requires a build toolchain even in development – and ``pip install "psycopg[binary]" -r requirements.txt`` does not help, because the pinned ``psycopg-c`` must still build. Instead, install the binary build against the base, which contains no psycopg:
+   When first adding ``requirements_base.txt``, compile it against the existing lock, so that the diff touches only psycopg and not unrelated packages:
 
    .. code-block:: bash
 
-      pip install "psycopg[binary]" -r requirements_base.txt
+      uv pip compile -c requirements.txt requirements_base.in -o requirements_base.txt
 
 Install requirements
 --------------------

docs/services/postgresql.rst

@@ -10,7 +10,7 @@ Connect to a database
 
 Connect to the database using a connection string stored in the ``DATABASE_URL`` environment variable.
 
-In Python, connect to the database using `dj-database-url <https://github.com/kennethreitz/dj-database-url#readme>`__ if using :doc:`Django<../python/django>`, or `psycopg <https://www.psycopg.org/psycopg3/docs/api/connections.html#psycopg.Connection.connect>`__ otherwise. See :ref:`requirements<requirements-psycopg>` for how to declare and install psycopg.
+In Python, connect to the database using `dj-database-url <https://github.com/kennethreitz/dj-database-url#readme>`__ if using :doc:`Django<../python/django>`, or `psycopg <https://www.psycopg.org/psycopg3/docs/api/connections.html#psycopg.Connection.connect>`__ otherwise.
 
 To set the search path for a PostgreSQL connection, append to the connection string:
 
@@ -66,15 +66,6 @@ Load (or dump) data
 
 Use the `\copy <https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-META-COMMANDS-COPY>`__ meta-command instead of the `COPY <https://www.postgresql.org/docs/current/sql-copy.html>`__ command, so that file accessibility and privileges are those of the user, not the server – such that no SQL superuser privileges are required.
 
-In Python, psycopg 3 removed the ``copy_expert()``, ``copy_from()`` and ``copy_to()`` methods. Use the `cursor.copy() <https://www.psycopg.org/psycopg3/docs/basic/copy.html>`__ context manager instead, writing the file in blocks:
-
-.. code-block:: python
-
-   with open(filename, "rb") as f:
-       with cur.copy("COPY mytable (data) FROM stdin") as copy:
-           while block := f.read(65536):
-               copy.write(block)
-
 .. _sql-statements:
 
 Construct SQL statements