Move setup.py metadata into pyproject.toml, remove dev-requirements.txt, & fix #839 (#985)

mhucka · sergeisakov · gemini-code-assist[bot] · web-flow · commit b9b2812020d5 · 2026-01-21T23:45:49.000Z
This addresses deprecation warnings originating from the use of outdated `setuptools` functions, and takes the opportunity to modernize the management of the version number and the dependencies in accordance with current Python practices (PEP [621](https://peps.python.org/pep-0631/), [735](https://peps.python.org/pep-0735/)). Key changes include: - All declarative package metadata (e.g., name, author, classifiers) has been moved from `setup.py` to `pyproject.toml`. What's left in `setup.py` has been simplified to only contain the logic necessary for building the C++ extensions and calling `setup`. - The qsim version number is now stored in only one file, `qsimcirq/_version.py`, and both `pyproject.toml` and `setup.py` read it from there. In the case of `setup.py`, the use of the deprecated `self.distribution.get_version()` has been replaced with the use of `runpy` to read the version number from `qsimcirq/_version.py`. (The latter change fixes #839.) - The development dependencies are no longer stored as "extras" but rather use the pyproject.toml `[dependency-groups]` section introduced in 2024 by [PEP 735](https://peps.python.org/pep-0735/) and recognized by [pip version 25.1+](https://packaging.python.org/en/latest/specifications/dependency-groups/#specification). This means `dev-requirements.txt` is gone, and development dependencies are installed using ```shell pip install --group dev ``` - `pyproject.toml` defines the versions of Python for which cibuildwheel builds wheels (in section `[tool.cibuildwheel]`). --------- Co-authored-by: Sergei Isakov <54642992+sergeisakov@users.noreply.github.com> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -73,10 +73,13 @@ jobs:
           cache: pip
           cache-dependency-path: |
             requirements.txt
-            dev-requirements.txt
+            pyproject.toml
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
 
       - name: Install dependencies
-        run: pip install -r requirements.txt -r dev-requirements.txt
+        run: pip install -r requirements.txt --group dev
 
       - name: Check format
         continue-on-error: ${{inputs.soft-linting == 'true'}}
@@ -243,10 +246,13 @@ jobs:
           cache: pip
           cache-dependency-path: |
             requirements.txt
-            dev-requirements.txt
+            pyproject.toml
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
 
       - name: Install dependencies
-        run: pip install -r requirements.txt -r dev-requirements.txt
+        run: pip install -r requirements.txt --group dev
 
       - name: Set up Bazel
         uses: './.github/actions/set-up-bazel'
@@ -331,10 +337,13 @@ jobs:
           cache: pip
           cache-dependency-path: |
             requirements.txt
-            dev-requirements.txt
+            pyproject.toml
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
 
       - name: Install dependencies
-        run: pip install -r requirements.txt -r dev-requirements.txt
+        run: pip install -r requirements.txt --group dev
 
       - name: Set up Bazel
         uses: './.github/actions/set-up-bazel'
@@ -387,10 +396,13 @@ jobs:
           cache: pip
           cache-dependency-path: |
             requirements.txt
-            dev-requirements.txt
+            pyproject.toml
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
 
       - name: Install dependencies
-        run: pip install -r requirements.txt -r dev-requirements.txt
+        run: pip install -r requirements.txt --group dev
 
       - name: Set up Bazel
         uses: './.github/actions/set-up-bazel'
diff --git a/.github/workflows/cirq_compatibility.yml b/.github/workflows/cirq_compatibility.yml
@@ -53,15 +53,13 @@ jobs:
           cache: pip
           cache-dependency-path: |
             requirements.txt
-            dev-requirements.txt
+            pyproject.toml
 
       - name: Install latest dev version of Cirq
         run: pip install --upgrade cirq~=1.0.dev
 
       - name: Install qsim dev requirements
-        run: |
-          pip install -r requirements.txt
-          pip install -r dev-requirements.txt
+        run: pip install -r requirements.txt --group dev
 
       - name: Run Python tests
         env:
diff --git a/Dockerfile b/Dockerfile
@@ -38,21 +38,20 @@ COPY ./lib/ /qsim/lib/
 COPY ./pybind_interface/ /qsim/lib/
 COPY ./qsimcirq_tests/ /qsim/qsimcirq_tests/
 COPY ./requirements.txt /qsim/requirements.txt
-COPY ./dev-requirements.txt /qsim/dev-requirements.txt
+COPY ./pyproject.toml /qsim/pyproject.toml
+
+WORKDIR /qsim/
 
 # Create venv to avoid collision between system packages and what we install.
 RUN python3 -m venv --upgrade-deps test_env
 
 # Activate venv.
-ENV PATH="/test_env/bin:$PATH"
+ENV PATH="/qsim/test_env/bin:$PATH"
 
 # Install qsim requirements.
-# hadolint ignore=DL3042
-RUN python3 -m pip install -r /qsim/requirements.txt && \
-    python3 -m pip install -r /qsim/dev-requirements.txt
+RUN python3 -m pip install --no-cache-dir -r requirements.txt --group dev
 
 # Compile qsim.
-WORKDIR /qsim/
 RUN make -j qsim
 
 ENTRYPOINT ["/qsim/apps/qsim_base.x"]
diff --git a/dev-requirements.txt b/dev-requirements.txt
diff --git a/dev_tools/test_libs.sh b/dev_tools/test_libs.sh
@@ -33,7 +33,7 @@ if [[ "$1" == "-h" || "$1" == "--help" || "$1" == "help" ]]; then
 fi
 
 if ! python -m pip show -qq py-cpuinfo 2>/dev/null; then
-    echo "Error: missing 'py-cpuinfo'. Please install dev-requirements.txt." >&2
+    echo "Error: missing package 'py-cpuinfo'." >&2
     exit 1
 fi
 
diff --git a/docs/install_qsimcirq.md b/docs/install_qsimcirq.md
@@ -10,18 +10,24 @@ directly in C++ code without building and installing the qsimcirq interface.
 
 ## Before installation
 
-Prior to installation, consider opening a
+Prior to installation, consider creating a
 [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/).
 
-Prerequisites are included in the
+Prerequisites for installing and running qsim are included in the
 [`requirements.txt`](https://github.com/quantumlib/qsim/blob/main/requirements.txt)
-file, and will be automatically installed along with qsimcirq.
+file, and will be automatically installed along with qsimcirq when you install
+it with pip.
 
-If you'd like to develop qsimcirq, a separate set of dependencies are includes
+If you'd like to develop qsimcirq, a separate set of dependencies are defined
 in the
-[`dev-requirements.txt`](https://github.com/quantumlib/qsim/blob/main/dev-requirements.txt)
-file. You can install them with `pip3 install -r dev-requirements.txt` or
-`pip3 install qsimcirq[dev]`.
+[`pyproject.toml`](https://github.com/quantumlib/qsim/blob/main/pyproject.toml)
+file. Using pip version 25.1 or higher, you can install them with the following
+commands:
+
+```shell
+pip install -r requirements.txt
+pip install --group dev
+```
 
 ## Linux installation
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -12,28 +12,140 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Note: there are altogether 3 types of dependencies listed in this file:
+#
+#  [build-system].requires: the packages needed by the build backend to build
+#  the project from source. This list is not stored in the package metadata.
+#
+#  [project].dependencies: core packages needed to be able to run qsimcirq.
+#  Equivalent to "install_requires" in setuptools' setup.py. The list is stored
+#  in the metadata of the package; when the project is installed by pip, this is
+#  the specification that is used to install its dependencies.
+#
+#  [dependency-groups].dev: the development dependencies; i.e., what a
+#  developer needs in order to run unit tests, linters, and formatters. The
+#  "[dependency-groups]" section is a Python packaging feature introduced in
+#  2025. This list is not stored in the metadata of the package. To install the
+#  development dependencies, use "pip install --group dev".
+
 [build-system]
+build-backend = "setuptools.build_meta"
 requires = [
-  "packaging",
-  "setuptools>=78.1.1",
-  "pybind11[global]",
-  # "pip install" from sources needs to build Pybind, which needs CMake too.
-  "cmake~=3.28.1",
+    "cmake~=3.28.1",
+    "pybind11[global]",
+    "setuptools-scm[toml]>=6.2",
+    "setuptools>=78.1.1",
+    "wheel",
 ]
-build-backend = "setuptools.build_meta"
+
+[project]
+name = "qsimcirq"
+description = "High-performance quantum circuit simulator for C++ and Python."
+authors = [
+    { name = "The qsim/qsimh Developers", email = "qsim-qsimh-dev@googlegroups.com" }
+]
+maintainers = [
+    { name = "Google Quantum AI", email = "quantum-oss-maintainers@google.com" }
+]
+readme = {file = "README.md", content-type = "text/markdown"}
+license = "Apache-2.0"
+requires-python = ">=3.10.0"
+dynamic = ["version", "dependencies"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: GPU :: NVIDIA CUDA",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: C++",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Quantum Computing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+keywords = [
+    "cirq",
+    "nisq",
+    "quantum algorithm development",
+    "quantum circuit simulator",
+    "quantum computing",
+    "quantum programming",
+    "quantum simulation",
+    "quantum",
+    "schrödinger-feynman simulation",
+    "simulation",
+    "state vector simulator",
+]
+
+[project.urls]
+documentation = "https://quantumai.google/qsim"
+download = "https://pypi.org/project/qsimcirq/#files"
+homepage = "https://quantumai.google/qsim"
+issues = "https://github.com/quantumlib/qsim/issues"
+source = "https://github.com/quantumlib/qsim"
+
+[dependency-groups]
+# Development dependencies. Install these with "pip install --group dev".
+dev = [
+    # The following repeats [build-system].requires b/c pyproject.toml has no
+    # mechanism to reference that list. Keep these versions in sync with above.
+    "cmake~=3.28.1",
+    "pybind11[global]",
+    "setuptools>=78.1.1; python_version >= '3.12'",
+
+    # Other build, packaging, and distribution utilities.
+    "cibuildwheel",
+
+    # Linters, formatters, and test utilities.
+    "black~=25.9.0",
+    "isort[colors]~=6.0.1",
+    "py-cpuinfo",
+    "pylint~=4.0.2",
+    "pytest",
+    "pytest-xdist",
+]
+
+[tool.setuptools]
+packages = ["qsimcirq"]
+package-data = {"qsimcirq" = ["py.typed"]}
+
+[tool.setuptools.dynamic]
+# The next one becomes the value of [project].version.
+version = {attr = "qsimcirq._version.__version__"}
+# The next one becomes [project].dependencies, equivalent to "install_requires"
+# in setuptools' setup.py. "pip install qsim" installs these automatically.
+dependencies = {file = ["requirements.txt"] }
 
 [tool.cibuildwheel]
-test-extras = "dev"
+build = "cp310-* cp311-* cp312-* cp313-*"
 dependency-versions = "latest"
 enable = ["cpython-prerelease"]
 environment.PIP_PREFER_BINARY = "1"
 # Due to package & module name conflict, temporarily move it away to run tests:
-before-test = "mv {package}/qsimcirq /tmp"
-test-command = "pytest -s -v {package}/qsimcirq_tests/qsimcirq_test.py && mv /tmp/qsimcirq {package}"
+before-test = "pip install --group dev && mv {package}/qsimcirq /tmp"
+test-command = """
+pytest -s -v {package}/qsimcirq_tests/qsimcirq_test.py &&
+mv /tmp/qsimcirq {package}
+"""
 
 [tool.cibuildwheel.macos]
-before-build = "brew install -q libomp llvm@19 && brew unlink libomp && brew unlink llvm@19 && brew link --force libomp && brew link --force llvm@19"
-repair-wheel-command = "delocate-listdeps {wheel} && delocate-wheel --verbose --require-archs {delocate_archs} -w {dest_dir} {wheel}"
+before-build = """
+brew install -q libomp llvm@19 &&
+brew unlink libomp &&
+brew unlink llvm@19 &&
+brew link --force libomp &&
+brew link --force llvm@19
+"""
+repair-wheel-command = """
+delocate-listdeps {wheel} &&
+delocate-wheel --verbose --require-archs {delocate_archs} -w {dest_dir} {wheel}
+"""
 
 [tool.cibuildwheel.linux]
 manylinux-x86_64-image = "manylinux2014"
diff --git a/requirements.txt b/requirements.txt
@@ -1,3 +1,6 @@
+# Run-time dependencies for qsimcirq. This file is read from pyproject.toml.
+
+# Core dependencies:
 absl-py
 cirq-core~=1.0
 
diff --git a/setup.py b/setup.py
