Metadata-Version: 2.4
Name: wkt_parser
Version: 1.0.0
Summary: A completely unofficial parser for the .wkt files produced by the WorkOutDoors app.
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: workout,workoutdoors,gps,fitness,parser,wkt,running,exercise,health,tracking
Author: Bryan L. Fordham
Author-email: bfordham@naughtybaptist.com
Requires-Python: >=3.13
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Provides-Extra: dev
Requires-Dist: mypy (>=1.19.1,<2.0.0) ; extra == "dev"
Requires-Dist: pytest (>=9.0.2,<10.0.0) ; extra == "dev"
Requires-Dist: ruff (>=0.15.2,<0.16.0) ; extra == "dev"
Project-URL: Changelog, https://codeberg.org/bfordham/wkt_parser/src/branch/main/CHANGELOG.md
Project-URL: Homepage, https://codeberg.org/bfordham/wkt_parser
Project-URL: Issues, https://codeberg.org/bfordham/wkt_parser/issues
Project-URL: Repository, https://codeberg.org/bfordham/wkt_parser
Description-Content-Type: text/markdown

# WorkOutDoors WKT Parser

An unofficial parser for the `.wkt` files created by [WorkOutDoors App](http://workoutdoors.net/).

## About

This library parses binary workout files from the WorkOutDoors app and provides structured access to workout data including GPS tracks, heart rate, cadence, laps, and more. It supports JSON export for further analysis or integration with other tools.

**Note**: This is an unofficial, reverse-engineered parser. The .wkt format is undocumented and may change without notice in future app releases.

## Features

- Parse Run, Walk, and Weightlifting workouts
- GPS track extraction with coordinate conversion
- Heart rate data including zones and samples
- Cadence data with samples
- Lap-by-lap analysis for multi-lap workouts
- App and device version information
- JSON export (`to_dict()`, `to_json()`, `save_json()`)
- Comprehensive error handling

## Installation

```bash
pip install -e .
```

## Usage

### Basic Parsing

```python
from pathlib import Path
from wkt_parser import WKTParser

parser = WKTParser()
workout = parser.parse(Path("path/to/workout.wkt"))

print(f"Type: {workout.workout_type_code}")
print(f"Distance: {workout.distance}m")
print(f"Duration: {workout.duration}s")
print(f"GPS points: {len(workout.gps_track)}")
```

### JSON Export

```python
# Export to JSON string
json_str = workout.to_json()

# Save to file
workout.save_json("workout.json")

# Get as dictionary
data = workout.to_dict()
```

### Batch Export

See `examples/export_to_json.py` for a complete example of batch processing multiple workout files.

```bash
python examples/export_to_json.py ~/workouts/Workouts ~/workouts/json
```

## Development

### Setup

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install dependencies
pip install -e .
```

### Testing

```bash
# Run tests
just test

# Or directly with pytest
pytest tests/
```

### Linting

```bash
just check  # Run all checks (ruff, mypy)
just lint   # Ruff linting only
```

## File Format

WorkOutDoors stores workout data in binary `.wkt` files with the following filename format:

```
YYMMDDHHMMSS_TYPE_DIST_DUR_F5_F6_STEPS_F8[_TITLE].wkt
```

Where:
- `YYMMDDHHMMSS` - End timestamp
- `TYPE` - Workout type code (37=Run, 52=Walk, 50=Weightlifting)
- `DIST` - Distance in meters
- `DUR` - Duration in seconds
- `STEPS` - Step count
- `TITLE` - Optional custom title

## Contributing

This is primarily a personal project, but contributions are welcome. The .wkt format is undocumented and largely reverse-engineered, so discoveries about the binary structure are particularly valuable.

## License

AGPL 3.0 - See LICENSE file for details

