Metadata-Version: 2.4
Name: rr-webapi
Version: 0.2.1
Summary: Python client library for RaceResult Web API
Author-email: SP Timing Team <dev@sptiming.ch>
Maintainer-email: SP Timing Team <dev@sptiming.ch>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/SPTiming/python-rr-webapi
Project-URL: Documentation, https://github.com/SPTiming/python-rr-webapi#readme
Project-URL: Repository, https://github.com/SPTiming/python-rr-webapi.git
Project-URL: Bug Reports, https://github.com/SPTiming/python-rr-webapi/issues
Project-URL: Source Code, https://github.com/SPTiming/python-rr-webapi
Keywords: raceresult,api,timing,sports,events,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=0.8; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# RaceResult Python Web API Library

A Python client library for the RaceResult Web API that mirrors the functionality of the Go library.

## Features

- Pythonic API design with dataclasses
- Session management with automatic cleanup
- Event and participant operations
- Raw timing data retrieval
- Easy-to-use endpoint classes
- Type hints for better IDE support

## Installation

```bash
pip install -e .
# or for development:
pip install -r requirements.txt
```

## Quick Start

### Environment Setup

Create a `.env` file with your credentials:
```bash
RACERESULT_API_KEY=your_api_key_here
RACERESULT_USERNAME=your_username
RACERESULT_PASSWORD=your_password
```

### Basic Usage

```python
from rr_webapi import API
import os

# Create API client
api = API("events.raceresult.com", use_https=True)

# Login with API key
api.public().login(api_key=os.getenv("RACERESULT_API_KEY"))

try:
    # Get your events
    events = api.public().event_list()
    print(f"You have {len(events)} events")
    
    # Open an event
    if events:
        event_api = api.event_api(events[0].id)
        
        # Get participants
        participants = event_api.data.list([
            "ID", "BIB", "FIRSTNAME", "LASTNAME", "CONTEST.NAME"
        ])
        print(f"Event has {len(participants)} participants")
        
        # Get raw data for a participant
        if participants:
            raw_data = event_api.rawdata.get_by_pid(participants[0][0])  # ID is first field
            print(f"Participant has {len(raw_data)} raw data entries")

finally:
    # Always logout
    api.public().logout()
```

## API Structure

### Main Components

- **API**: Main client with session management
- **Public**: Authentication and account operations  
- **EventAPI**: Event-specific operations

### Event API Endpoints

- **data**: Participant data retrieval and filtering
- **participants**: Participant management (CRUD)
- **contests**: Contest/category management
- **rawdata**: Raw timing data access

## Authentication

### API Key Authentication
```python
api.public().login(api_key="your_api_key")
```

### Username/Password Authentication  
```python
api.public().login(username="username", password="password")
```

## Bulk Operations

### Adding Multiple Participants at Once

```python
# Prepare multiple participants
participants = []
for i in range(1001, 1006):
    participant = {
        "Bib": i,
        "FirstName": "Test",
        "LastName": str(i),
        "Sex": "m",
        "DateOfBirth": "1990-01-01",
        "Contest": contest_id
    }
    participants.append(participant)

# Save all participants in bulk
event_api.participants().save(participants, no_history=False)
```

### Manual Raw Data Entry

```python
# Add a manual timing entry
event_api.rawdata().add_manual(
    timing_point="Finish",
    identifier_name="bib",  # or "pid"  
    identifier_value=1001,
    time=3600.5,  # Time in decimal seconds
    add_t0=False
)
```

## Data Models

The library uses dataclasses for structured data:

```python
@dataclass
class EventListItem:
    id: str
    name: str
    date: str
    participants: int
    # ... other fields
```

## Examples

See the `../../examples/python/` directory for complete examples:
- `basic_usage.py`: Authentication and basic operations
- `participant_and_rawdata.py`: Advanced participant and timing data operations
- `bulk_participant_save.py`: Bulk saving multiple participants at once

## Development

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run tests
python -m pytest tests/
```

## Requirements

- Python 3.7+
- requests
- python-dateutil
- python-dotenv

## Package Structure

```
rr_webapi/
├── __init__.py          # Main API class
├── api.py              # Core HTTP client
├── public.py           # Public API endpoints
├── eventapi.py         # Event API wrapper
├── general.py          # General utilities
└── endpoints/          # Endpoint implementations
    ├── data.py
    ├── contests.py
    ├── participants.py
    └── rawdata.py
```

## License

This library follows the same license as the original Go library.

## Contributing

1. Follow the existing code patterns
2. Add tests for new functionality
3. Update documentation
4. Ensure examples work with changes 
