pygenogrove 0.2.0__tar.gz

pygenogrove-0.2.0/.github/scripts/install-htslib-linux.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+#
+# Build htslib from source inside the cibuildwheel manylinux container.
+#
+# genogrove (pulled in via add_subdirectory) does `pkg_check_modules(HTSLIB
+# REQUIRED htslib)`, so htslib must be present at configure/build time even
+# though pygenogrove only binds the interval/grove surface. The manylinux_2_28
+# image (AlmaLinux 8) has no htslib package, so we build it from source into
+# /usr/local; auditwheel then bundles libhts into the repaired wheel.
+#
+# Runs once per container via cibuildwheel's `before-all`.
+set -euo pipefail
+
+HTSLIB_VERSION="${HTSLIB_VERSION:-1.21}"
+# SHA256 of the official htslib-${HTSLIB_VERSION}.tar.bz2 release asset. Pinned so
+# the download is verified before extraction (supply-chain guard in the publish
+# path). Keep in sync with HTSLIB_VERSION — re-verify against the samtools release
+# when bumping. An override of HTSLIB_VERSION without HTSLIB_SHA256 fails closed.
+HTSLIB_SHA256="${HTSLIB_SHA256:-84b510e735f4963641f26fd88c8abdee81ff4cb62168310ae716636aac0f1823}"
+
+# Build deps for htslib (+ the compression/network backends it links).
+dnf install -y \
+    autoconf automake make gcc perl \
+    zlib-devel bzip2-devel xz-devel libcurl-devel openssl-devel
+
+curl -fsSL -o /tmp/htslib.tar.bz2 \
+    "https://github.com/samtools/htslib/releases/download/${HTSLIB_VERSION}/htslib-${HTSLIB_VERSION}.tar.bz2"
+# Verify the tarball against the pinned checksum; abort (no extraction) on mismatch.
+echo "${HTSLIB_SHA256}  /tmp/htslib.tar.bz2" | sha256sum -c -
+mkdir -p /tmp/htslib
+tar -xjf /tmp/htslib.tar.bz2 -C /tmp/htslib --strip-components=1
+
+cd /tmp/htslib
+./configure
+make -j"$(nproc)"
+make install            # -> /usr/local/lib/libhts.so, /usr/local/lib/pkgconfig/htslib.pc
+ldconfig

pygenogrove-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout (with genogrove submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      # The genogrove C++ library (pulled in via add_subdirectory) links htslib,
+      # so it must be present at configure/build time even though pygenogrove
+      # currently only binds the interval/grove surface.
+      - name: Install htslib (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libhts-dev
+
+      - name: Install htslib (macOS)
+        if: runner.os == 'macOS'
+        run: brew install htslib
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      # scikit-build-core drives CMake (fetching pybind11 via FetchContent) and
+      # auto-provisions cmake/ninja if the runner lacks them. The editable
+      # install builds the C++20 extension and makes `import pygenogrove` work.
+      - name: Build and install (with dev extras)
+        run: python -m pip install -e ".[dev]" --verbose
+
+      - name: Run tests
+        run: python -m pytest tests/ -v

pygenogrove-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Release
+
+# Build wheels + sdist on every version tag, then publish to PyPI via Trusted
+# Publishing (OIDC — no API tokens). workflow_dispatch allows a manual run to
+# (re)publish whatever version is in pyproject.toml on the chosen ref.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu = manylinux x86_64; macos-14 = arm64 (Apple Silicon).
+        # No macOS x86_64 wheels: GitHub's Intel macos-13 runners are being
+        # retired and don't reliably allocate (jobs hang queued), and x86_64
+        # can't be cross-compiled here (Homebrew htslib is native-arch only).
+        # Intel Macs install from the sdist.
+        os: [ubuntu-24.04, macos-14]
+    steps:
+      - name: Checkout (with genogrove submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.4.1
+        # All build config (target Pythons, htslib provisioning, smoke test)
+        # lives in [tool.cibuildwheel] in pyproject.toml.
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Source distribution
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout (with genogrove submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-24.04
+    # Only publish on an actual tag push, never on a bare workflow_dispatch test run.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    environment: pypi
+    permissions:
+      id-token: write        # mandatory for Trusted Publishing (OIDC)
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pygenogrove-0.2.0/.gitignore

@@ -0,0 +1,156 @@
+# Created by https://www.toptal.com/developers/gitignore/api/cmake,macos,c++
+# Edit at https://www.toptal.com/developers/gitignore?templates=cmake,macos,c++
+
+### C++ ###
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+### CMake ###
+CMakeLists.txt.user
+CMakeCache.txt
+CMakeFiles
+CMakeScripts
+Testing
+#Makefile
+cmake_install.cmake
+install_manifest.txt
+compile_commands.json
+CTestTestfile.cmake
+_deps
+
+### CMake Patch ###
+CMakeUserPresets.json
+
+# External projects
+*-prefix/
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+build
+.cache
+CLAUDE.md
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+dist/
+*.egg-info/
+.eggs/
+*.egg
+wheels/
+*.whl
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pyright
+.pyright/
+
+# Internal Claude Code config — not for the repo
+.claude/
+
+# End of https://www.toptal.com/developers/gitignore/api/cmake,macos,c++

pygenogrove-0.2.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/genogrove"]
+	path = external/genogrove
+	url = https://github.com/genogrove/genogrove.git

pygenogrove-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to pygenogrove will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-10
+
+### Added
+
+- **Stranded `GenomicCoordinate` key type and `GenomicCoordinateGrove`** — `grove<genomic_coordinate>` exposed as `GenomicCoordinateGrove` / `GenomicCoordinateKey` / `GenomicCoordinateQueryResult` / `GenomicCoordinateFlankingResult`, plus the `GenomicCoordinate` value type (ctor `(strand, start, end)`; `strand`/`start`/`end`; `set_range`/`set_strand`; `overlaps`; comparisons). Overlap is **strand-aware** — equal strands match, `'*'` is a wildcard matching any strand, `'.'` is a concrete unstranded value — and sorting is coordinate-first (start → end → strand, `* < . < + < -`). Dataless grove only; reuses the generic `bind_grove<KeyT, DataT>` template, so insert / strand-aware intersect / flanking / graph overlay / serialization all come for free ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#15](https://github.com/genogrove/pygenogrove/pull/15)).
+
+### Changed
+
+- **PyPI release pipeline** — tagged releases now build manylinux x86_64 + macOS arm64 (Apple Silicon) wheels for CPython 3.9–3.12 and an sdist via cibuildwheel, then publish to PyPI through OIDC Trusted Publishing (no API tokens). htslib is provisioned and bundled into each wheel (built from source on manylinux, Homebrew on macOS), so `pip install pygenogrove` works without a system htslib. **macOS wheels are arm64-only and require macOS 14.0+** (the arm64 Homebrew bottles set the 14.0 floor; genogrove's `std::format` needs libc++ ≥ 13.3 regardless). **Intel Macs install from the sdist** — GitHub's hosted Intel runners are being retired, so x86_64 macOS wheels are not built ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#14](https://github.com/genogrove/pygenogrove/pull/14), [#16](https://github.com/genogrove/pygenogrove/pull/16), [#17](https://github.com/genogrove/pygenogrove/pull/17), [#18](https://github.com/genogrove/pygenogrove/pull/18)).
+
+## [0.1.0] - 2026-06-09
+
+### Added
+
+- **Version introspection** — `pygenogrove.__version__` (single-sourced from `pyproject.toml` at build time, no longer hardcoded in `bindings.cpp`) and `pygenogrove.__genogrove_version__` (the genogrove C++ library version the wheel was built against, read from genogrove's generated `config/version.hpp`). The two version lines follow independent SemVer cadences ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#13](https://github.com/genogrove/pygenogrove/pull/13)).
+- **Graph overlay on `grove<interval>`** — directed-edge operations (`add_edge`, `remove_edge`, `has_edge`, `get_neighbors`, `out_degree`, `edge_count`, `vertex_count_with_edges`) and `add_external_key` for graph-only keys outside the B+ tree index ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#2](https://github.com/genogrove/pygenogrove/pull/2)).
+- **Grove serialization** — `serialize(path)` and static `deserialize(path) -> Grove` over the zlib-compressed `.gg` binary format, with open/write failures surfaced as Python exceptions ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#2](https://github.com/genogrove/pygenogrove/pull/2)).
+- **CI, packaging, and tests** — GitHub Actions matrix build (Linux/macOS × Python 3.9–3.12), scikit-build-core `pyproject.toml`, and pytest suites for the graph overlay and serialization ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#2](https://github.com/genogrove/pygenogrove/pull/2)).
+- **Expanded test coverage** — ported the missing cases from the genogrove C++ suites for the bound surface (interval edge cases, node splits, graph edge directions / traversal / pointer stability, serialization round-trips); test count 25 → 55. The suite now mirrors the genogrove layout: `tests/data_type/` (`test_interval`, `test_key`, `test_query_result`) and `tests/structure/` (`test_dataless_grove`, `test_graph_overlay`, `test_serialization`), with snake_case test names matching the corresponding C++ cases ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#3](https://github.com/genogrove/pygenogrove/pull/3)).
+- **Data-carrying `BedGrove`** — `grove<interval, bed_entry>` exposed as `BedGrove` / `BedKey` / `BedQueryResult`, so prebuilt `.gg` files carrying BED records can be loaded, queried, and traversed from Python. `insert(index, interval, data)` and `add_external_key(interval, data)` take a `BedEntry` payload; `BedKey.data` is a live mutable reference (the payload is not part of B+ tree ordering) while `BedKey.value` is still returned by copy; `serialize`/`deserialize` round-trip the BED data. Also exposes the `BedEntry` value type (+ `BlockInfo` / `ThickInfo` / `RgbColor`). The binding sources were reorganized to mirror the genogrove tree (`src/data_type/`, `src/io/`, `src/structure/`), with the dataless and data-carrying groves sharing one `bind_grove<DataT>` template (the existing `Grove` surface is unchanged) ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#4](https://github.com/genogrove/pygenogrove/pull/4)).
+- **Data-carrying `GffGrove`** — `grove<interval, gff_entry>` exposed as `GffGrove` / `GffKey` / `GffQueryResult` (same surface as `BedGrove`), with the `GffEntry` value type, the `GffFormat` enum, the column-9 `attributes` as a `dict[str, str]`, and the GTF helper accessors (`get_gene_id`, `get_transcript_id`, `get_exon_number`, `get_gene_name`, `get_gene_biotype`, `is_gtf`/`is_gff3`). Reuses the `bind_interval_grove<DataT>` template; tests port the applicable genogrove `gfffile-test.cpp` cases. The data-carrying key value/data/lifetime tests were split into `tests/data_type/test_{bed,gff}_key.py` to match genogrove's `key_type_tests/` layout ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#8](https://github.com/genogrove/pygenogrove/pull/8)).
+
+- **BED/GFF file readers** — `BedReader` and `GffReader`, single-pass Python iterators over BED and GFF3/GTF files yielding `BedEntry` / `GffEntry`. Options are keyword args (`skip_invalid_lines`; `validate_gtf` for GFF); a missing file raises on construction, a malformed line raises `RuntimeError` (unless skipped), and plain/gzip/BGZF (`.gz`) inputs are auto-detected. Both expose `get_error_message()` / `get_current_line()`. Note: the first data record is validated at construction, so a malformed first record raises regardless of `skip_invalid_lines` ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#9](https://github.com/genogrove/pygenogrove/pull/9)).
+- **Sorted / bulk insertion** — `insert_sorted(index, interval, data)` (rightmost-append fast path) and `insert_bulk(index, items, presorted=False)` (insert many `(Interval, data)` records at once; 10–20× faster for large datasets, empty index built bottom-up in O(n)) on the data-carrying groves. Plus **entry-deriving overloads** `insert(index, entry)` and `insert_bulk(index, entries)` that compute the `Interval` key from a BED/GFF record's native coordinates (BED 0-based half-open, GFF 1-based), so callers never hand-convert — the conversion lives in one place (`src/io/entry_interval.hpp`). These require associated data, so they're absent on the dataless `Grove` ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#10](https://github.com/genogrove/pygenogrove/pull/10)).
+- **Nearest-neighbour queries** — `Grove.flanking(query, index) -> FlankingResult` returns the closest non-overlapping keys on either side of a query (`.predecessor` / `.successor`, each a `Key` or `None`); keys overlapping the query are excluded and, for nested intervals, the predecessor is the one with the largest end (smallest gap). Exposed on all groves (`FlankingResult` / `BedFlankingResult` / `GffFlankingResult`); the result and its keys keep the grove alive ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#11](https://github.com/genogrove/pygenogrove/pull/11)).
+
+### Fixed
+
+- **`intersect()` result lifetime** — the `QueryResult` returned by `Grove.intersect()` (and the keys it yields) now keep the grove alive via `keep_alive<0,1>`. Previously a key or `.data`/`.value` reference materialized from an intersect result could outlive the grove, a latent use-after-free affecting every grove instantiation ([#8](https://github.com/genogrove/pygenogrove/pull/8)).
+
+### Refactored
+
+- **Generalized the grove binding templates over the key type** — `bind_grove<KeyT, DataT>` (and `bind_key` / `bind_query_result` / `bind_flanking_query_result`) replace the interval-hardcoded versions, so additional key types can be added by instantiation rather than near-duplicate headers; the now-generic `interval_key.hpp` / `interval_grove.hpp` were renamed to `key.hpp` / `grove.hpp`. No change to the Python API ([#1](https://github.com/genogrove/pygenogrove/issues/1), [#12](https://github.com/genogrove/pygenogrove/pull/12)).

pygenogrove-0.2.0/CMakeLists.txt

@@ -0,0 +1,62 @@
+cmake_minimum_required(VERSION 3.15)
+project(pygenogrove)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Single source of truth for the package version: pyproject.toml. scikit-build-core
+# passes it in as SKBUILD_PROJECT_VERSION, which we forward to the module as a
+# compile definition (see target_compile_definitions below) so the version lives
+# in exactly one place. A plain `cmake` dev build (no scikit-build-core) gets a
+# clearly-non-release marker instead of a stale hardcoded number.
+if(DEFINED SKBUILD_PROJECT_VERSION)
+    set(PYGENOGROVE_VERSION "${SKBUILD_PROJECT_VERSION}")
+else()
+    set(PYGENOGROVE_VERSION "0.0.0+local")
+endif()
+
+# Fetch pybind11
+include(FetchContent)
+FetchContent_Declare(
+    pybind11
+    GIT_REPOSITORY https://github.com/pybind/pybind11.git
+    GIT_TAG v2.13.6
+)
+FetchContent_MakeAvailable(pybind11)
+
+# Add genogrove library — build it as a library only. Its test/CLI/benchmark
+# targets need generated headers (e.g. config/version.hpp) and extra deps we
+# don't use here, and would otherwise break the wheel build.
+set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
+set(BUILD_CLI OFF CACHE BOOL "" FORCE)
+set(BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE)
+# genogrove's static lib must be position-independent so it can be linked
+# into the pybind11 shared module (.so); otherwise ld rejects the relocation.
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+add_subdirectory(external/genogrove)
+
+# Create Python module
+pybind11_add_module(pygenogrove src/bindings.cpp)
+target_link_libraries(pygenogrove PRIVATE genogrove)
+target_include_directories(pygenogrove PRIVATE
+    ${CMAKE_SOURCE_DIR}/external/genogrove/include
+    # genogrove's version macros live in a header it generates at configure time
+    # into its own binary dir; expose it so bindings.cpp can report which
+    # genogrove it was built against (pygenogrove.__genogrove_version__).
+    ${genogrove_BINARY_DIR}/include
+)
+
+# PYGENOGROVE_VERSION -> pygenogrove.__version__ (single-sourced from pyproject.toml).
+target_compile_definitions(pygenogrove PRIVATE
+    PYGENOGROVE_VERSION="${PYGENOGROVE_VERSION}"
+)
+
+# Set output directory
+set_target_properties(pygenogrove PROPERTIES
+    LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}
+)
+
+# Install the extension into the wheel root so `import pygenogrove` resolves.
+# scikit-build-core populates the wheel from the CMake install tree; without
+# this rule the module is built but never packaged, leaving it unimportable.
+install(TARGETS pygenogrove LIBRARY DESTINATION .)