📝 Update uv sections

* Reproducing and updating uv environments

Author: veit

CHANGELOG.rst

@@ -32,6 +32,10 @@ Added
 Changed
 ~~~~~~~
 
+* 📝 Update uv sections
+
+  * Reproducing and updating uv environments
+
 * 📝 Update conda term
 * 📝 Update GitLab package registry
 * 📝 Expand the pytest plugins section

docs/appendix/glossary.rst

@@ -529,16 +529,17 @@ Glossary
        uv greatly simplifies the development and deployment of Python projects:
 
        * :ref:`Installation <uv>`
-       * :doc:`Python environments
-         <Python4DataScience:productive/envs/uv/index>`
-       * :ref:`uv-package-structure`
+       * :ref:`Create packages <uv-package-structure>` and publish them on
+         :doc:`PyPI <../packs/publish>` or :doc:`GitLab <../packs/gitlab>`
        * :doc:`Developing applications <../packs/apps>`
        * Testing libraries with different :ref:`Python versions
          <various-python-versions>` and :ref:`tox_uv`
+       * :ref:`Reproducing <reproduce-virtual-env>` and :ref:`updating
+         <update-uv-lock>` the Python environment, if necessary also with a
+         :doc:`Python4DataScience:productive/envs/uv/dependency-bot`
        * :doc:`Python4DataScience:productive/envs/uv/cicd`
        * :doc:`Python4DataScience:productive/envs/uv/docker`
-       * Publishing packages on :doc:`PyPI <../packs/publish>` and
-         :doc:`GitLab <../packs/gitlab>`
+       * Check vulnerabilities with :ref:`uv-secure <check-vulnerabilities>`
 
        .. seealso::
           * `Docs <https://docs.astral.sh/uv/>`__

docs/packs/apps.rst

@@ -22,6 +22,16 @@ interfaces)`. We can also create them with ``uv init --package``:
        └── myapp
            └── __init__.py
 
+.. note::
+   I strongly believe that a Python application should be properly packaged to
+   enjoy the many benefits, such as
+
+   * source management with :doc:`importlib <python3:library/importlib>`
+   * executable scripts with ``project.scripts`` instead of attached
+     :file:`scripts` folders
+   * the benefits of :file:`src` layout with a common, documented and well
+     understood structure.
+
 :file:`myapp/pyproject.toml`
     The :file:`pyproject.toml` file contains a ``scripts`` entry point
     ``myapp:main``:
@@ -56,90 +66,88 @@ interfaces)`. We can also create them with ``uv init --package``:
        >>> myapp.main()
        Hello from myapp!
 
-.. note::
-   I strongly believe that a Python application should be properly packaged to
-   enjoy the many benefits, such as
-
-   * source management with :doc:`importlib <python3:library/importlib>`
-   * executable scripts with ``project.scripts`` instead of attached
-     :file:`scripts` folders
-   * the benefits of :file:`src` layout with a common, documented and well
-     understood structure.
-
 .. _uv_lock:
 
 :file:`uv.lock` file
---------------------
-
-With ``uv add --dev .`` the :file:`uv.lock` file was also created alongside the
-:file:`pyproject.toml` file. :file:`uv.lock` is a cross-platform lock file that
-records the packages that are to be installed across all possible Python
-features such as operating system, architecture and Python version.
-
-Unlike :file:`pyproject.toml`, which specifies the general requirements of your
-project, :file:`uv.lock` contains the exact resolved versions that are installed
-in the project environment. This file should be checked into the :doc:`Git
-<Python4DataScience:productive/git/index>` version control system to enable
-consistent and reproducible installations on different computers.
-
-.. literalinclude:: myapp/uv.lock
-   :caption: myapp/uv.lock
-
-:file:`uv.lock` is a human-readable
-:doc:`Python4DataScience:data-processing/serialisation-formats/toml/index` file,
-but is managed by ``uv`` and should not be edited manually.
-
-.. note::
-   If ``uv`` is to be integrated into other tools or workflows, you can export
-   the content to the `requirements file format
-   <https://pip.pypa.io/en/stable/reference/requirements-file-format/>`_ using
-   :samp:`uv export --format requirements-txt > {CONSTRAINTS.TXT}`. Conversely,
-   the :samp:`{CONSTRAINTS.TXT}` file created can then be used with ``uv pip
-   install`` or other tools.
+    With ``uv add --dev .`` the :file:`uv.lock` file was also created alongside
+    the :file:`pyproject.toml` file. :file:`uv.lock` is a cross-platform lock
+    file that records the packages that are to be installed across all possible
+    Python features such as operating system, architecture and Python version.
+
+    Unlike :file:`pyproject.toml`, which specifies the general requirements of
+    your project, :file:`uv.lock` contains the exact resolved versions that are
+    installed in the project environment. This file should be checked into the
+    :doc:`Git <Python4DataScience:productive/git/index>` version control system
+    to enable consistent and reproducible installations on different computers.
+
+    .. literalinclude:: myapp/uv.lock
+       :caption: myapp/uv.lock
+
+    :file:`uv.lock` is a human-readable
+    :doc:`Python4DataScience:data-processing/serialisation-formats/toml/index`
+    file, but is managed by ``uv`` and should not be edited manually.
+
+    .. note::
+       If ``uv`` is to be integrated into other tools or workflows, you can
+       export the content to the `requirements file format
+       <https://pip.pypa.io/en/stable/reference/requirements-file-format/>`_
+       using :samp:`uv export --format requirements-txt > {CONSTRAINTS.TXT}`.
+       Conversely, the :samp:`{CONSTRAINTS.TXT}` file created can then be used
+       with ``uv pip install`` or other tools.
+
+.. _reproduce-virtual-env:
+
+Reproducing the Python environment
+----------------------------------
+
+In production environments, you should always use exactly the versions that have
+been tested. You can use ``uv sync --locked`` in your environment to ensure that
+the :file:`uv.lock` file matches the project metadata. Otherwise an error
+message will be displayed.
+
+You can then use ``uv sync --frozen`` in the production environment to ensure
+that the versions of  :file:`uv.lock` are used as the source of truth, but if
+the  :file:`uv.lock` file is missing in the production environment, ``uv sync
+--frozen`` will terminate with an error. Finally, changes to dependencies in the
+:file:`pyproject.toml` file are ignored if they are not yet written to the
+:file:`uv.lock` file.
+
+If you want to use ``uv run`` in a productive environment, the ``--no-sync``
+option prevents the environment from being updated.
 
 .. _update-uv-lock:
 
-Aktualisieren von :file:`uv.lock`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:file:`uv.lock` is updated regularly when ``uv sync`` and ``uv run`` are called.
-
-``--frozen``
-    leaves the :file:`uv.lock file` unchanged.
-``--no-sync``
-    avoids updating the environment during ``uv run`` calls.
-``--locked``
-    ensures that the lock file matches the project metadata. If the lockfile is
-    not up-to-date, an error message is issued instead of updating the lockfile.
+Updating the Python environment
+-------------------------------
 
 By default, ``uv`` favours the locked versions of the packages when executing
 ``uv sync`` and ``uv lock``. Package versions are only changed if the dependency
 conditions of the project exclude the previous, locked version.
 
-``uv lock --upgrade``
-    updates all packages.
-:samp:`uv lock --upgrade-package {PACKAGE}=={VERSION}`
-    upgrades a single package to a specific version.
+With ``uv lock --upgrade`` you can upgrade all packages and with :samp:`uv lock
+--upgrade-package {PACKAGE}=={VERSION}` you can upgrade individual packages to a
+specific version.
 
-You can also use the
-:doc:`Python4DataScience:productive/git/advanced/hooks/pre-commit` to regularly
-update your uv.lock file:
+.. tip::
+   You can also use the
+   :doc:`Python4DataScience:productive/git/advanced/hooks/pre-commit` to
+   regularly update your :file:`uv.lock` file:
 
-.. code-block:: yaml
-   :caption: .pre-commit-config.yaml
+   .. code-block:: yaml
+      :caption: .pre-commit-config.yaml
 
-   - repo: https://github.com/astral-sh/uv-pre-commit
-     rev: 0.4.24
-     hooks:
-       - id: uv-lock
+      - repo: https://github.com/astral-sh/uv-pre-commit
+        rev: 0.5.21
+        hooks:
+          - id: uv-lock
 
 Restrict platform and Python versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 If your project only supports a limited number of platforms or Python versions,
-you can do this in the :file:`pyprojects.toml` file in compliance with
-:pep:`508`, for example to restrict the :file:`uv.lock` file to macOS and Linux
-only:
+you can do this in the :file:`pyprojects.toml` file :pep:`508` compliant, for
+example to restrict your project to macOS and Linux only you can add the
+following section in your :file:`pyproject.toml` file:
 
 .. code-block:: toml