nkscan 0.1.0__tar.gz

nkscan-0.1.0/.envrc

@@ -0,0 +1 @@
+use flake

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

@@ -0,0 +1,135 @@
+name: CI
+
+on:
+    push:
+        branches: [main]
+        paths-ignore: &docs-paths
+            - "**.md"
+            - "LICENSE-*"
+    pull_request:
+        branches: [main]
+        paths-ignore: *docs-paths
+    workflow_dispatch:
+
+# Cancel superseded runs for the same branch/PR - these nix jobs are heavy.
+concurrency:
+    group: ci-${{ github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+    packages: write
+
+jobs:
+    check:
+        name: Nix Flake Check
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+            security-events: write # upload clippy findings as code scanning results
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Install Nix
+              uses: DeterminateSystems/nix-installer-action@v13
+
+            - name: Setup Nix cache
+              uses: DeterminateSystems/magic-nix-cache-action@v7
+
+            - name: Run flake checks
+              run: nix flake check --print-build-logs --keep-going
+
+    # The stub is what a consumer sees of an abi3 extension, since one carries no introspectable
+    # signatures. It is generated, so this only has to catch a commit that forgot to regenerate.
+    stubs:
+        name: Stub is up to date
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Install Rust
+              uses: dtolnay/rust-toolchain@master
+              with:
+                  toolchain: "1.96"
+
+            - name: Cache Rust artifacts
+              uses: Swatinem/rust-cache@v2
+
+            # pyo3 needs an interpreter to build against. numpy is not needed: the generator
+            # reads type information rather than calling into it.
+            - name: Install Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.13"
+
+            - name: Regenerate
+              run: cargo run --features python --bin stub_gen
+
+            - name: Fail if it differs from what is committed
+              run: |
+                  if ! git diff --exit-code nkscan.pyi; then
+                    echo "::error::nkscan.pyi is stale, run: cargo run --features python --bin stub_gen"
+                    exit 1
+                  fi
+
+    # The flake checks that the bindings compile, but only a manylinux build proves the wheel a
+    # consumer would actually install. Nix cannot produce one: it links against nix-store glibc
+    # with nix-store rpaths, and the result is tagged linux_x86_64, which no index accepts.
+    #
+    # Run on every change rather than at tag time, when a release is already half published.
+    wheel:
+        name: Build wheel
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Build wheel
+              uses: PyO3/maturin-action@v1
+              with:
+                  args: --release --out dist
+                  manylinux: auto
+
+            # The runner's default python is older than the abi3 floor, so pip would refuse a
+            # cp313 wheel. Both versions are installed to prove the point of abi3: one wheel
+            # covers the floor and every interpreter after it.
+            - name: Install the interpreters the wheel claims to support
+              uses: actions/setup-python@v5
+              with:
+                  python-version: |
+                      3.13
+                      3.14
+
+            - name: Check it is tagged for redistribution
+              run: |
+                  ls -l dist/
+                  # abi3 names one interpreter floor and works on every later one, so a wheel
+                  # tagged for a single version means the abi3 feature stopped taking effect
+                  for wheel in dist/*.whl; do
+                    case "$wheel" in
+                      *abi3-manylinux*) echo "ok: $wheel" ;;
+                      *) echo "::error::$wheel will not install off this machine" && exit 1 ;;
+                    esac
+                  done
+
+            - name: Check it installs and imports on every one of them
+              run: |
+                  for python in python3.13 python3.14; do
+                    echo "--- $python"
+                    "$python" -m pip install --upgrade pip
+                    "$python" -m pip install dist/*.whl
+                    "$python" - <<'PY'
+                  import nkscan, sys
+                  print("  running on", sys.version.split()[0])
+                  # No scanner is attached to a runner, so this exercises enumeration finding none
+                  assert nkscan.list_devices() == []
+                  assert issubclass(nkscan.TransportError, nkscan.TransientError)
+                  try:
+                      nkscan.Session("nonsense")
+                  except nkscan.DeviceNotFound:
+                      pass
+                  print("  import, enumeration and error hierarchy all fine")
+                  PY
+                  done

nkscan-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,178 @@
+name: Release
+
+on:
+    push:
+        tags:
+            - "v*"
+
+permissions:
+    contents: write
+    packages: write
+
+jobs:
+    build-linux:
+        name: Build Linux artifacts
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Install Nix
+              uses: DeterminateSystems/nix-installer-action@v13
+
+            - name: Setup Nix cache
+              uses: DeterminateSystems/magic-nix-cache-action@v7
+
+            - name: Build x86_64 binary
+              run: |
+                  nix build --print-build-logs
+                  cp result/bin/nkscan nkscan-x86_64-unknown-linux-gnu
+
+            - name: Upload Linux binaries to release
+              uses: softprops/action-gh-release@v2
+              with:
+                  files: |
+                      nkscan-x86_64-unknown-linux-gnu
+
+    build-windows:
+        name: Build Windows artifact
+        runs-on: windows-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Install Rust
+              uses: dtolnay/rust-toolchain@master
+              with:
+                  toolchain: "1.96"
+
+            - name: Cache Rust artifacts
+              uses: Swatinem/rust-cache@v2
+
+            - name: Build Windows binary
+              run: |
+                  cargo build --release -p nkscan --features=cli
+                  cp target/release/nkscan.exe nkscan-x86_64-pc-windows-msvc.exe
+
+            - name: Upload Windows binary to release
+              uses: softprops/action-gh-release@v2
+              with:
+                  files: nkscan-x86_64-pc-windows-msvc.exe
+
+    # ---- Python wheels
+    #
+    # maturin rather than nix: a nix-built extension links against nix-store glibc with
+    # nix-store rpaths and its wheel is tagged linux_x86_64, which no index accepts and which
+    # would not load off this machine anyway. maturin builds Linux wheels inside manylinux
+    # containers and runs auditwheel over the result.
+    #
+    # One wheel per platform, not per interpreter: the abi3-py313 feature makes a single build
+    # work on 3.13 and everything after it, which is the floor NegPy asks for.
+    wheels:
+        name: Wheel ${{ matrix.platform }} ${{ matrix.target }}
+        runs-on: ${{ matrix.runner }}
+        strategy:
+            fail-fast: false
+            matrix:
+                include:
+                    - { platform: linux, runner: ubuntu-latest, target: x86_64 }
+                    - { platform: linux, runner: ubuntu-latest, target: aarch64 }
+                    - { platform: macos, runner: macos-latest, target: x86_64 }
+                    - { platform: macos, runner: macos-latest, target: aarch64 }
+                    - { platform: windows, runner: windows-latest, target: x64 }
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Build wheel
+              uses: PyO3/maturin-action@v1
+              with:
+                  target: ${{ matrix.target }}
+                  args: --release --out dist
+                  # Cross-compiles the aarch64 Linux wheel in a manylinux container
+                  manylinux: auto
+                  sccache: "true"
+
+            - name: Upload wheel
+              uses: actions/upload-artifact@v4
+              with:
+                  name: wheel-${{ matrix.platform }}-${{ matrix.target }}
+                  path: dist
+
+    # A version on PyPI can never be reused, and maturin takes the version from Cargo.toml
+    # rather than from the tag, so a mistyped tag would otherwise publish the wrong one.
+    version:
+        name: Tag matches Cargo.toml
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Compare
+              run: |
+                  crate=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)
+                  tag=${GITHUB_REF_NAME#v}
+                  echo "Cargo.toml says $crate, tag says $tag"
+                  if [ "$crate" != "$tag" ]; then
+                    echo "::error::tag $GITHUB_REF_NAME does not match Cargo.toml version $crate"
+                    exit 1
+                  fi
+
+    sdist:
+        name: Source distribution
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Build sdist
+              uses: PyO3/maturin-action@v1
+              with:
+                  command: sdist
+                  args: --out dist
+
+            - name: Upload sdist
+              uses: actions/upload-artifact@v4
+              with:
+                  name: wheel-sdist
+                  path: dist
+
+    publish:
+        name: Publish to PyPI
+        needs: [version, wheels, sdist]
+        runs-on: ubuntu-latest
+        environment: pypi
+        permissions:
+            # Trusted publishing: PyPI verifies this workflow by OIDC, so there is no long-lived
+            # token in the repository. Register the publisher once at
+            # pypi.org/manage/account/publishing with owner, repo and this workflow's filename.
+            id-token: write
+        steps:
+            - name: Collect every wheel and the sdist
+              uses: actions/download-artifact@v4
+              with:
+                  pattern: wheel-*
+                  path: dist
+                  merge-multiple: true
+
+            - name: Publish
+              uses: pypa/gh-action-pypi-publish@release/v1
+              with:
+                  packages-dir: dist
+
+    attach-wheels:
+        name: Attach wheels to the release
+        needs: [version, wheels, sdist]
+        runs-on: ubuntu-latest
+        steps:
+            - name: Collect every wheel and the sdist
+              uses: actions/download-artifact@v4
+              with:
+                  pattern: wheel-*
+                  path: dist
+                  merge-multiple: true
+
+            - name: Upload to release
+              uses: softprops/action-gh-release@v2
+              with:
+                  files: dist/*

nkscan-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+/target
+.direnv
+*.tiff
+nkscan-wb.txt
+result

nkscan-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to this project
+
+All help is welcome and greatly appreciated!
+If you would like to contribute to the project, we ask you adhere to the following policies:
+
+## Before you open a PR
+
+```sh
+cargo fmt
+cargo clippy --all-targets     # should be silent
+cargo test
+rg -nP '[^\x00-\x7F]' src/ examples/    # should find nothing
+```
+
+The source is ASCII only. No em dashes, smart quotes or arrows, in code or comments.
+
+## AI Assistance
+
+Using AI tools to help you contribute is nominally ok, we just want to remind you that
+*you* are asking the maintainers (human people) review your code and you need to be in the loop of that process.
+As such, we ask that you use AI as a tool to help you write code, not as an agent that autonomously generates
+an entire contribution and submits it on your behalf.
+
+A few simple expectations:
+
+- **Understand your code.** You should be able to explain and answer questions about anything you submit.
+- **Write the PR description in your own words.** A short, clear explanation of *your* change is far more useful than a pasted AI summary.
+- **Test your change** before opening the PR.
+- **Keep it focused.** A PR that claims to fix one thing but touches a lot of unrelated code is hard to review (broad prompts tend to cause this).
+- **Disclose AI assistance** in the PR description, along with roughly how much was used (e.g. docs only vs. code generation). Trivial tab-completion of single keywords or short phrases doesn't need to be disclosed.
+
+Example disclosures:
+
+> **AI Disclosure:** This PR was written primarily by Claude Code.
+> **AI Disclosure:** I consulted ChatGPT to understand the codebase, but the solution was authored manually.
+> **AI Disclosure:** None.
+
+Disclosure isn't about discouraging AI use,it just helps reviewers know how much scrutiny a change needs, and it's a courtesy to the humans on the other end of the pull request.