cragpy

A modern Python wrapper for the theCrag Logbook API.

Installation

Install dependencies locally or install the package in editable mode:

# Clone the repository
git clone https://github.com/coderiot/pycrag.git
cd pycrag

# Install package with test/development dependencies
pip install -e ".[test]"

Updating cragpy

# Update the package
pip install --upgrade cragpy

Usage

from cragpy import TheCragClient

# Initialize client
client = TheCragClient(api_key="YOUR-API-KEY")

# Fetch logbook ascents
# Optional parameters:
# - page: int
# - since: int 
logbook = client.get_logbook(page=1)

# Read account metadata
if logbook.account:
    print(f"Climber Profile: {logbook.account.name} (@{logbook.account.login})")
    print(f"Total Ascents: {logbook.account.ascentCount}")
    print(f"Cumulative Height Climbed: {logbook.account.heightClimbed}m")

# Loop through ascents
for ascent in logbook.ascents:
    print(f"Ascent ID: {ascent.id}")
    print(f"Logged Date: {ascent.logDate}")
    print(f"Route Name: {ascent.route.name if ascent.route else 'N/A'}")
    print(f"Grade: {ascent.route.grade if ascent.route else 'N/A'}")
    print(f"Tick style: {ascent.tick.name if ascent.tick else 'N/A'}")
    print("-" * 20)

Rate-Limiting & Retries

Customizing the requests-per-second limit

client = TheCragClient(api_key="YOUR-API-KEY", requests_per_second=1.0)

CLI Usage

Use the cragpy CLI tool to fetch your complete logbook.

# Export logbook to JSON file
cragpy --api-key YOUR-API-KEY --output my_logbook.json

# or using environment variable for API key
export THECRAG_API_KEY="YOUR-API-KEY"
cragpy -o my_logbook.json

# Output prints to stdout formatted in JSON.
cragpy --api-key YOUR-API-KEY

# Incremental Updates: Fetch only ascents after a specific epoch timestamp
cragpy --api-key YOUR-API-KEY --since 1700000000

# Export logbook in CSV format instead of JSON
cragpy --api-key YOUR-API-KEY --format csv -o my_logbook.csv

Running with uv

With uv you can use the CLI without installing the package first:

# Run directly from PyPI without installing (via uvx)
uvx cragpy --api-key YOUR-API-KEY -o my_logbook.json

# Or install it as a persistent tool on your PATH
uv tool install cragpy
cragpy --api-key YOUR-API-KEY -o my_logbook.json

Inside a clone of this repository, uv run sets up the environment and runs the CLI in one step:

uv run cragpy --api-key YOUR-API-KEY -o my_logbook.json

Running Tests & Formatting

Run the test suite using pytest:

pytest

Run code quality check and formatters using ruff:

ruff check
ruff format