📝 Switch to uv for building envs, packaging etc.

* Install different Python versions in parallel including PyPy and
  free-threaded Python 3.13.
* Add tox-uv
* Publishing packages
* Update uv.lock file with a pre-commit hook

Author: veit

docs/apps.rst

@@ -0,0 +1,150 @@
+Apps
+====
+
+App projects are suitable for web servers, scripts and :abbr:`CLI (command line
+interfaces)`. We can also create them with ``uv init --package``:
+
+.. code-block:: console
+
+   $ uv init --package myapp
+   tree mypack -a
+   myapp
+   $ uv init --app myapp
+   $  tree myapp -a
+   myapp
+   ├── .git
+   │   └── ...
+   ├── .gitignore
+   ├── .python-version
+   ├── README.md
+   ├── pyproject.toml
+   └── src
+       └── myapp
+           └── __init__.py
+
+:file:`myapp/pyproject.toml`
+    The :file:`pyproject.toml` file contains a ``scripts`` entry point
+    ``myapp:main``:
+
+    .. literalinclude:: myapp/pyproject.toml
+       :caption: myapp/pyproject.toml
+       :lines: 12-13
+
+:file:`myapp/src/myapp/__init__.py`
+    The module defines a CLI function :func:`main`:
+
+    .. literalinclude:: myapp/src/myapp/__init__.py
+       :caption: myapp/src/myapp/__init__.py
+
+    It can be called up with ``uv run``:
+
+    .. code-block:: console
+
+       $ uv run mypack
+       Hello from myapp!
+
+    Alternatively, you can also build a :ref:`virtual environment <venv>` and
+    then call :func:`main` from Python:
+
+    .. code-block:: console
+
+       $  uv add --dev .
+       Resolved 1 package in 1ms
+       Audited in 0.01ms
+       $ uv run python
+       >>> import myapp
+       >>> 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.
+
+.. _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.
+
+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.
+
+You can also use the
+:doc:`Python4DataScience:productive/git/advanced/hooks/pre-commit` to regularly
+update your uv.lock file:
+
+.. 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
+
+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:
+
+.. code-block:: toml
+
+   [tool.uv]
+   environments = [
+       "sys_platform == 'darwin'",
+       "sys_platform == 'linux'",
+   ]

docs/index.rst

@@ -109,6 +109,7 @@ All tutorials serve as seminar documents for our harmonised training courses:
    functions/index
    modules/index
    libs/index
+   apps
    oop/index
    save-data/index
    dataclasses

docs/install.rst

@@ -29,9 +29,13 @@ installed, this should not be a problem.
       One disadvantage is that you have to return to the website regularly to
       check for security updates as there is no integrated auto-updater.
 
-   If older Python versions are required, for example to test libraries with
-   :doc:`test/tox`, we use `deadsnakes
-   <https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa>`_.
+.. _various-python-versions:
+
+If different Python versions are required, for example to test libraries with
+:doc:`test/tox`, I use `uv <https://docs.astral.sh/uv/guides/install-python/>`_.
+This allows not only older CPython versions to be installed but also  `PyPy
+<https://pypy.org>`_ or free-threaded Python 3.13 with ``uv python install
+[email protected]`` or ``uv python install 3.13t``.
 
 .. tab:: macOS
 

docs/libs/distribution.rst

@@ -9,22 +9,6 @@ uploaded to a package index such as :term:`pypi.org` and installed with
    `cusy seminar: Advanced Python
    <https://cusy.io/en/our-training-courses/advanced-python>`_
 
-Some of the following commands require a new version of pip, so you should make
-sure you have the latest version installed:
-
-
-.. tab:: Linux/macOS
-
-   .. code-block:: console
-
-      $ python3 -m pip install --upgrade pip
-
-.. tab:: Windows
-
-   .. code-block:: ps1
-
-      > python  -m pip install --upgrade pip
-
 Structure
 ---------
 
@@ -453,53 +437,93 @@ For more instructions in :file:`Manifest.in`, see `MANIFEST.in commands
 .. note::
    If you want files and directories from :file:`MANIFEST.in` to be installed as
    well, for example if they are runtime-relevant data, you can specify this
-   with ``include_package_data=True`` in your ``setup()`` call.
+   with ``include_package_data=True`` in your :func:`setup` call.
+
+.. _uv-package-structure:
+
+Create package structure
+------------------------
+
+With :samp:`uv init --package {MYPACK}` you can easily create an initial file
+structure for packages.
+
+.. code-block:: console
+
+   $ uv init --package mypack
+   $  tree mypack -a
+   mypack
+   ├── .git
+   │   └── ...
+   ├── .gitignore
+   ├── .python-version
+   ├── README.md
+   ├── pyproject.toml
+   └── src
+       └── mypack
+           └── __init__.py
+
+:file:`mypack/pyproject.toml`
+    The file :file:`pyproject.toml` contains a ``scripts`` entry point
+    ``mypack:main``:
+
+    .. literalinclude:: mypack/pyproject.toml
+       :caption: mypack/pyproject.toml
+       :emphasize-lines: 12-13
+
+:file:`mypack/src/mypack/__init__.py`
+    The module defines a CLI function :func:`main`:
+
+    .. literalinclude:: mypack/src/mypack/__init__.py
+       :caption: mypack/src/mypack/__init__.py
+
+    It can be called with ``uv run``:
+
+    .. code-block:: console
+
+       $ uv run mypack
+       Hello from mypack!
+
+    .. note::
+       If necessary, ``uv run`` creates a :ref:`virtual Python environment
+       <venv>` in the :file:`.venv` folder before :func:`main` is executed.
+
+.. _uv-build:
 
 Build
 -----
 
 The next step is to create distribution packages for the package. These are
 archives that can be uploaded to the :term:`Python Package Index` (:term:`PyPI`)
-and installed by :term:`pip`.
-
-Make sure you have the latest version of ``build`` installed:
-
-Now run the command in the same directory where :file:`pyproject.toml` is
-located:
+and installed by :term:`pip`. Now execute the command in the same directory
+where :file:`pyproject.toml` is located:
 
 .. tab:: Linux/macOS
 
    .. code-block:: console
 
-      $ python -m pip install build
-      $ cd /PATH/TO/YOUR/DISTRIBUTION_PACKAGE
-      $ rm -rf build dist
-      $ python -m build
+      $ uv build
+      Building source distribution...
+      Building wheel from source distribution...
+        Successfully built dist/mypack-0.1.0.tar.gz and dist/mypack-0.1.0-py3-none-any.whl
 
 .. tab:: Windows
 
    .. code-block:: ps1
 
-      > python -m pip install build
-      > cd C:\PATH\TO\YOUR\DISTRIBUTION_PACKAGE
-      > rm -rf build dist
-      > python -m build
+      > uv build
+      Building source distribution...
+      Building wheel from source distribution...
+        Successfully built dist/mypack-0.1.0.tar.gz and dist/mypack-0.1.0-py3-none-any.whl
 
-The second line ensures that a clean build is created without artefacts from
-previous builds. The third line should output a lot of text and create two files
-in the ``dist`` directory when finished:
+:file:`dist/mypack-0.1.0-py3-none-any.whl`
+    is a build distribution. :term:`pip` prefers to install build distributions
+    and only uses the source distributions if no suitable build distribution is
+    available. You should always upload a source distribution and provide build
+    distributions for the platforms with which your project is compatible. In
+    this case, our example package is compatible with Python on every platform,
+    so only one build distribution is required:
 
-.. code-block:: console
-
-   dist
-   ├── dataprep-0.1.0-py3-none-any.whl
-   └── dataprep-0.1.0.tar.gz
-
-:file:`dataprep-0.1.0-py3-none-any.whl`
-    is a binary distribution format with the suffix :file:`..whl`, where the
-    filename is composed as follows:
-
-    ``dataprep``
+    ``mypack``
         is the normalised package name
     ``0.1.0``
         is the version of the distribution package
@@ -514,16 +538,14 @@ in the ``dist`` directory when finished:
         other hand only for chips with the x86 instruction set and a 64-bit
         architecture
 
-:file:`dataprep-0.1.0.tar.gz`
+:file:`mypack-0.1.0.tar.gz`
     is a :term:`source distribution`.
 
 .. seealso::
-   The reference for the file names can be found in `File name convention
-   <https://peps.python.org/pep-0427/#file-name-convention>`_.
-
-   For more information on ``sdist``, see `Creating a Source Distribution
-   <https://docs.python.org/2/distutils/sourcedist.html#creating-a-source-distribution>`__
-   and :pep:`376`.
+   For more information on ``sdist``, see `Core metadata specifications
+   <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_
+   and `PyPA specifications
+   <https://packaging.python.org/en/latest/specifications/>`_.
 
 Testing
 -------