quantum-exercises 0.8.0__tar.gz

quantum_exercises-0.8.0/.github/dependabot.yml

@@ -0,0 +1,53 @@
+version: 2
+
+# This file does two jobs.
+#
+# The obvious one: the actions in .github/workflows are pinned to commit SHAs,
+# which is the right call for supply-chain reasons and also means nothing ever
+# moves them. A pull request carrying the upstream release notes is how they get
+# read before they get merged.
+#
+# The less obvious one, and the reason the interval is monthly rather than off:
+# GitHub disables a scheduled workflow in a public repository after 60 days with
+# no activity. This project is meant to reach a state where nobody commits to it
+# for months, which is exactly the state that silently stops verify.yml. A
+# monthly pull request is what keeps it running.
+
+updates:
+  # Everything scheduled in this repository lands on the 1st and the 15th, and
+  # that includes this. `cronjob` is the field the interval requires, confirmed
+  # against the published Dependabot schema rather than guessed; if a Dependabot
+  # that predates the cron interval ever rejects it, `interval: "monthly"` is the
+  # fallback and already falls on the 1st.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "cron"
+      cronjob: "23 6 1,15 * *"
+      timezone: "Etc/UTC"
+    # One pull request for all of them, not one per action.
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: "ci"
+
+  # Keeps uv.lock from drifting years behind the ranges in pyproject.toml.
+  #
+  # Expect these to arrive red. Bumping a pinned version makes the README badges
+  # and the CONTRIBUTING table disagree with what is installed, and three tests
+  # exist to say so. That is the tests working: in this context the docs really
+  # are stale, and the failing run is the list of files to update before merging.
+  # If the monthly touch-up is not worth it, delete this block. The one above
+  # already keeps the repository active on its own.
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "cron"
+      cronjob: "23 6 1,15 * *"
+      timezone: "Etc/UTC"
+    groups:
+      dependencies:
+        patterns: ["*"]
+    commit-message:
+      prefix: "deps"

quantum_exercises-0.8.0/.github/workflows/ci.yml

@@ -0,0 +1,172 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Never let CI submit a job to a real QPU, whatever credentials exist.
+  QX_OFFLINE: "1"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  # pre-commit is opt-in per clone, so the secret scan has to run here too.
+  # The pre-commit hook runs `gitleaks git --staged`, which only sees what is
+  # about to be committed; on a fresh CI checkout nothing is staged, so it would
+  # scan nothing at all. `gitleaks dir` scans the tree, which is what is wanted.
+  secrets:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      GITLEAKS_VERSION: 8.30.1
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install gitleaks
+        run: |
+          set -euo pipefail
+          curl -sSfL -o /tmp/gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          tar -xzf /tmp/gitleaks.tar.gz -C /usr/local/bin gitleaks
+      - name: Scan for hardcoded secrets
+        run: gitleaks dir . --config .gitleaks.toml --redact --no-banner --verbose
+
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run pytest -q
+
+  # The suite covers every line of src/, and only a gate keeps it that way.
+  # coverage is pulled in for these commands alone, so it never reaches
+  # pyproject.toml, uv.lock, or the package counts CONTRIBUTING documents.
+  # The threshold and the subprocess setting live in [tool.coverage] there.
+  coverage:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - run: uv sync --locked --all-extras --dev
+      - run: uv run --with coverage python -m coverage run -m pytest -q
+      # parallel mode writes one file per process, including every worker.
+      - run: uv run --with coverage python -m coverage combine
+      - run: uv run --with coverage python -m coverage report
+
+  # The README tells a learner to install with `uv tool install --editable .`, and
+  # nothing else here runs that path. It is also what proves the claim that qx
+  # finds the exercises from any directory.
+  install:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - name: Install the way the README says
+        run: |
+          set -euo pipefail
+          uv tool install --editable .
+          # Asked for rather than assumed: the location is uv's to decide.
+          uv tool dir --bin >> "$GITHUB_PATH"
+      - name: Run it from outside the repository
+        run: |
+          set -euo pipefail
+          cd "$HOME"
+          qx version
+          qx doctor
+          qx list
+
+  # The other way in, and the one nothing else covers: installing the built
+  # wheel, with no repository anywhere. That path only works if the wheel really
+  # carries the course and `qx init` really copies it somewhere writable, so this
+  # job takes a learner all the way to a passing exercise rather than stopping at
+  # an exit code.
+  wheel:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - name: Build the wheel
+        run: uv build --wheel --out-dir dist
+      - name: Install it into an environment of its own
+        run: |
+          set -euo pipefail
+          uv venv "$HOME/wheel-env" --python 3.13
+          VIRTUAL_ENV="$HOME/wheel-env" uv pip install dist/*.whl
+      - name: Take a learner through it, with no repository in sight
+        run: |
+          set -euo pipefail
+          qx="$HOME/wheel-env/bin/qx"
+          mkdir -p "$HOME/elsewhere"
+          cd "$HOME/elsewhere"
+
+          # Before anything is copied there is no course, and the message has to
+          # name the command that makes one rather than a repository to go and find.
+          if "$qx" list; then echo "expected qx list to fail before init"; exit 1; fi
+
+          # Captured, not piped into grep. `qx list` exits 2 here by design, and
+          # under pipefail that status is what the whole pipeline reports even
+          # though grep found what it was looking for. The check passed and the
+          # step failed anyway.
+          said=$("$qx" list 2>&1 || true)
+          case "$said" in
+            *init*) ;;
+            *) echo "the pre-init message does not name init: $said"; exit 1 ;;
+          esac
+
+          "$qx" init course
+          cd course
+          "$qx" doctor
+          "$qx" list
+          cp exercises/01_environment/solution.py exercises/01_environment/exercise.py
+          "$qx" run 1
+
+          # Running it again is the upgrade path, and it may not touch an answer.
+          cd ..
+          "$qx" init course
+          grep -q "__version__" course/exercises/01_environment/exercise.py

quantum_exercises-0.8.0/.github/workflows/publish-test.yml

@@ -0,0 +1,68 @@
+name: publish-test
+
+# A rehearsal of publish.yml against TestPyPI, which is a throwaway copy of PyPI.
+#
+# Same build, same guard, same trusted publishing, different endpoint. The point
+# is to find out whether the upload works before the version number is spent:
+# an index accepts a given version exactly once, so a first attempt on the real
+# PyPI is also the last one.
+#
+# Run by hand only. There is no release trigger here, so nothing reaches TestPyPI
+# unless someone asks for it from the Actions tab.
+#
+# The PyPI side is a one time thing, under the project's Publishing settings on
+# test.pypi.org: owner `TuguiDragos`, repository `quantum-exercises`, workflow
+# `publish-test.yml`, environment `testpypi`. Until that exists the job fails at
+# the upload step and changes nothing.
+#
+# Installing the result needs the real PyPI as well, because qiskit and the rest
+# are not on TestPyPI:
+#
+#   uv pip install quantum-exercises \
+#     --index-url https://test.pypi.org/simple/ \
+#     --extra-index-url https://pypi.org/simple/ \
+#     --index-strategy unsafe-best-match
+
+on:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  publish-test:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Build the wheel and the sdist
+        run: uv build
+
+      # Kept identical to publish.yml on purpose. A rehearsal that skips the
+      # guard does not rehearse the thing that matters.
+      - name: Refuse to publish a wheel with no course in it
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import sys, zipfile, pathlib
+          wheel = next(pathlib.Path("dist").glob("*.whl"))
+          names = zipfile.ZipFile(wheel).namelist()
+          exercises = {n.split("/")[3] for n in names if "/_course/exercises/" in n}
+          if len(exercises) < 20:
+              sys.exit(f"{wheel.name} carries {len(exercises)} exercises, expected 20")
+          if not any("/_course/notebooks/" in n for n in names):
+              sys.exit(f"{wheel.name} carries no notebooks")
+          print(f"{wheel.name}: {len(exercises)} exercises and the notebooks are in")
+          PY
+
+      - name: Upload to TestPyPI
+        run: |
+          uv publish --trusted-publishing always \
+            --publish-url https://test.pypi.org/legacy/ \
+            --check-url https://test.pypi.org/simple/

quantum_exercises-0.8.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: publish
+
+# Uploads the distributions to PyPI when a release is published.
+#
+# No token lives anywhere. PyPI is told, once, to trust releases coming from this
+# workflow in this repository, and the job asks GitHub for a short lived identity
+# at run time. That is why the job needs `id-token: write` and nothing else, and
+# why nobody has to rotate a secret.
+#
+# Setting it up on the PyPI side is a one time thing, under the project's
+# Publishing settings: owner `TuguiDragos`, repository `quantum-exercises`,
+# workflow `publish.yml`, environment `pypi`. Until that exists the job fails at
+# the upload step and changes nothing.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # A named environment, so the upload can be held behind a review rule if that
+    # is ever wanted. It costs nothing while no rule is set.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Build the wheel and the sdist
+        run: uv build
+
+      # A wheel without the course installs cleanly and then has nothing to give
+      # `qx init`, which is the one packaging mistake that would reach a reader
+      # rather than a maintainer. Cheaper to check here than to yank a release.
+      - name: Refuse to publish a wheel with no course in it
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import sys, zipfile, pathlib
+          wheel = next(pathlib.Path("dist").glob("*.whl"))
+          names = zipfile.ZipFile(wheel).namelist()
+          exercises = {n.split("/")[3] for n in names if "/_course/exercises/" in n}
+          if len(exercises) < 20:
+              sys.exit(f"{wheel.name} carries {len(exercises)} exercises, expected 20")
+          if not any("/_course/notebooks/" in n for n in names):
+              sys.exit(f"{wheel.name} carries no notebooks")
+          print(f"{wheel.name}: {len(exercises)} exercises and the notebooks are in")
+          PY
+
+      - name: Upload to PyPI
+        run: uv publish --trusted-publishing always

quantum_exercises-0.8.0/.github/workflows/rotate-notes.yml

@@ -0,0 +1,159 @@
+name: Rotate notes
+
+# Rewrites the block between the NOTES markers in README.md with five posts from
+# the author's feed, chosen by a seeded shuffle so the set changes without ever
+# repeating inside a cycle.
+#
+# It is also the only thing in this repository that commits on a schedule, and
+# that is deliberate. GitHub disables a scheduled workflow in a public repository
+# after 60 days with no activity, and this project is meant to reach a state
+# where nobody touches it for months, which is exactly the state that would stop
+# verify.yml without a word. A commit twice a month keeps the clock from ever
+# getting close.
+#
+# Twice a month rather than daily, and the reason is margin rather than cost: a
+# run is about a minute. Sixty days is the limit, and the widest gap between the
+# 1st and the 15th is seventeen days, so two consecutive runs can fail outright
+# before the clock gets anywhere near it. Runs do fail; a GitHub incident took
+# out every job in this repository on the day this was written.
+#
+# Monthly would look tidier and halve that margin twice over: one skipped run
+# puts the gap at sixty-two days, past the limit, from a single bad morning.
+#
+# Cron has no notion of a week of the year, so "every two weeks" is not
+# expressible. Fixed days of the month are, and land close enough.
+
+on:
+  schedule:
+    - cron: "17 4 1,15 * *" # the 1st and the 15th, 04:17 UTC
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  rotate:
+    runs-on: ubuntu-latest
+    permissions:
+      # The one workflow here that writes. Everything else in this repository
+      # runs read-only, so this is the job to look at first if the question is
+      # ever "what can CI change".
+      contents: write
+    steps:
+      # Pinned by commit, like every other action in this repository. It matters
+      # most here: this is the workflow holding write access, so a moved tag
+      # would be a moved tag on the one job that can push.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "24"
+
+      - name: Pick this round's five
+        run: |
+          cat > /tmp/rotate.mjs <<'JS'
+          import { readFileSync, writeFileSync } from "node:fs";
+
+          const FEED = "https://tuguidragos.com/rss/";
+          const decode = (s) => s
+            .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(+n))
+            .replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'");
+
+          const parse = (xml) => [...xml.matchAll(/<item>([\s\S]*?)<\/item>/g)].map((m) => {
+            const grab = (tag) => {
+              const re = new RegExp(`<${tag}>(?:<!\\[CDATA\\[)?([\\s\\S]*?)(?:\\]\\]>)?</${tag}>`);
+              return (m[1].match(re) || [])[1] || "";
+            };
+            return { title: decode(grab("title").trim()), link: grab("link").trim() };
+          }).filter((i) => i.title && i.link);
+
+          // Ghost paginates the feed at 15 posts, so walk pages until one runs dry.
+          const items = [];
+          const links = new Set();
+          for (let page = 1; page <= 30; page++) {
+            const url = page === 1 ? FEED : `${FEED}${page}/`;
+            let res;
+            try {
+              res = await fetch(url);
+            } catch {
+              break;
+            }
+            if (!res.ok) break;
+            const batch = parse(await res.text());
+            if (batch.length === 0) break;
+            let added = 0;
+            for (const it of batch) {
+              if (links.has(it.link)) continue;
+              links.add(it.link);
+              items.push(it);
+              added++;
+            }
+            if (added === 0) break;
+          }
+
+          if (items.length === 0) {
+            console.log("Feed returned no items — leaving README untouched.");
+            process.exit(0);
+          }
+
+          const PER_DAY = 5;
+
+          const shuffle = (arr, seedStr) => {
+            const a = arr.slice();
+            let seed = 2166136261;
+            for (const ch of seedStr) {
+              seed ^= ch.charCodeAt(0);
+              seed = Math.imul(seed, 16777619) >>> 0;
+            }
+            const rand = () => (seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0) / 4294967296;
+            for (let i = a.length - 1; i > 0; i--) {
+              const j = Math.floor(rand() * (i + 1));
+              [a[i], a[j]] = [a[j], a[i]];
+            }
+            return a;
+          };
+
+          const dayNo = Math.floor(Date.now() / 86400000);
+          const perCycle = Math.ceil(items.length / PER_DAY);
+          const cycle = Math.floor(dayNo / perCycle);
+          const slot = ((dayNo % perCycle) + perCycle) % perCycle;
+          const deck = shuffle(items, "cycle-" + cycle);
+
+          const today = [];
+          for (let k = 0; k < PER_DAY && k < deck.length; k++) {
+            today.push(deck[(slot * PER_DAY + k) % deck.length]);
+          }
+          const seen = new Set();
+          const picked = today.filter((i) => !seen.has(i.link) && seen.add(i.link));
+
+          // A square bracket in a post title would end the markdown link early and
+          // leave the rest of the title loose in the README. The titles come from a
+          // feed rather than from this repository, so they are escaped rather than
+          // trusted.
+          const esc = (s) => s.replace(/[[\]]/g, "\\$&");
+
+          const list = picked.map((i) => `- [${esc(i.title)}](${i.link})`).join("\n");
+          const file = "README.md";
+          const md = readFileSync(file, "utf8");
+          const next = md.replace(
+            /<!-- NOTES:START -->[\s\S]*?<!-- NOTES:END -->/,
+            `<!-- NOTES:START -->\n${list}\n<!-- NOTES:END -->`
+          );
+          if (next === md) {
+            console.log("No change.");
+          } else {
+            writeFileSync(file, next);
+            console.log(`Wrote ${picked.length} of ${items.length} posts (deck ${cycle}, slot ${slot + 1}/${perCycle}).`);
+          }
+          JS
+          node /tmp/rotate.mjs
+
+      - name: Commit if changed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          if ! git diff --staged --quiet; then
+            git commit -m "chore: rotate notes" \
+                       -m "Co-authored-by: Țugui Dragoș <contact@tuguidragos.com>"
+            git push
+          fi