Development Setup¶

This guide walks you through setting up a local development environment for contributing to CXAS SCRAPI. The process is straightforward — you'll be up and running in a few minutes.

Prerequisites¶

• Python 3.10 or later — SCRAPI supports Python 3.10, 3.11, 3.12, 3.13, 3.14.
• uv — recommended for fast dependency management and environment isolation. Install uv.
• Git — for version control.
• gcloud CLI — recommended for authentication during development.

Fork and Clone¶

Start by forking the repository on GitHub, then clone your fork locally:

git clone https://github.com/<your-username>/cxas-scrapi.git
cd cxas-scrapi

We recommend using uv to manage your development environment:

uv sync --all-extras
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

This creates a virtual environment, installs the package in editable mode, and includes all development and documentation dependencies (ruff, pytest, mkdocs, etc.).

We use pre-commit hooks to catch issues before they reach CI. Install them with:

uv run pre-commit install

This sets up automatic linting (via ruff) and test execution on every commit.

Verify Your Setup¶

Run the test suite to make sure everything is working:

uv run pytest

And verify the CLI is available:

cxas --help

You should see the full list of available commands.

Building the Documentation Locally¶

To preview documentation changes as you write:

uv run mkdocs serve

This starts a local server at http://127.0.0.1:8000 with live reload — any changes you save will appear in the browser automatically.

Project Layout¶

Here's a quick orientation of the repository:

Next Steps¶

• Review the code style guide before writing code.
• Read the PR submission guide when you're ready to contribute.