batchcorder 0.1.0__tar.gz → 0.1.2__tar.gz

batchcorder-0.1.2/.github/release-drafter.yml

@@ -0,0 +1,78 @@
+exclude-labels:
+  - ignore
+  - release
+  - dependencies
+name-template: 'batchcorder unreleased'
+version-template: unreleased
+
+change-template: '- $TITLE (#$NUMBER)'
+
+autolabeler:
+  - label: 'release'
+    title:
+      - '/^release:/i'
+  - label: 'dependencies'
+    title:
+      - '/^chore\(deps\):/i'
+      - '/^fix\(deps\):/i'
+  - label: 'perf'
+    title:
+      - '/^perf(\(.*\))?:/i'
+  - label: 'feature'
+    title:
+      - '/^feat(\(.*\))?:/i'
+  - label: 'fix'
+    title:
+      - '/^fix(\(.*\))?:/i'
+  - label: 'docs'
+    title:
+      - '/^docs(\(.*\))?:/i'
+      - '/^chore\(docs\):/i'
+  - label: 'ci'
+    title:
+      - '/^ci(\(.*\))?:/i'
+      - '/^chore\(ci\):/i'
+  - label: 'chore'
+    title:
+      - '/^chore(\(.*\))?:/i'
+  - label: 'internal'
+    title:
+      - '/^ref(\(.*\))?:/i'
+      - '/^refactor(\(.*\))?:/i'
+      - '/^spike(\(.*\))?:/i'
+
+categories:
+  - title: 🚀 Performance improvements
+    labels:
+      - performance
+      - perf
+  - title: ✨ Enhancements
+    labels:
+      - feature
+      - enhancement
+  - title: 🐞 Bug fixes
+    labels:
+      - fix
+      - bugfix
+      - bug
+  - title: 📖 Documentation
+    labels:
+      - documentation
+      - docs
+  - title: 📦 Build system
+    labels:
+      - build
+      - ci
+      - chore
+  - title: 🛠️ Other improvements
+    labels:
+      - internal
+      - maintenance
+
+template: |
+  ## Changes
+
+  $CHANGES
+
+  Thank you to all our contributors for making this release possible!
+  $CONTRIBUTORS

batchcorder-0.1.2/.github/workflows/ci-test.yaml

@@ -0,0 +1,188 @@
+name: ci-test
+
+on:
+  push:
+    paths-ignore:
+      - "docs/**"
+      - "**/*.md"
+      - "*.md"
+      - ".envrc"
+    branches:
+      - main
+    tags:
+      - '*'
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    runs-on: ubuntu-latest
+    env:
+      UV_NO_SYNC: "1"
+    strategy:
+      matrix:
+        # requires-python = ">=3.10"; test the floor and the latest stable.
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Update Rust stable
+        run: rustup update stable && rustup component add llvm-tools-preview
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cargo cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            ./target/
+          # abi3-py310 produces a single binary regardless of Python version,
+          # so the cache key does not include python-version.
+          key: cargo-test-${{ hashFiles('**/Cargo.toml', '**/Cargo.lock') }}
+          restore-keys: cargo-test-
+
+      # --no-install-project: maturin develop handles the batchcorder install.
+      - name: Install Python dependencies
+        run: uv sync --locked --group dev --no-install-project
+
+      - name: Build and test with coverage
+        env:
+          CARGO_INCREMENTAL: "1"
+        run: |
+          eval "$(cargo llvm-cov show-env --export-prefix)"
+          cargo llvm-cov clean --workspace
+          cargo test
+          uv run maturin develop --uv
+          uv run pytest --import-mode=importlib --cov --cov-report=xml
+          cargo llvm-cov report --lcov --output-path coverage.lcov
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5.4.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml,coverage.lcov
+
+  windows:
+    runs-on: windows-latest
+    env:
+      UV_NO_SYNC: "1"
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Update Rust stable
+        run: rustup update stable && rustup component add llvm-tools-preview
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cargo cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            ./target/
+          key: cargo-test-windows-${{ hashFiles('**/Cargo.toml', '**/Cargo.lock') }}
+          restore-keys: cargo-test-windows-
+
+      - name: Install Python dependencies
+        run: uv sync --locked --group dev --no-install-project
+
+      - name: Build and test with coverage
+        shell: bash
+        env:
+          CARGO_INCREMENTAL: "1"
+        run: |
+          eval "$(cargo llvm-cov show-env --export-prefix)"
+          cargo llvm-cov clean --workspace
+          cargo test
+          uv run maturin develop --uv
+          uv run pytest --import-mode=importlib --cov --cov-report=xml
+          cargo llvm-cov report --lcov --output-path coverage.lcov
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5.4.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml,coverage.lcov
+
+  macos:
+    runs-on: macos-latest
+    env:
+      UV_NO_SYNC: "1"
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Update Rust stable
+        run: rustup update stable
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cargo cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            ./target/
+          key: cargo-test-macos-${{ hashFiles('**/Cargo.toml', '**/Cargo.lock') }}
+          restore-keys: cargo-test-macos-
+
+      - name: Install Python dependencies
+        run: uv sync --locked --group dev --no-install-project
+
+      - name: Build extension
+        uses: PyO3/maturin-action@v1
+        with:
+          command: develop
+          args: --release --strip --uv
+          sccache: 'true'
+
+      - name: Run tests
+        run: uv run pytest --import-mode=importlib

batchcorder-0.1.2/.github/workflows/release-drafter.yml

@@ -0,0 +1,24 @@
+name: release-drafter
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, reopened, synchronize, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  update-release-draft:
+    permissions:
+      contents: write       # to create/update draft release
+      pull-requests: write  # to add labels to PRs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        with:
+          config-name: release-drafter.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{batchcorder-0.1.0 → batchcorder-0.1.2}/.gitignore

@@ -88,3 +88,5 @@ docs/source/_autoapi/
 !src/bin
 
 site
+
+drafts

{batchcorder-0.1.0 → batchcorder-0.1.2}/.pre-commit-config.yaml

@@ -66,7 +66,7 @@ repos:
     rev: v0.11.0.1
     hooks:
       - id: shellcheck
-        args: ["scripts/build-docs.sh"]
+        args: ["scripts/build-docs.sh", "scripts/build-release.sh"]
 
   - repo: local
     hooks:
@@ -110,7 +110,7 @@ repos:
       - id: mypy-stubtest
         name: mypy stubtest
         description: Validate _batchcorder.pyi matches the compiled extension at runtime.
-        entry: .venv/bin/python -m mypy.stubtest batchcorder._batchcorder
+        entry: .venv/bin/python -m mypy.stubtest --mypy-config-file pyproject.toml batchcorder._batchcorder
         language: system
         pass_filenames: false
         types_or: [python, pyi]

batchcorder-0.1.2/CLAUDE.md

@@ -0,0 +1,326 @@
+# batchcorder Repository
+
+This repository contains batchcorder, a Rust-backed Python library for caching Arrow record-batch streams so they can be replayed multiple times from a source that can only be read once.
+
+## 📦 Architecture
+
+The project consists of:
+
+- **Python API** (`python/`): Python interface and bindings
+- **Rust Core** (`src/`): Core implementation in Rust using PyO3 for Python bindings
+- **Tests** (`tests/`): Test suite for verifying functionality
+- **Documentation** (`docs/`): Project documentation
+
+The Rust core implements the `StreamCache` functionality using:
+- Arrow C Stream interface for compatibility
+- Arrow IPC stream format for on-disk serialisation
+- PyO3 for Python interoperability
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Python 3.11+
+- Rust toolchain (stable)
+- `uv` for dependency management
+
+### Setup Commands
+
+```bash
+# Install dependencies without building the extension
+uv sync --no-install-project --dev
+
+# For docs development, include docs group
+uv sync --no-install-project --dev --group docs
+
+# Build the extension
+uv run maturin develop --uv
+```
+
+### Environment variables
+
+Set `UV_NO_SYNC=1` in your shell so that `uv run` never re-syncs the
+virtual environment on every invocation:
+
+```bash
+export UV_NO_SYNC=1
+```
+
+Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) to make it
+permanent for this project.
+
+## 🧪 Testing
+
+### Run Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test files or modules
+uv run pytest tests/test_module.py
+```
+
+### Testing Guidelines
+
+- All changes must be tested
+- Look to see if your tests could go in an existing file before adding a new file
+- Get your tests to pass before committing
+- Run `uv run pre-commit run --all-files` before pushing code
+
+## 📝 Code Style
+
+### Rust Guidelines
+
+- Avoid patterns that require `panic!`, `unreachable!`, or `.unwrap()`
+- Prefer let chains (`if let` combined with `&&`) over nested `if let` statements
+- Use `#[expect()]` over `[allow()]` for suppressing Clippy lints
+- Use comments purposefully to explain invariants and unusual decisions
+
+### Python Guidelines
+
+- Follow existing code style in neighboring files
+- Use type hints where appropriate
+- Keep functions small and focused
+
+### Code Examples
+
+```rust
+// ✅ Good: Proper error handling with let chains
+if let Some(value) = optional_value && value.is_valid() {
+    // Handle valid value
+    process_value(value);
+}
+
+// ❌ Bad: Nested if let statements
+if let Some(value) = optional_value {
+    if value.is_valid() {
+        // Handle valid value
+        process_value(value);
+    }
+}
+```
+
+```python
+# ✅ Good: Type hints and clear function naming
+def calculate_total(items: List[Item]) -> float:
+    """Calculate the total price of items."""
+    return sum(item.price for item in items)
+
+# ❌ Bad: No type hints, vague function name
+def process(x):
+    # Process something
+    pass
+```
+
+## 📂 Project Structure
+
+```
+batchcorder/
+├── python/          # Python API and bindings
+├── src/             # Rust core implementation
+├── tests/           # Test suite
+├── docs/            # Documentation
+├── CONTRIBUTING.md  # Contribution guidelines (this file)
+└── README.md         # Human-readable overview
+```
+
+## 🔧 Development Workflow
+
+1. **Create a feature branch**: `git checkout -b feature/your-feature`
+2. **Make changes**: Follow code style guidelines
+3. **Run tests**: `uv run pytest`
+4. **Run pre-commit**: `uv run pre-commit run --all-files`
+5. **Commit changes**: Use clear, descriptive commit messages
+6. **Push and create PR**: Get code review before merging
+
+## 🚢 Releasing
+
+### Prerequisites
+
+Install `cargo-edit` for version bumping:
+
+```bash
+cargo install cargo-edit
+```
+
+### Release Process
+
+Use the release script, passing the bump type as an argument:
+
+```bash
+bash scripts/build-release.sh <major|minor|patch>
+```
+
+This will:
+1. Switch to upstream `main` and pull the latest changes
+2. Bump the version in `Cargo.toml` using `cargo set-version --bump`
+3. Create a `release-<version>` branch
+4. Commit the version change
+5. Push the branch to upstream
+
+## 🛑 Boundaries
+
+### Never Touch
+
+- `.env*` files - Environment variables
+- `target/` - Rust build artifacts
+- `__pycache__/` - Python cache files
+- `node_modules/` - Node.js dependencies (if any)
+- `*.lock` files - Dependency lock files
+
+### Always Do
+
+- Write tests for new functionality
+- Run existing tests before committing
+- Follow code style guidelines
+- Document public APIs
+
+### Ask First
+
+- Major architectural changes
+- Breaking changes to public APIs
+- Changes to CI/CD configuration
+- Dependency updates
+
+## 📖 Documentation
+
+### Dependencies
+
+Documentation requires:
+- Quarto for rendering .qmd files to Markdown
+- Sphinx for building HTML documentation
+- Python dependencies listed in `docs/requirements.txt`
+
+Install documentation dependencies:
+```bash
+uv sync --no-install-project --dev --group docs
+```
+
+### Building Documentation
+
+```bash
+# Render Quarto files to Markdown
+make quarto
+
+# Build Sphinx HTML documentation
+make sphinx
+
+# Build both (quarto + sphinx)
+make docs
+
+# Clean documentation build artifacts
+make clean-docs
+```
+
+### Quarto Usage
+
+- Quarto source files are in `docs/quarto/`
+- Configuration in `docs/quarto/_quarto.yml`
+- Code execution is disabled in Quarto (requires compiled Rust extension)
+- Output directory: `docs/source/`
+
+### Documentation Structure
+
+```
+docs/
+├── quarto/           # Quarto source files (.qmd)
+│   ├── how-to/       # How-to guides
+│   ├── reference/    # Reference documentation
+│   ├── tutorials/    # Tutorials
+│   └── _quarto.yml   # Quarto configuration
+├── source/           # Generated Markdown files
+├── build/            # Built HTML documentation
+├── requirements.txt  # Documentation dependencies
+└── Makefile           # Documentation build targets
+```
+
+### Documentation Guidelines
+
+- Write for a developer audience
+- Focus on clarity and practical examples
+- Keep documentation up-to-date with code changes
+- Use Markdown format for documentation files
+- Follow the structure defined in Quarto configuration
+
+## 🤖 Agent-Specific Instructions
+
+### For Coding Agents
+
+- You are a Rust/Python developer working on the batchcorder project
+- Focus on the Rust core (`src/`) and Python bindings (`python/`)
+- Follow the existing architecture and patterns
+- Never modify files outside the project scope
+
+### For Documentation Agents
+
+- You are a technical writer for the batchcorder project
+- Read code from `src/` and `python/` to understand functionality
+- Write documentation in `docs/quarto/` using Quarto format
+- Follow the documentation guidelines above
+
+### For Testing Agents
+
+- You are a QA engineer for the batchcorder project
+- Write tests in the `tests/` directory
+- Ensure tests cover edge cases and error conditions
+- Never remove failing tests without authorization
+
+## 🔄 Version Control
+
+### Git Workflow
+
+- Use feature branches for new functionality
+- Use fix branches for bug fixes
+- Create draft PRs for work-in-progress
+- Require at least one approval before merging
+- Squash merge for clean history
+
+### Commit Message Format
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+Where:
+- `type`: feat, fix, docs, style, refactor, perf, test, chore
+- `scope`: module or component affected
+- `subject`: brief description of changes
+- `body`: detailed explanation (optional)
+- `footer`: breaking changes or issue references (optional)
+
+## 🔒 Security
+
+### Security Guidelines
+
+- Never commit secrets or API keys
+- Keep dependencies up-to-date
+- Follow Rust's security best practices
+- Use secure coding practices in Python
+
+## 📚 Resources
+
+- [Arrow Documentation](https://arrow.apache.org/docs/)
+- [PyO3 Documentation](https://pyo3.rs/)
+- [Rust Documentation](https://doc.rust-lang.org/)
+- [Python Documentation](https://docs.python.org/3/)
+- [Quarto Documentation](https://quarto.org/docs/)
+- [Sphinx Documentation](https://www.sphinx-doc.org/)
+
+## 🤝 Contributing
+
+We welcome contributions! Please:
+
+1. Read the CONTRIBUTING.md file thoroughly
+2. Follow the development guidelines
+3. Write tests for your changes
+4. Submit a pull request with clear description
+5. Be responsive to feedback and reviews
+
+## 📜 License
+
+This project is licensed under the Apache License. See the LICENSE file for details.