Metadata-Version: 2.4
Name: cragpy
Version: 0.2.0
Summary: A modern Python wrapper for the theCrag Logbook API.
Project-URL: Homepage, https://github.com/coderiot/cragpy
Project-URL: Changelog, https://github.com/coderiot/cragpy/releases
Project-URL: Issue Tracker, https://github.com/coderiot/cragpy/issues
Project-URL: theCrag API Documentation, https://www.thecrag.com/en/article/logbookreadapi
Author-email: coderiot <coderiot@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,climbing,logbook,theCrag,wrapper
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx[http2]>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: lint
Requires-Dist: pre-commit>=4.6.0; extra == 'lint'
Requires-Dist: ruff>=0.15.17; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: respx>=0.20.0; extra == 'test'
Description-Content-Type: text/markdown

[![CI](https://github.com/coderiot/cragpy/actions/workflows/ci.yml/badge.svg)](https://github.com/coderiot/cragpy/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/cragpy.svg)](https://pypi.org/project/cragpy/)

# cragpy

A modern Python wrapper for the [theCrag](https://www.thecrag.com) [Logbook API](https://www.thecrag.com/en/article/logbookreadapi).

## Installation

Install dependencies locally or install the package in editable mode:

```bash
# 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

```bash
# Update the package
pip install --upgrade cragpy
```

## Usage

```python
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

```python

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

## CLI Usage

Use the `cragpy` CLI tool to fetch your complete logbook.

```bash
# 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](https://docs.astral.sh/uv/) you can use the CLI without installing the package first:

```bash
# 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:

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

---     

## Running Tests & Formatting

Run the test suite using `pytest`:

```bash
pytest
```

Run code quality check and formatters using `ruff`:

```bash
ruff check
ruff format
```
