Reword the requirements_base starter sentence #162

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, `psycopg2 cursors are not thread safe <https://www.psycopg.org/docs/cursor.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/docker/dockerfile.rst

@@ -96,7 +96,7 @@ Set ``server_tokens off;`` to prevent false positives from penetration tests (Ub
 System packages
 ---------------
 
-Before installing a system package, check whether it's included in a base image. For example, the ``psycopg2`` Python package `requires <https://www.psycopg.org/install/>`__ the ``libpq-dev`` system package. To check whether it's included, when using the `python:3.14 image <https://hub.docker.com/_/python>`__:
+Before installing a system package, check whether it's included in a base image. For example, the ``psycopg[c]`` Python package `requires <https://www.psycopg.org/psycopg3/docs/basic/install.html#local-installation>`__ the ``libpq-dev`` system package to build. To check whether it's included, when using the `python:3.14 image <https://hub.docker.com/_/python>`__:
 
 #. Find the tag on the DockerHub page of the base image (the ``3.14`` tag is under *Shared Tags*)
 #. Click the link to view the Dockerfile

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 `psycopg2 <https://www.psycopg.org/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*.
+  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 ``psycopg2`` in production, not ``psycopg2-binary``, `as recommended <https://www.psycopg.org/docs/install.html#psycopg-vs-psycopg-binary>`__. :ref:`See instructions<requirements-psycopg2>`.
+     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

@@ -63,6 +63,10 @@ A common starter ``requirements.in`` for :doc:`django` is:
 
 .. literalinclude:: ../../cookiecutter-django/{{cookiecutter.project_slug}}/requirements.in
 
+Its shared requirements live in ``requirements_base.in``, which the starter splits out because it uses :ref:`psycopg<requirements-psycopg>`:
+
+.. literalinclude:: ../../cookiecutter-django/{{cookiecutter.project_slug}}/requirements_base.in
+
 A common starter ``requirements_dev.in`` is:
 
 .. literalinclude:: ../../cookiecutter-django/{{cookiecutter.project_slug}}/requirements_dev.in
@@ -97,20 +101,63 @@ Add the requirement in alphabetical order to the appropriate ``.in`` file. Then,
 
    :doc:`preferences`
 
-.. _requirements-psycopg2:
+.. _requirements-psycopg:
+
+psycopg
+~~~~~~~
+
+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.
+
+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 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.
+
+When you add or upgrade a requirement shared by both environments, edit ``requirements_base.in`` and compile base-first, so that the downstream locks pick up its versions:
+
+.. code-block:: bash
+
+   uv pip compile 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
+
+Order the ``pip-compile`` pre-commit hooks the same way, and set ``files:`` patterns so that changing the base re-triggers the dependent locks:
+
+.. code-block:: yaml
+   :caption: .pre-commit-config.yaml
 
-psycopg2
-~~~~~~~~
+   - id: pip-compile
+     name: pip-compile requirements_base.in
+     args: [requirements_base.in, -o, requirements_base.txt]
+     files: ^requirements_base\.(in|txt)$
+   - id: pip-compile
+     name: pip-compile requirements.in
+     args: [requirements.in, -o, requirements.txt]
+     files: ^requirements(_base)?\.(in|txt)$
+   - id: pip-compile
+     name: pip-compile requirements_dev.in
+     args: [requirements_dev.in, -o, requirements_dev.txt]
+     files: ^requirements(_base|_dev)?\.(in|txt)$
 
-``psycopg2`` is `recommended <https://www.psycopg.org/docs/install.html#psycopg-vs-psycopg-binary>`__ for production. However, installing ``psycopg2`` for development can be difficult on operating systems like macOS. In that case, you can:
+Add ``requirements_base.in`` to the :ref:`requirements check<linting-ci>` in ``lint.yml``:
 
--  Put ``psycopg2`` in ``requirements.in``
--  Put ``psycopg2-binary`` in ``requirements_dev.in``
--  Run: ``pip install psycopg2-binary``
+.. code-block:: yaml
+   :caption: .github/workflows/lint.yml
+
+   with:
+     standard-maintenance-scripts-files: requirements_base.in
 
 .. note::
 
-   You **must** keep the locked versions of psycopg2 and psycopg2-binary in sync.
+   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
+
+      uv pip compile -c requirements.txt requirements_base.in -o requirements_base.txt
 
 Install requirements
 --------------------

docs/services/postgresql.rst

@@ -10,12 +10,12 @@ 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 `psycopg2 <https://www.psycopg.org/docs/module.html#psycopg2.connect>`__ otherwise.
+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:
 
 .. code-block:: none
-   :caption: psycopg2
+   :caption: psycopg
 
    ?options=-csearch_path%3Dmyschema,public
 
@@ -79,9 +79,9 @@ Construct SQL statements
 
    `GitLab SQL Style Guide <https://handbook.gitlab.com/handbook/enterprise-data/platform/sql-style-guide/>`__
 
-Follow `best practices <https://www.psycopg.org/docs/usage.html#sql-injection>`__ to avoid accidental errors and `SQL injection <https://en.wikipedia.org/wiki/SQL_injection>`__. The code samples below use the psycopg2 Python package.
+Follow `best practices <https://www.psycopg.org/psycopg3/docs/basic/params.html>`__ to avoid accidental errors and `SQL injection <https://en.wikipedia.org/wiki/SQL_injection>`__. The code samples below use the psycopg Python package.
 
--  `Pass parameters to SQL queries <https://www.psycopg.org/docs/usage.html#passing-parameters-to-sql-queries>`__, using the second argument to the ``execute`` method. This adapts the Python value's type (like ``bool``, ``int``, ``str``) to the correct SQL representation:
+-  `Pass parameters to SQL queries <https://www.psycopg.org/psycopg3/docs/basic/params.html>`__, using the second argument to the ``execute`` method. This adapts the Python value's type (like ``bool``, ``int``, ``str``) to the correct SQL representation:
 
    .. code-block:: python
 
@@ -131,11 +131,11 @@ Follow `best practices <https://www.psycopg.org/docs/usage.html#sql-injection>`_
           SELECT * FROM record WHERE collection_id = %s AND ocid = %s
       """, (1, 1, 'ocds-213czf-1'))  # AVOID
 
--  If you are writing a query template in which you want to substitute column names or table names, use the ``format`` method and the ``SQL`` and ``Identifier`` classes (`documentation <https://www.psycopg.org/docs/sql.html>`__):
+-  If you are writing a query template in which you want to substitute column names or table names, use the ``format`` method and the ``SQL`` and ``Identifier`` classes (`documentation <https://www.psycopg.org/psycopg3/docs/api/sql.html>`__):
 
    .. code-block:: python
 
-      from psycopg2.sql import SQL, Identifier
+      from psycopg.sql import SQL, Identifier
 
       cur.execute(SQL("SELECT * FROM {table}").format(table=Identifier('collection')))