oxihipo 0.1.0__tar.gz

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

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo test --all-targets
+      # High-level smoke test: `cargo test` compiles the examples but never runs
+      # them, so a runtime break (panic, bad logic) ships silently. Drive the
+      # core examples end-to-end — write → read → recook to Lz4PerBank → read
+      # back, tag-and-skim round-trip, plus a small all-format encode/read sweep.
+      - name: Smoke-run examples
+        run: |
+          cargo run --example write -- /tmp/demo.hipo
+          cargo run --example read -- /tmp/demo.hipo
+          cargo run --example recook_by_bank -- /tmp/demo.hipo /tmp/demo_bybank.hipo
+          cargo run --example read -- /tmp/demo_bybank.hipo
+          cargo run --example tag_and_skim -- /tmp/tagdemo
+          cargo run --example bench_read_compression -- 3000 1
+      - run: cargo doc --no-deps
+        env:
+          RUSTDOCFLAGS: -D warnings

oxihipo-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: docs
+
+# Build the Docusaurus site on every PR (so a broken link or bad MDX fails
+# review, not main), and deploy to GitHub Pages on push to main.
+#
+# ONE-TIME SETUP: GitHub Pages must be enabled for the repo with its source set
+# to "GitHub Actions" (Settings → Pages → Build and deployment → Source).
+# This workflow deliberately does not use `configure-pages`' `enablement: true`,
+# because that input requires a token with `administration:write` (a PAT or App
+# token) — the default GITHUB_TOKEN cannot enable Pages.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'website/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+defaults:
+  run:
+    working-directory: website
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      # `onBrokenLinks: 'throw'` means a dead cross-reference fails here.
+      - name: Build
+        run: npm run build
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: website/build
+
+  deploy:
+    name: deploy
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write # to deploy
+      id-token: write # to verify the deployment origin
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

oxihipo-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,181 @@
+name: wheels
+
+# Build (and, on a tag, publish) the `oxihipo` Python wheels. The extension is
+# abi3 (one wheel per OS/arch works on CPython >= 3.13) and pure-Rust
+# (default-features = false), so the aarch64 / cross builds need no C toolchain.
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: wheels-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Native build + the full pytest suite on each OS — fast confidence that the
+  # binding imports and behaves, before spending time on the cross wheels.
+  test:
+    name: test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: py
+      - name: Build the extension (native)
+        working-directory: py
+        run: |
+          python -m pip install --upgrade pip maturin
+          maturin build --release --out dist -i python
+      - name: Install wheel + test dependencies
+        run: |
+          python -m pip install numpy awkward pandas pyarrow pytest "mypy~=2.3"
+          python -m pip install --no-index --find-links py/dist oxihipo --no-deps
+      - name: Run the binding's test suite
+        run: python -m pytest py/tests -q
+      - name: Type-check the pure-Python package (mypy)
+        working-directory: py
+        run: python -m mypy
+      - name: Check the compiled stub matches the extension (stubtest)
+        working-directory: py
+        run: python -m mypy.stubtest oxihipo._oxihipo
+      - name: Assert the py.typed marker ships in the wheel (PEP 561)
+        run: |
+          python - <<'PY'
+          import glob, zipfile
+          whl = sorted(glob.glob("py/dist/*.whl"))[-1]
+          names = zipfile.ZipFile(whl).namelist()
+          assert any(n.endswith("oxihipo/py.typed") for n in names), \
+              f"py.typed missing from {whl}: {names}"
+          print("py.typed present in", whl)
+          PY
+
+  linux:
+    name: wheels linux ${{ matrix.target }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          working-directory: py
+          target: ${{ matrix.target }}
+          manylinux: auto
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v5
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: py/dist
+
+  macos:
+    name: wheels macos ${{ matrix.target }}
+    runs-on: macos-14
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          working-directory: py
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v5
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: py/dist
+
+  windows:
+    name: wheels windows
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          working-directory: py
+          target: x64
+          args: --release --out dist
+          sccache: "true"
+      - uses: actions/upload-artifact@v5
+        with:
+          name: wheels-windows-x64
+          path: py/dist
+
+  sdist:
+    name: sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          working-directory: py
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v5
+        with:
+          name: wheels-sdist
+          path: py/dist
+
+  # Fail fast if the pushed tag doesn't match the packaged version, before the
+  # (irreversible) publish. `v0.1.0` must match `version` in py/pyproject.toml.
+  tag-check:
+    name: tag matches version
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Assert tag == pyproject version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          proj=$(grep -m1 '^version' py/pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          echo "tag=$tag  pyproject=$proj"
+          test "$tag" = "$proj" || { echo "::error::tag v$tag does not match py/pyproject.toml version $proj"; exit 1; }
+
+  # Publish to PyPI on a version tag via Trusted Publishing (OIDC) — no stored
+  # token. One-time setup: on PyPI add a "pending publisher" for project
+  # `oxihipo`, repo `mathieuouillon/oxihipo`, workflow `wheels.yml`, environment
+  # `pypi`. The OIDC `id-token` below is exchanged for a short-lived upload
+  # credential; PEP 740 attestations are generated automatically.
+  release:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [tag-check, test, linux, macos, windows, sdist]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oxihipo
+    permissions:
+      id-token: write # mint the OIDC token Trusted Publishing verifies
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true # flatten every artifact into dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

oxihipo-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Build artifacts
+/target
+**/*.rs.bk
+
+# Profiling
+*.profraw
+*.profdata
+perf.data*
+flamegraph.svg
+
+# Editor backups & swap files
+*~
+*.swp
+*.swo
+
+# IDE state
+.idea/
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Local fixtures (large data files kept outside the repo)
+fixtures/large/
+
+# Analysis / example output artifacts
+/out
+
+# Generated docs (build from the .typ source with `typst compile`)
+/docs/*.pdf
+
+# Local env / secrets
+.env
+.env.local
+
+# Local tooling
+.claude/

oxihipo-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the
+version is below `1.0.0`, minor releases may contain breaking changes.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-20
+
+First public release: a pure-Rust HIPO (CLAS12) v6 reader and writer, with a
+columnar, [uproot](https://uproot.readthedocs.io)-shaped Python binding whose
+columns come back as zero-copy [Awkward](https://awkward-array.org) arrays.
+
+### Added
+
+- **Python reading** — `open` a file / directory / glob / list; `arrays`,
+  `array`, and a raw-NumPy `numpy` accessor; `library=` backends `ak` (default),
+  `np`, `pd` (pandas), and `arrow` (pyarrow); bank proxies (`f["REC::Particle"]`),
+  `filter_name` globs, `entry_start`/`entry_stop`, and discovery (`keys`,
+  `typenames`, `show`).
+- **Bounded-memory streaming** — `iterate(step_size=…)` in event- or byte-sized,
+  record/file-aligned chunks; multi-process reading with `workers=N` for
+  I/O-bound parallel filesystems.
+- **Python writing** — `create` a new file or `recreate` to *decorate* an
+  existing one with a derived bank (verbatim event copy); columnar `new_bank` /
+  `extend` from NumPy or Awkward, scalar and fixed-length `T#N` array columns.
+- **Event tags** — pushdown `filtered(event_tag=…/event_tag_any=…)`, the
+  `event_tags()` column, a persisted name↔bit registry (`tag_names`, filter by
+  name), tag-and-skim (`skim(tags=…, tag_names=…)`), and in-place
+  `set_event_tag` / `set_event_tags` for uncompressed files.
+- **ROOT RDataFrame bridge** — `rdataframe` / `iterate_rdataframe` feed a
+  selection to ROOT's RDataFrame through Awkward's generated (no-copy)
+  `RDataSource`; optional `oxihipo[root]` extra.
+- **Compression** — six formats (`none`, `lz4`, `lz4best`, `gzip`, `lz4perbank`,
+  `lz4percolumn`); `skim` re-compresses and defaults to `lz4percolumn`.
+- **Rust core** — HIPO v6 reader/writer, `Chain` with pushdown filters, typed
+  bank rows and the `bank_row!` / `clas12` helpers, and a columnar `read_columns`
+  materializer behind a released GIL.
+- **Packaging** — `abi3` wheels (one per OS/arch, CPython ≥ 3.13) for Linux
+  (x86_64/aarch64), macOS (x86_64/aarch64), and Windows (x64), plus an sdist;
+  PEP 561 typed (`py.typed`, checked stub).
+
+[Unreleased]: https://github.com/mathieuouillon/oxihipo/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mathieuouillon/oxihipo/releases/tag/v0.1.0