✨ Adopt PEP 735 dependency groups (#530)

## Description This PR updates the project to use the dependency groups feature that was proposed in [PEP 735](https://peps.python.org/pep-0735/) and is available in `uv` since `0.4.27` in favour of optional dependencies. It adds three explicit dependency groups: - `build`, containing the build time dependencies, - `test`, containing the test dependencies (including coverage), and - `docs`, containing the docs dependencies. In addition, - enables testing on Python 3.13 (after some dependency adjustments), - updates lower bounds for many development dependencies, and - refactors the nox sessions as well as the RtD script to take advantage of the new dependency groups. ## Checklist:  - [x] The pull request only contains commits that are related to it. - [x] I have added appropriate tests and documentation. - [x] I have made sure that all CI jobs on GitHub pass. - [x] The pull request introduces no new warnings and follows the project's style guidelines.
cda-tum · Jan 7, 2025 · 0ed735c · 0ed735c
2 parents 4b0474d + 243f0a8
commit 0ed735c
Show file tree

Hide file tree

Showing 8 changed files with 1,150 additions and 582 deletions.
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -42,7 +42,6 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
-          attestations: true
 
   # Downloads the previously generated artifacts and deploys to PyPI on published releases.
   deploy:
@@ -64,5 +63,3 @@ jobs:
         with:
           subject-path: "dist/*"
       - uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          attestations: true
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,32 +1,39 @@
 version: 2
 
-submodules:
-  include: all
-  recursive: true
+formats:
+  #  - pdf
+  - htmlzip
 
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
-  jobs:
-    post_checkout:
-      # Skip docs build if the commit message contains "skip ci"
-      - (git --no-pager log --pretty="tformat:%s -- %b" -1 | grep -viq "skip ci") || exit 183
-      # Skip docs build if there are no changes related to docs
-      - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml src/mqt/ src/python include/python .github/contributing* .github/workflows/support*;
-        then
-          exit 183;
-        fi
-      # Unshallow the git clone and fetch tags to get proper version information
-      - git fetch --unshallow --tags
+    python: "3.12"
+  commands:
+    # Skip docs build if the commit message contains "skip ci"
+    - (git --no-pager log --pretty="tformat:%s -- %b" -1 | grep -viq "skip ci") || exit 183
+    # Skip docs build if there are no changes related to docs
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml src/mqt/ src/python include/*/python .github/contributing* .github/support*;
+      then
+        exit 183;
+      fi
+    # Set up uv and a virtual environment
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    # Unshallow the git clone and fetch tags to get proper version information
+    - git fetch --unshallow --tags
+    # Run the html builder
+    - uv run --frozen --no-dev --group docs -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs/source $READTHEDOCS_OUTPUT/html
+    # Run the htmlzip builder and create a zip file
+    - uv run --frozen --no-dev --group docs -m sphinx -T -b dirhtml -d docs/_build/doctrees -D language=en docs/source docs/_build/dirhtml
+    - mkdir -p $READTHEDOCS_OUTPUT/htmlzip
+    - zip -r $READTHEDOCS_OUTPUT/htmlzip/html.zip docs/_build/dirhtml/*
+    # Run the latex builder and create a pdf file
+#    - uv run --frozen --no-dev --group docs -m sphinx -T -b latex -d docs/_build/doctrees -D language=en docs/source docs/_build/latex
+#    - cd docs/_build/latex && latexmk -pdf -f -dvi- -ps- -interaction=nonstopmode -jobname=$READTHEDOCS_PROJECT
+#    - mkdir -p $READTHEDOCS_OUTPUT/pdf
+#    - cp docs/_build/latex/$READTHEDOCS_PROJECT.pdf $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT.pdf
 
 sphinx:
-  configuration: docs/source/conf.py
-
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+  configuration: docs/conf.py
diff --git a/docs/source/library/ApplicationScheme.rst b/docs/source/library/ApplicationScheme.rst
@@ -8,7 +8,7 @@ See :doc:`/CompilationFlowVerification` for more information on the dedicated ap
 
 In case of the other checkers, which consider both circuits individually, using a non-sequential application scheme can significantly boost the operation caching performance in the underlying decision diagram package.
 
-    .. autoclass:: mqt.qcec.types.ApplicationSchemeName
+    .. autoclass:: mqt.qcec.literals.ApplicationSchemeName
 
     .. autoclass:: mqt.qcec.ApplicationScheme
         :undoc-members:

diff --git a/docs/source/library/EquivalenceCriterion.rst b/docs/source/library/EquivalenceCriterion.rst
@@ -5,7 +5,7 @@ Notions of Equivalence
 
 This class captures all the different notions of equivalence that can be the :class:`result <mqt.qcec.EquivalenceCheckingManager.Results>` of a :func:`~mqt.qcec.EquivalenceCheckingManager.run`.
 
-    .. autoclass:: mqt.qcec.types.EquivalenceCriterionName
+    .. autoclass:: mqt.qcec.literals.EquivalenceCriterionName
 
     .. autoclass:: mqt.qcec.EquivalenceCriterion
         :undoc-members:

diff --git a/docs/source/library/StateType.rst b/docs/source/library/StateType.rst
@@ -11,7 +11,7 @@ The type of states that is used in the :ref:`simulation checker <EquivalenceChec
 
 For details, see :cite:p:`burgholzer2021randomStimuliGenerationQuantum`.
 
-    .. autoclass:: mqt.qcec.types.StateTypeName
+    .. autoclass:: mqt.qcec.literals.StateTypeName
 
     .. autoclass:: mqt.qcec.StateType
         :undoc-members:

diff --git a/noxfile.py b/noxfile.py
@@ -14,22 +14,11 @@
     from collections.abc import Sequence
 
 nox.needs_version = ">=2024.3.2"
-nox.options.default_venv_backend = "uv|virtualenv"
+nox.options.default_venv_backend = "uv"
 
 nox.options.sessions = ["lint", "tests", "minimums"]
 
-PYTHON_ALL_VERSIONS = ["3.9", "3.10", "3.11", "3.12"]
-
-# The following lists all the build requirements for building the package.
-# Note that this includes transitive build dependencies of package dependencies,
-# since we use `--no-build-isolation` to install the package in editable mode
-# and get better caching performance. This only concerns dependencies that are
-# not available via wheels on PyPI (i.e., only as source distributions).
-BUILD_REQUIREMENTS = [
-    "scikit-build-core>=0.10.1",
-    "setuptools_scm>=8.1",
-    "pybind11>=2.13.5",
-]
+PYTHON_ALL_VERSIONS = ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
 if os.environ.get("CI", None):
     nox.options.error_on_missing_interpreters = True
@@ -49,10 +38,8 @@ def _run_tests(
     *,
     install_args: Sequence[str] = (),
     run_args: Sequence[str] = (),
-    extras: Sequence[str] = (),
 ) -> None:
-    posargs = list(session.posargs)
-    env = {}
+    env = {"UV_PROJECT_ENVIRONMENT": session.virtualenv.location}
     if os.environ.get("CI", None) and sys.platform == "win32":
         env["SKBUILD_CMAKE_ARGS"] = "-T ClangCL"
 
@@ -61,15 +48,31 @@ def _run_tests(
     if shutil.which("ninja") is None:
         session.install("ninja")
 
-    extras_ = ["test", *extras]
-    if "--cov" in posargs:
-        extras_.append("coverage")
-        posargs.append("--cov-config=pyproject.toml")
-
-    session.install(*BUILD_REQUIREMENTS, *install_args, env=env)
-    install_arg = f"-ve.[{','.join(extras_)}]"
-    session.install("--no-build-isolation", install_arg, *install_args, env=env)
-    session.run("pytest", *run_args, *posargs, env=env)
+    # install build and test dependencies on top of the existing environment
+    session.run(
+        "uv",
+        "sync",
+        "--inexact",
+        "--only-group",
+        "build",
+        "--only-group",
+        "test",
+        *install_args,
+        env=env,
+    )
+    session.run(
+        "uv",
+        "run",
+        "--no-dev",  # do not auto-install dev dependencies
+        "--no-build-isolation-package",
+        "mqt-qcec",  # build the project without isolation
+        *install_args,
+        "pytest",
+        *run_args,
+        *session.posargs,
+        "--cov-config=pyproject.toml",
+        env=env,
+    )
 
 
 @nox.session(reuse_venv=True, python=PYTHON_ALL_VERSIONS)
@@ -90,7 +93,9 @@ def minimums(session: nox.Session) -> None:
         install_args=["--resolution=lowest-direct"],
         run_args=["-Wdefault"],
     )
-    session.run("uv", "pip", "list")
+    env = {"UV_PROJECT_ENVIRONMENT": session.virtualenv.location}
+    session.run("uv", "tree", "--frozen", env=env)
+    session.run("uv", "lock", "--refresh", env=env)
 
 
 @nox.session(reuse_venv=True)
@@ -101,25 +106,38 @@ def docs(session: nox.Session) -> None:
     args, posargs = parser.parse_known_args(session.posargs)
 
     serve = args.builder == "html" and session.interactive
-    extra_installs = ["sphinx-autobuild"] if serve else []
-    session.install(*BUILD_REQUIREMENTS, *extra_installs)
-    session.install("--no-build-isolation", "-ve.[docs]")
-    session.chdir("docs")
-
-    if args.builder == "linkcheck":
-        session.run("sphinx-build", "-b", "linkcheck", "source", "_build/linkcheck", *posargs)
-        return
+    if serve:
+        session.install("sphinx-autobuild")
+
+    env = {"UV_PROJECT_ENVIRONMENT": session.virtualenv.location}
+    # install build and docs dependencies on top of the existing environment
+    session.run(
+        "uv",
+        "sync",
+        "--inexact",
+        "--only-group",
+        "build",
+        "--only-group",
+        "docs",
+        env=env,
+    )
 
-    shared_args = (
+    shared_args = [
         "-n",  # nitpicky mode
         "-T",  # full tracebacks
         f"-b={args.builder}",
-        "source",
-        f"_build/{args.builder}",
+        "docs/source",
+        f"docs/_build/{args.builder}",
         *posargs,
+    ]
+
+    session.run(
+        "uv",
+        "run",
+        "--no-dev",  # do not auto-install dev dependencies
+        "--no-build-isolation-package",
+        "mqt-qcec",  # build the project without isolation
+        "sphinx-autobuild" if serve else "sphinx-build",
+        *shared_args,
+        env=env,
     )
-
-    if serve:
-        session.run("sphinx-autobuild", *shared_args)
-    else:
-        session.run("sphinx-build", "--keep-going", *shared_args)
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,8 +1,8 @@
 [build-system]
 requires = [
-  "scikit-build-core>=0.10.1",
+  "scikit-build-core>=0.10.7",
   "setuptools-scm>=8.1",
-  "pybind11>=2.13.5",
+  "pybind11>=2.13.6",
 ]
 build-backend = "scikit_build_core.build"
 
@@ -45,26 +45,6 @@ dependencies = [
 ]
 dynamic = ["version"]
 
-[project.optional-dependencies]
-test = ["pytest>=7.2"]
-coverage = ["mqt.qcec[test]", "pytest-cov>=4"]
-docs = [
-    "furo>=2023.9.10",
-    "qiskit[visualization]",
-    "setuptools-scm>=8.1",
-    "sphinx_design>=0.6",
-    "sphinx-autoapi>=3",
-    "sphinx-copybutton>=0.5",
-    "sphinxcontrib-bibtex>=2.4.2",
-    "sphinxcontrib-svg2pdfconverter>=1.2",
-    "sphinxext-opengraph>=0.9",
-    "ipython",
-    "ipykernel",
-    "nbsphinx",
-    "sphinx-autodoc-typehints",
-]
-dev = ["mqt.qcec[coverage, docs]"]
-
 [project.urls]
 Homepage = "https://github.com/cda-tum/mqt-qcec"
 Documentation = "https://mqt.readthedocs.io/projects/qcec"
@@ -285,8 +265,9 @@ ignore = ["GH200"]
 build = "cp3*"
 skip = "*-musllinux_*"
 archs = "auto64"
-test-command = "python -c \"from mqt import qcec\""
-test-skip = ["cp313*"] # skip testing on Python 3.13 until our dependencies are ready
+test-groups = ["test"]
+test-command = "pytest {project}/test/python"
+test-skip = ["cp3*t-*"] # skip testing on free-threading Python until our dependencies are ready
 build-frontend = "build[uv]"
 enable = ["cpython-freethreading"]
 manylinux-x86_64-image = "manylinux_2_28"
@@ -312,3 +293,36 @@ environment = { MACOSX_DEPLOYMENT_TARGET = "11.0" }
 
 [tool.uv]
 reinstall-package = ["mqt.qcec"]
+
+[tool.uv.sources]
+mqt-qcec = { workspace = true }
+
+[dependency-groups]
+build = [
+  "pybind11>=2.13.6",
+  "scikit-build-core>=0.10.7",
+  "setuptools-scm>=8.1",
+]
+docs = [
+  "furo>=2024.8.6",
+  "qiskit[visualization]>=1.0.0",
+  "setuptools-scm>=8.1",
+  "sphinx-autoapi>=3.4.0",
+  "sphinx-copybutton>=0.5.2",
+  "sphinx-design>=0.6.1",
+  "sphinxcontrib-bibtex>=2.6.3",
+  "sphinxcontrib-svg2pdfconverter>=1.2.3",
+  "sphinxext-opengraph>=0.9.1",
+  "ipykernel>=6.29.5",
+  "nbsphinx>=0.9.6",
+  "sphinx-autodoc-typehints>=2.3.0",
+]
+test = [
+  "pytest>=8.3.4",
+  "pytest-cov>=6",
+]
+dev = [
+  {include-group = "build"},
+  {include-group = "docs"},
+  {include-group = "test"},
+]