Add pyproject.toml, use uv (#183)

* Add pyproject.toml

* Require Python 3.11, change installation instructions to using "uv"

... and use it for CI as well.

Author: mgeier

.github/workflows/test.yml

@@ -2,6 +2,9 @@ name: Test
 
 on: [push, pull_request]
 
+env:
+  UV_PYTHON_DOWNLOADS: never
+
 jobs:
   build:
 
@@ -10,13 +13,15 @@ jobs:
       matrix:
         os: [ubuntu-latest, macOS-latest, windows-latest]
         python-version: ['3.11', '3.12']
-        
+
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
     - name: Prepare Ubuntu
       run: |
         sudo apt-get update
@@ -30,16 +35,14 @@ jobs:
       if: matrix.os == 'windows-latest'
     - name: Install dependencies
       run: |
-        python -V
-        python -m pip install --upgrade pip
-        python -m pip install .
-        python -m pip install -r tests/requirements.txt
-        python -m pip install -r doc/requirements.txt
+        uv sync --locked
+        uv pip install -r tests/requirements.txt
+        uv pip install -r doc/requirements.txt
         # This is needed in example scripts:
-        python -m pip install pillow
+        uv pip install pillow
     - name: Test
-      run: python -m pytest
+      run: uv run --locked -m pytest
     - name: Test examples
-      run: python doc/examples/run_all.py
+      run: uv run --locked --script doc/examples/run_all.py
     - name: Test documentation
-      run: python -m sphinx doc/ _build/ -b doctest
+      run: uv run --locked -m sphinx doc/ _build/ -b doctest

CONTRIBUTING.rst

@@ -14,12 +14,17 @@ newest development version from Github_::
 
    git clone https://github.com/sfstoolbox/sfs-python.git
    cd sfs-python
-   python3 -m pip install --user -e .
+   uv sync
 
-... where ``-e`` stands for ``--editable``.
+This creates a virtual environment where the latest development version
+of the SFS Toolbox is installed.
+Note that you can activate this environment from any directory
+(e.g. one where you have some Python scripts using the ``sfs`` module),
+it doesn't have to be the directory where you cloned the Git repository.
 
-This way, your installation always stays up-to-date, even if you pull new
-changes from the Github repository.
+Wherever you activate that environment from,
+it will always stay up-to-date, even if you pull new
+changes from the Github repository or switch branches.
 
 .. _PyPI: https://pypi.org/project/sfs/
 .. _Github: https://github.com/sfstoolbox/sfs-python/
@@ -30,37 +35,31 @@ Building the Documentation
 
 If you make changes to the documentation, you can re-create the HTML pages
 using Sphinx_.
-You can install it and a few other necessary packages with::
+From the main ``sfs-python`` directory,
+you can install it and a few other necessary packages with::
 
-   python3 -m pip install -r doc/requirements.txt --user
+   uv pip install -r doc/requirements.txt
 
 To create the HTML pages, use::
 
-   python3 setup.py build_sphinx
+   uv run -m sphinx doc _build
 
-The generated files will be available in the directory ``build/sphinx/html/``.
-
-To create the EPUB file, use::
-
-   python3 setup.py build_sphinx -b epub
-
-The generated EPUB file will be available in the directory
-``build/sphinx/epub/``.
+The generated files will be available in the directory ``_build/``.
 
 To create the PDF file, use::
 
-   python3 setup.py build_sphinx -b latex
+   uv run -m sphinx doc _build -b latex
 
-Afterwards go to the folder ``build/sphinx/latex/`` and run LaTeX to create the
+Afterwards go to the folder ``_build/`` and run LaTeX to create the
 PDF file. If you don’t know how to create a PDF file from the LaTeX output, you
 should have a look at Latexmk_ (see also this `Latexmk tutorial`_).
 
 It is also possible to automatically check if all links are still valid::
 
-   python3 setup.py build_sphinx -b linkcheck
+   uv run -m sphinx doc _build -b linkcheck
 
 .. _Sphinx: http://sphinx-doc.org/
-.. _Latexmk: http://personal.psu.edu/jcc8/software/latexmk-jcc/
+.. _Latexmk: https://www.cantab.net/users/johncollins/latexmk/
 .. _Latexmk tutorial: https://mg.readthedocs.io/latexmk.html
 
 Running the Tests
@@ -69,11 +68,11 @@ Running the Tests
 You'll need pytest_ for that.
 It can be installed with::
 
-   python3 -m pip install -r tests/requirements.txt --user
+   uv pip install -r tests/requirements.txt
 
 To execute the tests, simply run::
 
-   python3 -m pytest
+   uv run -m pytest
 
 .. _pytest: https://pytest.org/
 

MANIFEST.in

@@ -15,8 +15,8 @@ License:
     MIT -- see the file ``LICENSE`` for details.
 
 Quick start:
-    * Install Python 3, NumPy, SciPy and Matplotlib
-    * ``python3 -m pip install sfs --user``
+    * Install Python and (optionally) Matplotlib
+    * Install the ``sfs`` package for Python
     * Check out the examples in the documentation
 
 More information about the underlying theory can be found at

README.rst

@@ -5,40 +5,51 @@ Requirements
 ------------
 
 Obviously, you'll need Python_.
-More specifically, you'll need Python 3.
-NumPy_ and SciPy_ are needed for the calculations.
-If you want to use the provided functions for plotting sound fields, you'll need
-Matplotlib_.
-However, since all results are provided as plain NumPy_ arrays, you should also
-be able to use any plotting library of your choice to visualize the sound
-fields.
+There are many ways to install Python,
+and you can use any way you like,
+however, we recommend using uv_ as shown in the steps below.
 
-Instead of installing all of the requirements separately, you should probably
-get a Python distribution that already includes everything, e.g. Anaconda_.
+You can install ``uv`` with your favorite package manager,
+or by one of the other methods described at
+https://docs.astral.sh/uv/getting-started/installation/.
 
 .. _Python: https://www.python.org/
+.. _uv: https://docs.astral.sh/uv/
 .. _NumPy: http://www.numpy.org/
 .. _SciPy: https://www.scipy.org/scipylib/
 .. _Matplotlib: https://matplotlib.org/
-.. _Anaconda: https://docs.anaconda.com/anaconda/
 
 Installation
 ------------
 
-Once you have installed the above-mentioned dependencies, you can use pip_
-to download and install the latest release of the Sound Field Synthesis Toolbox
-with a single command::
+First, create a new directory wherever you want, change into it, then run::
+
+    uv venv
 
-    python3 -m pip install sfs --user
+This will print instructions for how to `activate the environment`__.
+You should do that now!
 
-If you want to install it system-wide for all users (assuming you have the
-necessary rights), you can just drop the ``--user`` option.
+__ https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment
 
-To un-install, use::
+The Sound Field Synthesis Toolbox can be installed with::
 
-    python3 -m pip uninstall sfs
+    uv pip install sfs
+
+This will automatically install the NumPy_ and SciPy_ libraries as well,
+which are needed by the SFS Toolbox.
+
+If you want to use the provided functions for plotting sound fields, you'll need
+Matplotlib_::
+
+    uv pip install matplotlib
+
+However, since all results are provided as plain NumPy_ arrays, you should also
+be able to use any other plotting library of your choice to visualize the sound
+fields.
+
+The steps above need to be executed only once.
+Whenever you come back to this directory at a later time,
+you just need to activate the environment again.
 
 If you want to install the latest development version of the SFS Toolbox, have a
 look at :doc:`contributing`.
-
-.. _pip: https://pip.pypa.io/en/latest/installing/

doc/installation.rst

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sfs"
+license = "MIT"
+dynamic = ["version"]
+description = "Sound Field Synthesis Toolbox"
+readme = "README.rst"
+keywords = ["audio", "SFS", "WFS", "Ambisonics"]
+authors = [{ name = "SFS Toolbox Developers", email = "[email protected]" }]
+dependencies = ["numpy >= 2", "scipy >= 1.16"]
+requires-python = ">= 3.11"
+classifiers = [
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Documentation = "https://sfs-python.readthedocs.io/"
+Repository = "https://github.com/sfstoolbox/sfs-python"
+Issues = "https://github.com/sfstoolbox/sfs-python/issues"
+
+[tool.setuptools.packages.find]
+include = ["sfs*"]
+
+[tool.setuptools.dynamic]
+version = { attr = "sfs.__version__" }