Metadata-Version: 2.4
Name: trainingload
Version: 0.1.0
Summary: Training-load metrics (TSS, CTL/ATL/TSB) and Strava archive parsing — zero runtime dependencies
Project-URL: Homepage, https://getmotus.fit
Project-URL: Repository, https://github.com/youloseman/trainingload
Project-URL: Issues, https://github.com/youloseman/trainingload/issues
Author-email: Artur <top.raider90@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: atl,ctl,cycling,fitness,performance-management-chart,running,sports-science,strava,swimming,training-load,training-stress-score,triathlon,tsb,tss
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# trainingload

[![CI](https://github.com/youloseman/trainingload/actions/workflows/ci.yml/badge.svg)](https://github.com/youloseman/trainingload/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/trainingload.svg)](https://pypi.org/project/trainingload/)
[![Python](https://img.shields.io/pypi/pyversions/trainingload.svg)](https://pypi.org/project/trainingload/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Training-load metrics and Strava archive parsing for endurance sport — with zero runtime dependencies.**

`trainingload` is a small, typed Python toolkit for the math behind endurance
training analytics: Training Stress Score (TSS) for swim/bike/run/strength, the
Performance Management Chart (CTL / ATL / TSB), and a parser for Strava's bulk
data export. It's the load engine extracted from the production codebase of
[**Motus**](https://getmotus.fit) — an AI triathlon coach — and packaged so you
can drop it into a notebook, a script, or your own app.

No NumPy, no pandas, no web framework. Just the standard library.

---

## Install

```bash
pip install trainingload
```

Requires Python 3.10+.

## Quick start

```python
from datetime import date
from trainingload import calculate_pmc

# Daily Training Stress Score -> fitness (CTL), fatigue (ATL), form (TSB)
series = calculate_pmc({
    date(2026, 1, 1): 80.0,
    date(2026, 1, 2): 120.0,
    date(2026, 1, 3): 0.0,    # rest day
})
today = series[-1]
print(today.ctl, today.atl, today.tsb)
```

## What's inside

Three independent modules — use one or all three.

### 1. `trainingload.tss` — Training Stress Score

Sport-aware TSS from whatever data you have (power, pace, heart rate, or just
duration), with sensible fallbacks.

```python
from trainingload import TSSCalculator, TrainingZones

zones = TrainingZones(bike_ftp=250, run_threshold_pace=300, swim_css=95)

# Cycling from normalized power:
TSSCalculator.calculate_bike_tss(duration_seconds=3600, normalized_power=200, ftp=250)  # 64.0

# Or let it pick the best method for the sport and data available:
TSSCalculator.estimate_tss(sport_type="run", duration_seconds=3600,
                           distance_meters=10000, zones=zones)  # 69.4

# Show your work — which method, inputs and formula were used:
TSSCalculator.explain_tss_calculation(sport_type="bike", duration_seconds=3600,
                                      tss=64.0, normalized_power=200, zones=zones)
```

### 2. `trainingload.pmc` — Performance Management Chart

CTL/ATL/TSB time series and a current-fitness snapshot from a map of daily TSS.

```python
from datetime import date
from trainingload import fitness_summary, interpret_tsb, recommend_training

summary = fitness_summary(daily_tss)          # {date: tss} -> ctl/atl/tsb + ramp rate
print(interpret_tsb(summary.tsb))             # e.g. "fresh"
print(recommend_training(summary.tsb, target_event_days=7))
```

- **CTL** (Chronic Training Load) — 42-day EMA of TSS → *fitness*
- **ATL** (Acute Training Load) — 7-day EMA of TSS → *fatigue*
- **TSB** (Training Stress Balance) — CTL − ATL → *form*

### 3. `trainingload.strava` — bulk-export parser

Turn the `activities.csv` from a Strava data export into typed records. Accepts
a file path **or** an in-memory stream (e.g. an upload), so it works server-side
or in a worker without touching disk.

```python
from trainingload import StravaArchiveParser

parser = StravaArchiveParser()
activities = parser.parse_zip_activities("strava_export.zip")
meta = parser.parse_zip("strava_export.zip")   # totals, date range, sport breakdown
```

## End-to-end: Strava export → fitness curve

See [`examples/strava_to_pmc.py`](examples/strava_to_pmc.py) for the full flow —
parse the archive, score every activity, and print your current CTL/ATL/TSB:

```bash
python examples/strava_to_pmc.py path/to/strava_export.zip
```

## Accuracy & credits

TSS, NP/IF, and the CTL/ATL/TSB model come from the endurance-training
literature popularised by Hunter Allen & Andrew Coggan
(*Training and Racing with a Power Meter*) and the TrainingPeaks Performance
Management Chart. The implementations here are independent and intentionally
transparent — every formula is documented in the source and covered by tests.

> **Trademark note.** "TSS", "CTL", "ATL", "TSB", "NP" and "IF" are used in this
> project descriptively to refer to widely-documented training-load concepts.
> They are trademarks of Peaksware, LLC (TrainingPeaks). This project is not
> affiliated with, sponsored by, or endorsed by TrainingPeaks or Strava.

## Built by Motus

`trainingload` powers the analytics inside [**Motus**](https://getmotus.fit?utm_source=github&utm_medium=readme&utm_campaign=trainingload),
an AI coach for runners and triathletes. If you want the metrics in this library
turned into adaptive training plans, race predictions and a coach in your pocket,
[give Motus a try](https://getmotus.fit?utm_source=github&utm_medium=readme&utm_campaign=trainingload)
— and read the training-science guides on the [Motus blog](https://getmotus.fit/blog?utm_source=github&utm_medium=readme&utm_campaign=trainingload).

## Contributing

Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE) © Motus
