Development¶

This guide covers how to set up a development environment and contribute to ptars.

Prerequisites¶

Python 3.10+
Rust (latest stable)
just as a command runner
uv for Python dependency management
maturin for building the Rust/Python package

Setting Up the Development Environment¶

Most development tasks are available via the justfile.

Create Virtual Environment and Install Dependencies¶

just develop

This will:

Create a virtual environment in .venv
Install dependencies using uv
Compile the protobuf files
Build the Rust extension with maturin

Special Case for ARM Mac¶

Add this to your .bashrc or .zshrc:

export CARGO_BUILD_TARGET=aarch64-apple-darwin

Running Tests¶

Run both Python and Rust tests:

just test

Or run them separately:

# Python tests only
. .venv/bin/activate
pytest python/test

# Rust tests only
cargo test

Building¶

Build the package locally:

just build

Build distribution wheels using Docker:

just dist

Linting¶

Run all linters (Rust formatter, clippy, prek):

just lint

Code Coverage¶

First, install coverage tools:

just coverage-env

Then run coverage:

just coverage

Benchmarking¶

Run benchmarks comparing ptars to protarrow:

just benchmark

Note

Make sure to install the release version for accurate benchmarks. The debug build is much slower.

Releasing¶

Create a release from a new tag in Github. The CI takes care of the rest.

CI¶

The CI script for releases is auto-generated, though it had to be customized.

just generate-ci

Project Structure¶

ptars/
├── ptars/              # Core Rust library
├── ptars-python/       # Python bindings (PyO3)
├── python/
│   ├── ptars/          # Python package
│   └── test/           # Python tests
├── protos/             # Protobuf definitions for tests
├── docs/               # Documentation (MkDocs)
└── scripts/            # Build scripts