pgoutput-decoder 0.1.0__tar.gz

pgoutput_decoder-0.1.0/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+
+  # Cargo dependencies
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "rust"
+
+  # Python dependencies (pip)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "python"

pgoutput_decoder-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,49 @@
+name: Build
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  build:
+    name: Build - Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist --interpreter python${{ matrix.python-version }}
+          sccache: 'true'
+          manylinux: auto
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: dist
+          retention-days: 7

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

@@ -0,0 +1,205 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install maturin
+        run: uv tool install maturin
+
+      - name: Rust format check
+        run: cargo fmt --all -- --check
+
+      - name: Rust clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+      - name: Python format check (ruff)
+        run: |
+          uv sync
+          uv run ruff check .
+          uv run ruff format --check .
+
+  test:
+    name: Test - Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Set up Docker (for Testcontainers)
+        if: runner.os == 'Linux'
+        uses: docker/setup-buildx-action@v3
+
+      - name: Install maturin
+        run: uv tool install maturin
+
+      - name: Install dependencies and build
+        run: |
+          uv sync
+          uv run maturin develop
+
+      - name: Run tests (Linux - with Docker)
+        if: runner.os == 'Linux'
+        run: uv run pytest tests/ -v --tb=short
+
+      - name: Run tests (macOS/Windows - skip Docker tests)
+        if: runner.os != 'Linux'
+        run: uv run pytest tests/ -v --tb=short -m "not docker"
+
+  coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: llvm-tools-preview
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Set up Docker
+        uses: docker/setup-buildx-action@v3
+
+      - name: Install maturin
+        run: uv tool install maturin
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+
+      - name: Install dependencies and build
+        run: |
+          uv sync
+          rm -f *.profraw  # Clean old coverage data
+
+      - name: Build with maturin (instrumented)
+        run: uv tool run maturin develop
+        env:
+          RUSTFLAGS: '-C instrument-coverage'
+          LLVM_PROFILE_FILE: 'coverage-%p-%m.profraw'
+
+      - name: Run Python tests with coverage
+        run: |
+          uv run pytest tests/ --cov=pgoutput_decoder --cov-report=xml:python-coverage.xml --cov-report=term
+        env:
+          LLVM_PROFILE_FILE: 'coverage-%p-%m.profraw'
+
+      - name: Generate Rust coverage report
+        run: |
+          # Check if profraw files exist
+          ls -la *.profraw || echo "Warning: No profraw files found in workspace"
+          # Find llvm tools from rustc sysroot
+          SYSROOT=$(rustc --print sysroot)
+          LLVM_PROFDATA=$(find "$SYSROOT" -name llvm-profdata | head -1)
+          LLVM_COV=$(find "$SYSROOT" -name llvm-cov | head -1)
+          echo "Using llvm-profdata: $LLVM_PROFDATA"
+          echo "Using llvm-cov: $LLVM_COV"
+          # Merge profraw files
+          "$LLVM_PROFDATA" merge -sparse *.profraw -o coverage.profdata
+          # Find the compiled Python extension in target/debug (where maturin builds it)
+          # Exclude deps/ directory which contains Rust build dependencies
+          echo "Searching for Python extension in target/debug..."
+          EXTENSION=$(find target/debug -maxdepth 1 -type f \( -name "*.so" -o -name "*.dylib" \) 2>/dev/null | head -1)
+          echo "Using extension: $EXTENSION"
+          if [ -z "$EXTENSION" ] || [ ! -f "$EXTENSION" ]; then
+            echo "Error: Could not find Python extension in target/debug"
+            echo "Contents of target/debug:"
+            ls -la target/debug/ 2>/dev/null || echo "target/debug not found"
+            echo "Searching for all .so/.dylib files:"
+            find target -name "*.so" -o -name "*.dylib" 2>/dev/null || echo "No shared libraries found"
+            exit 1
+          fi
+          # Generate lcov report
+          "$LLVM_COV" export --format=lcov \
+            --instr-profile=coverage.profdata \
+            --ignore-filename-regex='/.cargo/' \
+            --ignore-filename-regex='/rustc/' \
+            "$EXTENSION" > rust-coverage.lcov
+          # Show summary
+          "$LLVM_COV" report \
+            --instr-profile=coverage.profdata \
+            --ignore-filename-regex='/.cargo/' \
+            --ignore-filename-regex='/rustc/' \
+            "$EXTENSION"
+
+      - name: Upload Python coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./python-coverage.xml
+          flags: python
+          name: python-coverage
+          fail_ci_if_error: false
+
+      - name: Upload Rust coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./rust-coverage.lcov
+          flags: rust
+          name: rust-coverage
+          fail_ci_if_error: false

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

@@ -0,0 +1,161 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist --interpreter 3.12 3.13
+          sccache: 'true'
+          manylinux: auto
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: dist
+
+  build-sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish-test-pypi:
+    name: Publish to Test PyPI
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || contains(github.ref, 'rc') || contains(github.ref, 'beta')
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/pgoutput-decoder
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, 'rc') && !contains(github.ref, 'beta')
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pgoutput-decoder
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  create-github-release:
+    name: Create GitHub Release
+    needs: [publish-pypi]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false

pgoutput_decoder-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Coverage reports
+htmlcov/
+.coverage
+coverage.xml
+.pytest_cache/
+
+# Rust-generated files
+target/
+Cargo.lock
+*.so
+*.pyd
+*.dylib
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

pgoutput_decoder-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+repos:
+  # Rust formatting and linting
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt
+        entry: cargo fmt
+        language: system
+        types: [rust]
+        pass_filenames: false
+        
+      - id: cargo-clippy
+        name: cargo clippy
+        entry: cargo clippy --all-targets --all-features -- -D warnings
+        language: system
+        types: [rust]
+        pass_filenames: false
+
+  # Python formatting and linting via ruff
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=1000']

pgoutput_decoder-0.1.0/AGENTS.md

@@ -0,0 +1,125 @@
+🤖 Project Persona
+You are an expert full-stack developer specializing in high-performance Python/Rust systems. You prioritize memory safety, type correctness, and efficient dependency management.
+
+🛠 Tech Stack
+Package Manager: uv (use uv run, uv sync, uv add)
+
+Linter/Formatter: ruff
+
+Backend: Rust (using PyO3 for bindings)
+
+Build System: maturin
+
+Testing: pytest + Testcontainers (for E2E)
+
+📂 Project Structure
+Plaintext
+.
+├── Cargo.toml                  # Rust metadata & dependencies
+├── pyproject.toml              # Python metadata, Ruff config, Maturin settings
+├── justfile                    # Task runner for common commands
+├── .pre-commit-config.yaml     # Pre-commit hooks configuration
+├── src/                        # Rust source code
+│   └── lib.rs                  # PyO3 module definitions
+├── python/                     # Python source code
+│   └── my_project/             # Main Python package
+│       ├── __init__.py
+│       └── core.py
+├── tests/                      # E2E and Unit tests
+│   └── e2e/                    # Testcontainers-based tests
+├── .vscode/settings.json       # VS Code configuration
+└── .python-version             # Managed by uv
+🚀 Development Workflow
+1. Setup & Installation
+Always use uv for environment management.
+
+Sync environment: uv sync
+
+Build Rust bindings (dev): uv run maturin develop (This installs the Rust module into the current venv).
+
+Quick setup: just setup (requires just: brew install just)
+
+2. Linting & Formatting
+We use ruff for everything Python and clippy for Rust.
+
+**Recommended**: Use pre-commit hooks to catch issues before commit:
+
+bash
+# One-time setup
+pip install pre-commit
+pre-commit install
+
+# Manual run
+pre-commit run --all-files
+
+
+**Manual checks:**
+
+Python:
+- Check: uv run ruff check .
+- Format: uv run ruff format .
+
+Rust:
+- Format: cargo fmt
+- Lint: cargo clippy --all-targets --all-features -- -D warnings
+
+**Quick commands** (requires just):
+- just check - Run all checks
+- just lint - Run all linters
+- just fmt - Format all code
+- just pre-commit - Full pre-commit check
+
+**Auto-watch mode** (requires cargo-watch):
+bash
+just watch  # Auto-run clippy on file changes
+
+Always run just check or pre-commit before pushing to avoid CI failures.
+
+
+3. Testing
+Run all tests: uv run pytest
+
+E2E Tests: Ensure Docker is running, as these use Testcontainers.
+
+Note: Use the testcontainers[postgres] (or relevant module) in pyproject.toml.
+
+Quick: just test (runs both Rust and Python tests)
+
+📝 Coding Standards
+Rust Bindings: Prefer #[pyfunction] and #[pymodule]. Avoid manual type conversions; let PyO3 handle the heavy lifting where possible.
+
+Python Types: Strict type hinting is mandatory. All function signatures must have type hints.
+
+Testing Pattern:
+
+Use @pytest.fixture for Testcontainers setup.
+
+Keep E2E tests in tests/e2e/ to separate them from fast unit tests.
+
+Performance: If a Python loop is identified as a bottleneck, move the logic to the Rust src/ directory.
+
+⚠️ Constraints
+Never use pip or venv directly. Always go through uv.
+
+Never commit the .venv directory or Rust target/ binaries.
+
+Do not add heavy Python dependencies if the logic can be implemented efficiently in Rust.
+
+💡 Example: End-to-End Test with Testcontainers
+When writing E2E tests, follow this pattern:
+
+Python
+import pytest
+from testcontainers.postgres import PostgresContainer
+from my_project import rust_backend # Your PyO3 module
+
+@pytest.fixture(scope="module")
+def db_container():
+    with PostgresContainer("postgres:18.1-alpine") as postgres:
+        yield postgres
+
+def test_rust_db_integration(db_container):
+    conn_str = db_container.get_connection_url()
+    # Logic calling your Rust bindings to interact with the container
+    result = rust_backend.process_data_in_db(conn_str)
+    assert result is True