pyrjson 0.2.0__tar.gz

pyrjson-0.2.0/.cargo/config.toml

@@ -0,0 +1,15 @@
+# Build configuration.
+#
+# x86_64 targets x86-64-v2 (SSE4.2/SSSE3/POPCNT, every x86_64 CPU since ~2009),
+# like orjson's wheels. Do NOT use target-cpu=native: wheels built that way
+# crash with SIGILL on older CPUs, and on the benchmark Xeon, BMI2 codegen
+# (enabled by native / x86-64-v3) made zmij float formatting ~1.6x slower
+# (33ns vs 20ns per float in dumps).
+#
+# One cfg entry covers every x86_64 target (linux-gnu, linux-musl, darwin,
+# windows-msvc/gnu). Setting RUSTFLAGS in the environment silently replaces
+# these flags; pass extra flags via CARGO_TARGET_<TRIPLE>_RUSTFLAGS, which
+# cargo merges with them (scripts/build_pgo.sh does this).
+
+[target.'cfg(target_arch = "x86_64")']
+rustflags = ["-C", "target-cpu=x86-64-v2"]

pyrjson-0.2.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+# Weekly update PRs. Actions are pinned to commit SHAs; Dependabot bumps the
+# SHA and the version comment together. Grouped to keep the PR count low.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      cargo-minor:
+        update-types: [minor, patch]
+    # PyO3 upgrades touch the doc-hidden trampoline API (src/entry.rs) and
+    # need the version checks in CLAUDE.md; take them deliberately.
+    ignore:
+      - dependency-name: pyo3
+        update-types: [version-update:semver-major, version-update:semver-minor]

pyrjson-0.2.0/.github/instructions/leader.instructions.md

@@ -0,0 +1,62 @@
+---
+applyTo: '**/*.md'
+---
+# AI Coding Leader Instructions for Python-Rust Integration Project
+
+## Project Overview
+This project integrates Python and Rust, using Rust for performance-critical operations while providing Pythonic interfaces. The core functionality is implemented in Rust with Python bindings.
+
+## Technology Stack
+- **Rust**: Core implementation
+- **Python**: User-facing API
+- **PyO3**: Python bindings for Rust
+- **Maturin**: Build system for Python extensions written in Rust
+
+## Coding Standards
+
+### Rust Standards
+- Follow Rust idiomatic practices and official style guide
+- Use 2021 edition of Rust
+- Leverage strong typing and ownership system
+- Use Result/Option for error handling, avoid panics
+- Format code with `rustfmt` and lint with `clippy`
+- Document all public APIs with rustdoc
+
+### Python Standards
+- Follow PEP 8 style guidelines
+- Use type hints (PEP 484)
+- Format with Black and check with flake8
+- Write docstrings in Google style
+- Target Python 3.7+ compatibility
+
+## Integration Guidelines
+- Create Pythonic APIs that hide Rust implementation details
+- Handle memory management carefully at language boundaries
+- Convert between Rust and Python types safely
+- Propagate errors appropriately between languages
+
+## Project Structure
+- `/src/`: Rust implementation
+- `/python/`: Python interface code
+- `/tests/`: Test suites for both languages
+- `/examples/`: Example usage
+- `/docs/`: Documentation
+- `/benches/`: Performance benchmarks
+
+## Testing Requirements
+- Unit tests for both languages
+- Integration tests across language boundary
+- Benchmark performance-critical code
+- Test in CI pipeline
+
+## Documentation
+- Document APIs in both languages
+- Include examples and usage patterns
+- Explain performance characteristics
+- Keep README updated with installation and usage instructions
+
+## Performance Considerations
+- Profile code to identify bottlenecks
+- Minimize Python/Rust boundary crossings
+- Consider parallelism for CPU-bound operations
+- Benchmark critical paths

pyrjson-0.2.0/.github/instructions/python-enginner.instructions.md

@@ -0,0 +1,39 @@
+---
+applyTo: '**/*.py'
+---
+# Senior Python Engineer Coding Standards
+
+## General Approach
+- Write code as a senior Python engineer would: prioritize readability, maintainability, and efficiency
+- Use Python 3.11+ syntax and features when appropriate
+- Follow a systematic problem-solving approach: understand requirements, plan implementation, code, test, and refactor
+- Before coding, outline a clear strategy considering edge cases, performance implications, and maintainability
+
+## Code Style & Organization
+- Follow PEP 8 style guidelines consistently
+- Use meaningful variable/function names that convey purpose
+- Organize code into logical modules and packages
+- Limit function/method size to maintain readability (typically under 50 lines)
+- Use appropriate design patterns where they simplify the code
+
+## Documentation & Type Hints
+- Write clear, concise docstrings for all public functions, classes, and modules
+- Use type hints consistently to improve code understanding and static analysis
+- Include examples in docstrings for complex functions
+- Add inline comments only for non-obvious code sections
+
+## Best Practices
+- Prefer built-in functions and standard library modules over third-party packages for simple tasks
+- Write idiomatic Python (e.g., use list comprehensions, generators where appropriate)
+- Handle errors gracefully using try/except with specific exception types
+- Use context managers for resource management
+- Implement appropriate logging rather than print statements
+- Write modular, reusable, and testable code
+- Practice defensive programming for robust error handling
+
+## Performance & Security
+- Avoid premature optimization; focus on correct and clear code first
+- Be mindful of performance implications for large datasets
+- Use appropriate data structures for the problem at hand
+- Validate all inputs, especially in public-facing interfaces
+- Follow security best practices when handling sensitive data

pyrjson-0.2.0/.github/instructions/rust-engineer.instructions.md

@@ -0,0 +1,60 @@
+---
+applyTo: '**/*.rs'
+---
+# Senior Rust Engineering Guidelines
+
+## Code Style and Organization
+- Follow the official Rust style guide and idioms from rust-lang/rust
+- Use snake_case for variables and functions, CamelCase for types and traits
+- Organize code with clear module hierarchy and separation of concerns
+- Keep functions focused and concise (ideally under 50 lines)
+- Use meaningful variable and function names that convey intent
+
+## Safety and Error Handling
+- Prefer Result over panic/unwrap in public APIs
+- Use `?` operator for clean error propagation
+- Implement custom error types for libraries using thiserror or similar
+- Handle all error cases explicitly; avoid ignoring errors
+- Use `#[must_use]` for Results that shouldn't be ignored
+
+## Performance
+- Minimize heap allocations where possible
+- Consider using Cow<T> for flexible ownership
+- Use iterators and avoid unnecessary collecting
+- Profile before optimizing; focus on measured bottlenecks
+- Use appropriate data structures for the task (e.g., HashMap vs BTreeMap)
+
+## Memory Management
+- Leverage Rust's ownership system; avoid unnecessary Rc/Arc
+- Minimize use of unsafe code; document and isolate when necessary
+- Prefer references over smart pointers when appropriate
+- Be explicit about lifetimes when necessary for clarity
+
+## Documentation
+- Document all public APIs with rustdoc comments
+- Include examples in documentation for complex functionality
+- Document SAFETY considerations for unsafe functions
+- Add comments for complex algorithms or non-obvious implementations
+
+## Testing
+- Write unit tests for all public functions
+- Include integration tests for major features
+- Use property-based testing where appropriate (e.g., proptest)
+- Test edge cases and error paths explicitly
+
+## Dependencies
+- Be conservative with dependencies; evaluate their maintenance status
+- Prefer crates from the rust-lang org when available
+- Consider MSRV (Minimum Supported Rust Version) requirements
+
+## Async Code
+- Use appropriate executor for the project (tokio, async-std, etc.)
+- Follow structured concurrency patterns
+- Be mindful of cancellation and resource cleanup
+- Document blocking operations clearly
+
+## General
+- Prefer immutable variables (let vs let mut)
+- Use strong typing over runtime checks
+- Leverage the type system to prevent invalid states
+- Follow API design principles from the Rust API Guidelines

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

@@ -0,0 +1,160 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+# Never set RUSTFLAGS in this workflow: it replaces the target rustflags from
+# .cargo/config.toml (target-cpu=x86-64-v2). Extra flags go into
+# CARGO_TARGET_<TRIPLE>_RUSTFLAGS, which cargo merges with the config.
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: stable
+          components: clippy
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      # Warnings are reported, not fatal (two pre-existing clippy warnings in
+      # src/ser.rs). `cargo fmt --check` is not enforced yet: src/entry.rs and
+      # src/parser.rs are not rustfmt-clean.
+      - run: cargo clippy --release --all-targets
+        env:
+          PYO3_PYTHON: python
+
+  test:
+    name: test ${{ matrix.os }} py${{ matrix.python }}${{ matrix.no-avx512 && ' no-avx512' || '' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # requires-python >=3.10; PyO3 0.29 supports up to 3.14 (3.14 str access: src/compat.rs).
+        os: [ubuntu-24.04]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          # SSE2/AVX2 escape kernels (the runner may have AVX-512).
+          - os: ubuntu-24.04
+            python: "3.13"
+            no-avx512: true
+          # aarch64: SWAR / non-x86 fallback paths, pre- and post-3.12 layouts.
+          - os: ubuntu-24.04-arm
+            python: "3.10"
+          - os: ubuntu-24.04-arm
+            python: "3.13"
+          - os: macos-14
+            python: "3.13"
+          # Windows links private C-API symbols via the full import library
+          # (build.rs); 3.10 covers _PyDict_NewPresized, 3.13 _PyDict_FromItems.
+          - os: windows-2022
+            python: "3.10"
+          - os: windows-2022
+            python: "3.13"
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+        with:
+          key: py${{ matrix.python }}-${{ matrix.no-avx512 && 'no-avx512' || 'default' }}
+      - name: Disable the AVX-512 kernel
+        if: matrix.no-avx512
+        run: echo "CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS=--cfg rjson_no_avx512" >> "$GITHUB_ENV"
+      # fastapi + httpx: tests/test_examples.py skips its FastAPI tests without them;
+      # orjson: tests/test_native.py compares against it (skipped without it);
+      # tzdata: ZoneInfo zones on Windows, which has no system tz database.
+      - run: python -m pip install "maturin>=1.8,<2" pytest fastapi httpx orjson tzdata
+      - name: Build wheel
+        run: maturin build --release -i python -o dist
+      - name: Install wheel
+        run: python -m pip install --no-index --find-links dist pyrjson
+      - run: python -m pytest tests -q
+
+  # musl (Alpine): the musllinux wheels' platform. Its pthread_getattr_np
+  # reports the main thread's stack differently from glibc (src/stack.rs);
+  # rjson 0.1.0's musllinux wheel builds failed on exactly that.
+  musl:
+    name: test musl (Alpine) py3.13
+    runs-on: ubuntu-24.04
+    container: python:3.13-alpine
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - name: Install the Rust toolchain
+        run: |
+          apk add --no-cache build-base curl patchelf
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+      - run: python -m pip install "maturin>=1.8,<2" pytest orjson
+      - name: Build wheel
+        run: maturin build --release -i python -o dist
+      - name: Install wheel
+        run: python -m pip install --no-index --find-links dist pyrjson
+      - run: python -m pytest tests -q
+
+  # The extension built with AddressSanitizer (nightly rustc), run under a
+  # normal CPython with the ASan runtime preloaded. PYTHONMALLOC=malloc puts
+  # Python objects (the bytes/str rjson writes into) on ASan's allocator, so
+  # out-of-bounds reads/writes and use-after-free are reported; leak checking
+  # is off because CPython keeps objects alive until exit on purpose. The fuzz
+  # suite runs with more cases here.
+  sanitize:
+    name: sanitize (ASan) py3.13
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: nightly
+      - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+        with:
+          key: asan
+      - run: python -m pip install "maturin>=1.8,<2" pytest fastapi httpx orjson
+      - name: Build wheel with AddressSanitizer
+        env:
+          CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: -Zsanitizer=address
+        run: maturin build --release --target x86_64-unknown-linux-gnu -i python -o dist
+      - name: Install wheel
+        run: python -m pip install --no-index --find-links dist pyrjson
+      - name: Tests and fuzzing under ASan
+        env:
+          ASAN_OPTIONS: detect_leaks=0:abort_on_error=1
+          PYTHONMALLOC: malloc
+          RJSON_SANITIZER: asan
+          RJSON_FUZZ_ITERS: "5000"
+        run: LD_PRELOAD="$(gcc -print-file-name=libasan.so)" python -m pytest tests -q

pyrjson-0.2.0/.github/workflows/perf.yml

@@ -0,0 +1,96 @@
+name: Perf gate
+
+# Opt-in performance regression gate (shared runners are noisy): runs on PRs
+# labelled `perf` and on manual dispatch. Builds base and head (plain release,
+# no PGO) in the same job, runs benches/corpus_benchmark.py for both,
+# interleaved, and fails if any rjson/orjson geomean (loads, dumps,
+# dumps_str) is more than 5% worse than base. The ratio to orjson, timed in
+# the same process, cancels most runner speed drift.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+  workflow_dispatch:
+    inputs:
+      base:
+        description: Base ref to compare against
+        default: main
+      threshold:
+        description: Max allowed geomean regression (0.05 = 5%)
+        default: "0.05"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: perf-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  ROUNDS: "5"
+
+jobs:
+  perf:
+    if: github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'perf')
+    name: perf py${{ matrix.python }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.11 exercises the GC-pause path, 3.13 the like-for-like parser.
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+          path: head
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+          path: base
+          ref: ${{ github.event.pull_request.base.sha || inputs.base }}
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@02cb101ec7c40f2c49e1d9714d64511d8e1b74de # master
+        with:
+          toolchain: stable
+      - name: Fetch corpora (sha256-pinned)
+        run: head/benches/fetch_corpus.sh "$RUNNER_TEMP/corpus"
+      - name: Build base and head
+        run: |
+          python -m pip install "maturin>=1.8,<2"
+          for side in base head; do
+            (cd "$side" && maturin build --release -i python -o "$RUNNER_TEMP/wheels-$side")
+            python -m venv "$RUNNER_TEMP/venv-$side"
+            "$RUNNER_TEMP/venv-$side/bin/python" -m pip install -q orjson
+            # Install by file, not by name: the base ref may predate the
+            # rjson -> pyrjson distribution rename (one wheel per directory).
+            "$RUNNER_TEMP/venv-$side/bin/python" -m pip install -q --no-index "$RUNNER_TEMP/wheels-$side"/*.whl
+          done
+      - name: Benchmark (interleaved)
+        run: |
+          mkdir -p results
+          for r in $(seq 1 "$ROUNDS"); do
+            # alternate which side goes first to cancel ordering effects
+            if (( r % 2 )); then order="base head"; else order="head base"; fi
+            for side in $order; do
+              # head's benchmark script for both sides (base may predate --output-json)
+              "$RUNNER_TEMP/venv-$side/bin/python" head/benches/corpus_benchmark.py \
+                --data "$RUNNER_TEMP/corpus" --repeat 5 --output-json "results/$side-$r.json" > /dev/null
+            done
+          done
+      - name: Compare
+        run: |
+          python head/benches/perf_gate.py --threshold "${THRESHOLD}" \
+            --base results/base-*.json --head results/head-*.json
+        env:
+          THRESHOLD: ${{ inputs.threshold || '0.05' }}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: perf-results-py${{ matrix.python }}
+          path: results/