pytest-quantum 0.1.0__tar.gz

pytest_quantum-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  # -------------------------------------------------------------------------
+  # Lint + type check (fast, runs on every push)
+  # -------------------------------------------------------------------------
+  lint:
+    name: Lint & type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Ruff lint
+        run: uv run --group dev ruff check src/ tests/
+      - name: Ruff format check
+        run: uv run --group dev ruff format --check src/ tests/
+      - name: Mypy
+        run: uv run --group dev mypy src/
+
+  # -------------------------------------------------------------------------
+  # Core tests (no quantum SDK) — fast, runs on all platforms + Python versions
+  # -------------------------------------------------------------------------
+  test-core:
+    name: Core tests (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install core dependencies only
+        run: uv sync --no-group dev
+      - name: Run core tests
+        run: uv run pytest tests/test_stats.py tests/test_plugin.py tests/test_assertions_states.py tests/test_assertions_distributions.py tests/test_assertions_unitary.py tests/test_assertions_structure.py -v --cov=pytest_quantum --cov-report=xml
+      - name: Upload coverage
+        uses: codecov/codecov-action@v5
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          files: ./coverage.xml
+
+  # -------------------------------------------------------------------------
+  # Qiskit integration tests
+  # -------------------------------------------------------------------------
+  test-qiskit:
+    name: Qiskit integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Install with Qiskit extras
+        run: uv sync --extra qiskit
+      - name: Run Qiskit tests
+        run: uv run pytest tests/test_integration_qiskit.py tests/test_integration_noise.py tests/test_assertions_structure.py tests/test_assertions_unitary.py -v
+
+  # -------------------------------------------------------------------------
+  # Cirq integration tests
+  # -------------------------------------------------------------------------
+  test-cirq:
+    name: Cirq integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Install with Cirq extras
+        run: uv sync --extra cirq
+      - name: Run Cirq tests
+        run: uv run pytest tests/test_integration_cirq.py -v
+
+  # -------------------------------------------------------------------------
+  # Cross-framework tests (needs both Qiskit + Cirq)
+  # -------------------------------------------------------------------------
+  test-cross-framework:
+    name: Cross-framework tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Install Qiskit + Cirq
+        run: uv sync --extra qiskit --extra cirq
+      - name: Run cross-framework tests
+        run: uv run pytest tests/test_integration_cross_framework.py -v
+
+  # -------------------------------------------------------------------------
+  # PennyLane integration tests
+  # -------------------------------------------------------------------------
+  test-pennylane:
+    name: PennyLane integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Install with PennyLane extras
+        run: uv sync --extra pennylane
+      - name: Run PennyLane tests
+        run: uv run pytest tests/test_integration_pennylane.py -v
+
+  # -------------------------------------------------------------------------
+  # Graphix integration tests
+  # -------------------------------------------------------------------------
+  test-graphix:
+    name: Graphix integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Install with Graphix extras
+        run: uv sync --extra graphix
+      - name: Run Graphix tests
+        run: uv run pytest tests/test_assertions_states.py tests/test_stats.py -v

pytest_quantum-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"  # triggers on tags like v0.1.0
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build wheel + sdist
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pytest-quantum
+    permissions:
+      id-token: write  # OIDC trusted publishing — no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

pytest_quantum-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+*.pyd
+build/
+dist/
+wheels/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+.uv/
+
+# pytest
+.pytest_cache/
+.cache/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Sphinx docs build output
+docs/_build/
+
+# Quantum SDK artifacts
+*.qasm
+*.quil
+*.braket

pytest_quantum-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,182 @@
+# Contributing to pytest-quantum
+
+Thank you for your interest in contributing. This document covers everything you need to get set up, run tests, and submit a pull request.
+
+---
+
+## Prerequisites
+
+- Python 3.11 or 3.12
+- [uv](https://docs.astral.sh/uv/) (fast Python package manager — replaces pip/venv)
+
+Install uv if you don't have it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+---
+
+## Setup
+
+```bash
+git clone https://github.com/qbench/pytest-quantum
+cd pytest-quantum
+
+# Create virtual environment and install all dependencies (all quantum SDKs + dev tools)
+uv sync --all-extras --group dev
+```
+
+That's it. `uv sync` creates `.venv/` and installs everything.
+
+---
+
+## Running tests
+
+```bash
+# Full test suite (111+ tests across all frameworks)
+uv run pytest
+
+# Only unit tests (no quantum SDK needed — fast, < 1s)
+uv run pytest tests/test_stats.py tests/test_assertions_distributions.py \
+               tests/test_assertions_states.py tests/test_assertions_structure.py
+
+# Integration tests only (real quantum circuits)
+uv run pytest tests/test_integration_qiskit.py tests/test_integration_cirq.py \
+               tests/test_integration_cross_framework.py \
+               tests/test_integration_pennylane.py tests/test_integration_noise.py
+
+# Include slow shot-heavy tests
+uv run pytest --quantum-slow
+
+# With coverage report
+uv run pytest --cov=pytest_quantum --cov-report=term-missing
+
+# Run a specific test file
+uv run pytest tests/test_stats.py -v
+
+# Run a specific test by name
+uv run pytest -k "test_bell_state_distribution" -v
+```
+
+---
+
+## Linting and type checking
+
+All three must pass before a PR is merged.
+
+```bash
+# Linter + formatter (ruff does both)
+uv run ruff check src/ tests/          # check
+uv run ruff check src/ tests/ --fix    # auto-fix what's fixable
+uv run ruff format src/ tests/         # format
+
+# Type checker (strict mypy — no Any leakage in public API)
+uv run mypy src/
+
+# Run all three at once
+uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run mypy src/
+```
+
+---
+
+## Building docs
+
+```bash
+# Install docs dependencies
+uv sync --group docs
+
+# Build HTML docs
+uv run sphinx-build docs docs/_build/html
+
+# Open in browser (macOS)
+open docs/_build/html/index.html
+
+# Auto-rebuild on change (requires sphinx-autobuild)
+uv run sphinx-autobuild docs docs/_build/html
+```
+
+---
+
+## Project structure
+
+```
+src/pytest_quantum/
+├── __init__.py              # public API — everything users import
+├── plugin.py                # pytest entry point: markers, CLI options, all fixtures
+├── assertions/
+│   ├── distributions.py     # assert_measurement_distribution, assert_counts_close
+│   ├── states.py            # assert_state_fidelity_above, assert_states_close
+│   ├── structure.py         # assert_circuit_depth, assert_circuit_width, assert_gate_count
+│   └── unitary.py           # assert_unitary, assert_circuits_equivalent
+├── converters/
+│   └── to_unitary.py        # any circuit → numpy unitary matrix
+└── stats/
+    ├── shots.py             # min_shots, recommended_shots
+    └── tests.py             # fidelity, tvd, tvd_from_counts, chi_square_test
+
+tests/
+├── test_stats.py                          # pure math tests, no SDKs needed
+├── test_assertions_*.py                   # unit tests (mock-based)
+├── test_plugin.py                         # pytester-based plugin tests
+├── test_integration_qiskit.py             # real Qiskit + AerSimulator
+├── test_integration_cirq.py               # real Cirq
+├── test_integration_cross_framework.py    # Qiskit vs Cirq equivalence
+├── test_integration_pennylane.py          # real PennyLane
+└── test_integration_noise.py             # depolarizing noise fixture
+```
+
+---
+
+## Adding support for a new framework
+
+1. Add the import detection to `converters/to_unitary.py` — add a `_is_<framework>` function and `_from_<framework>` converter.
+2. Add a fixture to `plugin.py` following the same `scope="session"` pattern.
+3. Add the optional dependency to `pyproject.toml` under `[project.optional-dependencies]`.
+4. Add integration tests to `tests/test_integration_<framework>.py`.
+5. Update `README.md` and `docs/fixtures.md`.
+
+---
+
+## Adding a new assertion
+
+1. Add the function to the appropriate file in `src/pytest_quantum/assertions/`.
+2. Register assert rewriting in `__init__.py` (already done for all modules).
+3. Export from `__init__.py` (`from pytest_quantum.assertions.X import ...` and add to `__all__`).
+4. Add unit tests in the corresponding `tests/test_assertions_*.py`.
+5. Add integration tests that use real circuits.
+6. Update `docs/assertions.md`.
+
+---
+
+## Code style
+
+- Type annotations required everywhere (`mypy --strict`).
+- Google-style docstrings on every public function.
+- `from __future__ import annotations` at the top of every file.
+- Optional SDK imports must be inside functions (lazy imports) — never at module level.
+- All assertions must produce clear, human-readable error messages with observed vs expected values.
+
+---
+
+## Pull request checklist
+
+- [ ] `uv run pytest` passes (136+ tests)
+- [ ] `uv run ruff check src/ tests/` passes
+- [ ] `uv run mypy src/` passes
+- [ ] New assertion or fixture has integration test with a real circuit
+- [ ] Docstring updated with example
+- [ ] `docs/` updated if public API changed
+- [ ] `CHANGELOG.md` entry added under an `Unreleased` section
+
+---
+
+## Reporting bugs
+
+Open an issue at https://github.com/qbench/pytest-quantum/issues with:
+
+- Python version (`python --version`)
+- pytest-quantum version (`pip show pytest-quantum`)
+- Quantum SDK versions (e.g. `pip show qiskit qiskit-aer`)
+- Minimal reproducible example
+- Full error output

pytest_quantum-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qbench
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.