just-based development commands

Justfile

@@ -0,0 +1,30 @@
+# Oxen: Fast, unstructured data version control
+
+mod rust 'oxen-rust/Justfile'
+mod python 'oxen-python/Justfile'
+
+# Build all sub-projects
+build:
+    just rust build
+    just python build
+
+# Run all linters and format checkers
+lint:
+    just rust lint
+    just python lint
+
+# Type-check all sub-projects (cargo check + mypy)
+check:
+    just rust check
+    just python check
+
+# Run all tests (Rust, CLI integration, and Python)
+test:
+    just rust test
+    just rust test-cli
+    just python test
+
+# Generate all documentation
+doc:
+    just rust doc
+    just python doc

README.md

@@ -121,6 +121,47 @@ Code bases to contribute to:
 
 If you are building anything with Oxen.ai or have any questions we would love to hear from you in our [discord](https://discord.gg/s3tBEn7Ptg).
 
+## Developer Quick Start
+
+The project uses [Just](https://github.com/casey/just) as a command runner to provide a consistent developer interface across all sub-projects. Install it first:
+
+```bash
+# macOS
+brew install just
+
+# Or see https://github.com/casey/just#installation for other platforms
+```
+
+Then from the repository root you can run common tasks across all sub-projects:
+
+```bash
+just build    # Build all sub-projects
+just check    # Type-check (cargo check + mypy)
+just lint     # Run all linters and format checkers
+just test     # Run all tests (Rust + CLI integration + Python)
+just doc      # Generate all documentation
+```
+
+Each sub-project also has its own Justfile with more specific recipes:
+
+```bash
+just rust build        # Build the Rust workspace
+just rust test         # Run Rust tests with nextest
+just rust test-only NAME  # Run a specific Rust test by name
+just rust lint         # cargo fmt --check + clippy
+just rust serve        # Start server with live-reload (bacon)
+just rust test-cli     # Run CLI integration tests
+
+just python build      # Install deps + compile Rust extension
+just python test       # Run Python tests
+just python test-only NAME  # Run a specific Python test by keyword
+just python check      # Type-check with mypy
+just python lint       # ruff + cargo fmt --check + clippy
+just python doc        # Generate API docs with pdoc
+```
+
+See `oxen-rust/Justfile` and `oxen-python/Justfile` for the full list of recipes.
+
 ## Build 🔨
 
 Set up virtual environment:
@@ -136,15 +177,15 @@ $ pip install -r requirements.txt
 # Install rust
 $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
-# Run maturin
+# Run maturin (or `just python build`)
 $ cd oxen
 $ maturin develop
 ```
 
 ## Test
 
 ```bash
-$ pytest -s tests/
+$ pytest -s tests/  # or `just python test`
 ```
 
 ## Why build Oxen?

oxen-python/.gitignore

@@ -69,4 +69,7 @@ docs/_build/
 .vscode/
 
 # Pyenv
-.python-version
+.python-version
+
+# Generated docs (pdoc)
+docs/

oxen-python/Develop.md

@@ -20,7 +20,7 @@ pip install -r requirements.txt
 Then use `maturin` to build the Rust native module and deploy it in the current virtualenv.
 
 ```bash
-maturin develop
+maturin develop   # or `just build` to also install deps
 ```
 
 For intel builds if it cannot find the c++ headers
@@ -32,7 +32,7 @@ env CPLUS_INCLUDE_PATH=/Library/Developer/CommandLineTools/usr/include/c++/v1/ m
 ## Run Tests
 
 ```bash
-pytest -s tests/
+pytest -s tests/   # or `just test`
 ```
 
 ## Code Quality
@@ -46,7 +46,7 @@ black .
 ### Linting
 
 ```bash
-ruff .
+ruff .   # or `just lint` to run ruff + cargo fmt + clippy
 ```
 
 ## Adding Modules 🦀 -> 🐍

oxen-python/Justfile

@@ -0,0 +1,31 @@
+# Oxen Python bindings (PyO3 + maturin)
+
+# Install deps and compile Rust extension into venv
+build:
+    uv sync --no-install-project
+    maturin develop
+
+# Lint Python (ruff) and Rust (fmt + clippy); all run even if one fails
+lint:
+    #!/usr/bin/env bash
+    rc=0
+    ruff check . || rc=1
+    cargo fmt --all -- --check || rc=1
+    cargo clippy --no-deps -- -D warnings || rc=1
+    exit $rc
+
+# Type-check Python code with mypy
+check:
+    uv run mypy python/oxen
+
+# Run all Python tests
+test:
+    uv run pytest -s tests
+
+# Run a specific test by keyword
+test-only NAME:
+    uv run pytest -s tests -k "{{NAME}}"
+
+# Generate Python API docs with pdoc
+doc:
+    uv run pdoc python/oxen -o docs

oxen-python/README.md

@@ -1,4 +1,4 @@
-# 🐂 🐍 Oxen Python Interface 
+# 🐂 🐍 Oxen Python Interface
 
 The Oxen python interface makes it easy to integrate Oxen datasets directly into machine learning dataloaders or other data pipelines.
 
@@ -41,7 +41,7 @@ repo.checkout()
 If you don't want to download the data locally, you can use the `RemoteRepo` class to interact with a remote repository on OxenHub.
 
 ```python
-import oxen 
+import oxen
 
 repo = RemoteRepo("https://hub.oxen.ai/ox/CatDogBBox")
 ```
@@ -62,3 +62,20 @@ repo.commit("Adding another training image")
 
 Note that no "push" command is required here, since the above code creates a commit directly on the remote branch.
 
+## Development
+
+This sub-project uses [Just](https://github.com/casey/just) as a command runner. Install it with `brew install just` or see the [installation guide](https://github.com/casey/just#installation).
+
+List all available recipes with `just --list`. Common recipes:
+
+| Command | Description |
+|---------|-------------|
+| `just build` | Install deps and compile Rust extension into venv |
+| `just lint` | Lint Python (ruff) and Rust (fmt + clippy) |
+| `just check` | Type-check Python code with mypy |
+| `just test` | Run all Python tests |
+| `just test-only NAME` | Run a specific test by keyword |
+| `just doc` | Generate Python API docs with pdoc |
+
+See `Develop.md` for more detailed development instructions.
+

oxen-python/pyproject.toml

@@ -41,3 +41,16 @@ build-backend = "maturin"
 [tool.maturin]
 python-source = "python"
 features = ["pyo3/extension-module"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "pdoc>=15.0",
+]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["python/oxen"]
+ignore_missing_imports = true
+warn_return_any = true
+warn_unused_configs = true