eticu 0.2.1__tar.gz

eticu-0.2.1/.env.example

@@ -0,0 +1,2 @@
+INTERVALS_API_KEY=your_api_key_here
+INTERVALS_ATHLETE_ID=i12345

eticu-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Semantic Release
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write # Needed to push tags and releases to GitHub
+  id-token: write # Needed for trusted publishing to PyPI
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/eticu
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.8.1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build package
+        if: steps.release.outputs.released == 'true'
+        run: uv build
+          
+      - name: Publish to PyPI
+        # Only publish if a new release was created
+        if: steps.release.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1

eticu-0.2.1/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+.env
+
+# Virtual environments
+.venv
+
+8020_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache

eticu-0.2.1/.python-version

@@ -0,0 +1 @@
+3.14

eticu-0.2.1/CHANGELOG.md

@@ -0,0 +1,41 @@
+# CHANGELOG
+
+
+
+## v0.2.1 (2026-07-06)
+
+### Ci
+
+* ci: add explicit build step after semantic release ([`5370e5a`](https://github.com/melihakay/8020-Fetcher/commit/5370e5ac0598451312efc36fc099bf7c151fed22))
+
+### Fix
+
+* fix: trigger publisher ([`24eff65`](https://github.com/melihakay/8020-Fetcher/commit/24eff653c359e75ebd26d20c7a7a02791e6dd233))
+
+### Unknown
+
+* Merge branch 'master' of https://github.com/melihakay/8020-Fetcher ([`8df2000`](https://github.com/melihakay/8020-Fetcher/commit/8df20006cce8f0a169dfd3870463e7ad4e08a03e))
+
+
+## v0.2.0 (2026-07-06)
+
+### Feature
+
+* feat: added semantic versioning ([`d42e355`](https://github.com/melihakay/8020-Fetcher/commit/d42e355e822b9d7180aaaa4d4cfa16a5c74d43c1))
+
+### Fix
+
+* fix: use default semantic-release build command ([`04315fc`](https://github.com/melihakay/8020-Fetcher/commit/04315fcbc5b133f5d4c2a4e5bc1a451ced3d0262))
+
+
+## v0.1.0 (2026-07-06)
+
+### Feature
+
+* feat: added dynamic versioning and publisher ([`14573ca`](https://github.com/melihakay/8020-Fetcher/commit/14573ca967a4faf057e863dd078b679412746c02))
+
+### Unknown
+
+* update readme ([`0c6f3a7`](https://github.com/melihakay/8020-Fetcher/commit/0c6f3a7e2a1c1f2eac406ac98eba9ec2b614ae96))
+
+* initial version ([`68e92ec`](https://github.com/melihakay/8020-Fetcher/commit/68e92ec95c07469b0497d8dbeaa2076815e08c9d))

eticu-0.2.1/CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+Operational guide for working in this repo. **`ROADMAP.md` is the authoritative spec** — read it
+first, especially §0 (the domain gotchas). This file is the how-to-work-here layer: commands,
+conventions, and the short list of things that will bite you.
+
+## What this is
+
+A Python package (`eticu`, CLI `eticu`) that scrapes the **free** 80/20 Endurance
+workout library, converts each `.FIT` workout into a correct intervals.icu structured workout,
+and uploads them into the intervals.icu workout library. Metric units only. Swims 25 m / 50 m
+only. Reimplements and fixes `njg4ne/8020-intervals-icu` (TS, GPL-3.0).
+
+Only ever use the **free public library**. Never scrape, embed, or redistribute paid 80/20
+training plans.
+
+## Stack & tooling
+
+- Python **3.12+**, **uv** for env/deps, `src/` layout.
+- `ruff` (lint + format), `mypy --strict`, `pytest` (+ `respx` for HTTP mocking).
+- Runtime deps (see ROADMAP §1): a FIT decoder (`garmin-fit-sdk` or `fitdecode`), `httpx`,
+  `selectolax`/`beautifulsoup4`, `typer`, `pydantic` + `pydantic-settings`.
+
+## Commands
+
+```bash
+uv sync                       # install (creates .venv, resolves lockfile)
+uv run eticu --help    # CLI
+uv run eticu all --dry-run          # full pipeline, no network writes
+uv run eticu all --cycling-power     # rides as Power targets; run/swim stay HR
+
+uv run pytest -q              # tests
+uv run ruff check .           # lint
+uv run ruff format .          # format
+uv run mypy src               # typecheck
+uv build                      # build wheel/sdist
+
+uv add <pkg>                  # add runtime dep
+uv add --dev <pkg>            # add dev dep
+```
+
+Run `ruff check`, `ruff format`, `mypy src`, and `pytest` before considering any change done.
+
+## Layout
+
+```
+src/eticu/  models.py zones.py scrape.py download.py
+                   fit_parse.py convert.py intervals_client.py upload.py cli.py
+tests/             unit tests + fixtures/  (vendored sample .FIT + golden JSON/text)
+ROADMAP.md         the spec (phases, acceptance criteria, correctness checklist)
+CLAUDE.md          this file
+.env.example       INTERVALS_API_KEY=, INTERVALS_ATHLETE_ID=
+```
+
+## Conventions
+
+- Full type hints everywhere; `mypy --strict` must pass. Prefer pure functions in `zones`,
+  `fit_parse`, and `convert` so they're trivially testable.
+- Keep the `Workout`/`Step` model **unit-agnostic** (store seconds and meters). All unit and
+  target-syntax formatting happens in `convert.py`, never in the parser.
+- Golden-file testing is the backbone. Fixtures live in `tests/fixtures/`. **CCI1 is the
+  canonical regression case** (ROADMAP §0.5) — it guards both the target-loss fix and the
+  repeat-scoping fix, and it must pass in **both** HR mode and `--cycling-power` mode.
+- **No live network calls in tests.** Mock intervals.icu with `respx`; use vendored `.FIT`
+  fixtures rather than hitting 8020's site. Never commit an API key or real athlete ID.
+- Conventional Commits; small, phase-aligned PRs that each leave the suite green.
+
+## Domain gotchas (full detail in ROADMAP §0 — do not re-derive)
+
+- **Targets aren't in the FIT.** Steps use `target_type = open`; the zone is in the `notes`
+  string. Reading the file's target field gives you Z1 for everything — that's the bug. (§0.1)
+- **Zone map inserts X and Y:** 80/20 `1,2,X,3,Y,4,5` → intervals.icu `Z1..Z7`, so **80/20
+  Zone 3 → Z4**. Assert this. (§0.2)
+- **Repeats scope to the loop-back index only.** The repeat step names the message index to
+  return to; the `Nx` block wraps exactly that range up to the repeat instruction — steps after
+  it are siblings, not children. (§0.5)
+- **Metric only.** Run/Ride distance → km; swim → meters (25 m increments). No `mi`, no `y`. (§0.6)
+- **Swim 25 m / 50 m only**, never 25 y; each yields a name-suffixed workout. (§0.7)
+- **Target type by sport:** Run/Swim always HR; Ride HR by default, **Power** under
+  `--cycling-power` (needs the athlete's FTP/Power zones; the Zwift/ERG use case). Same
+  Z-number mapping for both. (§0.3)
+- **Folders are flat and fixed-named:** `80/20 - Run`, `80/20 - Bike`, `80/20 - Swim`
+  (intervals.icu doesn't nest folders; note "Bike" label vs `Ride` type). (§0.8)
+- **Idempotent uploads:** re-running must not duplicate folders or workouts — look up by name,
+  then update or skip. (Phase 4)
+
+## Config & secrets
+
+Read `INTERVALS_API_KEY` and `INTERVALS_ATHLETE_ID` from the environment via
+`pydantic-settings` (`.env` locally, never committed — ship `.env.example`). Auth is HTTP Basic:
+username literal `API_KEY`, password = the key; athlete ID goes in the path
+(`https://intervals.icu/api/v1/athlete/{id}/...`). Verify exact endpoints and the bulk-upsert
+semantics against `https://intervals.icu/api-docs.html` before relying on them.
+
+## Etiquette
+
+Be a good citizen of both services: resumable downloads (skip existing, atomic writes), modest
+concurrency and a small delay when scraping 8020, and idempotent writes to intervals.icu. Prefer
+a `--dry-run` path for anything that mutates the remote library.

eticu-0.2.1/Makefile

@@ -0,0 +1,30 @@
+.PHONY: install format lint test typecheck build publish clean
+
+install:
+	uv sync
+
+format:
+	uv run ruff format .
+
+lint:
+	uv run ruff check .
+
+typecheck:
+	uv run mypy src
+
+test:
+	uv run pytest -q
+
+build:
+	uv build
+
+publish: build
+	uv publish
+
+clean:
+	rm -rf dist/
+	rm -rf build/
+	rm -rf .ruff_cache/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +

eticu-0.2.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: eticu
+Version: 0.2.1
+Summary: Convert 80/20 Endurance .FIT workouts to intervals.icu structured workouts
+Project-URL: Repository, https://github.com/melihakay/8020-fetcher
+Author-email: Melih Akay <melih.akay@metu.edu.tr>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: fitdecode>=0.10.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.3.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: selectolax>=0.3.17
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# eticu: 80/20 Endurance to Intervals.icu
+
+`eticu` is a Python CLI pipeline that scrapes the **free** 80/20 Endurance workout library, parses and converts the `.FIT` files into fully structured [Intervals.icu](https://intervals.icu/) workouts, and idempotently uploads them to your Intervals.icu workout library.
+
+It serves as a more robust, metric-first Python reimplementation of the [8020-intervals-icu](https://github.com/njg4ne/8020-intervals-icu) TypeScript project, completely fixing target loss issues during imports, nested repeat structures, and adding idempotent uploading.
+
+> **Scope Note**: Brick (`BR*`) workouts do not exist as `.FIT` files in the library and are therefore also out of scope.
+
+## Installation & Setup
+
+This project uses `uv` for dependency management.
+
+1. **Clone the repository:**
+   ```bash
+   git clone <repo-url>
+   cd 8020-fetcher
+   ```
+
+2. **Environment Variables:**
+   Copy `.env.example` to `.env` and set your Intervals.icu credentials:
+   ```env
+   INTERVALS_API_KEY=your_intervals_api_key
+   INTERVALS_ATHLETE_ID=your_intervals_athlete_id
+   ```
+   You can find these in your Intervals.icu settings.
+
+## Usage
+
+To run the full pipeline (scrape → download → upload):
+```bash
+uv run eticu all
+```
+
+**Options:**
+- `--dry-run`: Do everything except network writes to Intervals.icu.
+- `--cycling-power`: Emit Power targets (instead of Heart Rate) for Ride workouts. (Run and Swim always remain HR).
+- `--cache-dir <dir>`: Directory to cache downloaded `.FIT` files (defaults to `8020_cache`).
+
+To convert and view a single downloaded `.FIT` file locally:
+```bash
+uv run eticu convert 8020_cache/bike/CCI1.FIT
+```
+
+To upload a training plan from a CSV file (e.g. `plans/olympic_distance_level_0.csv`):
+```bash
+uv run eticu upload-plan plans/olympic_distance_level_0.csv --name "Olympic Level 0"
+```
+
+Exercise names in the CSV's should be same as the 80/20 FIT files.
+
+**Options:**
+- `--pool-length`: Pool length in meters (e.g., 25 or 50) for swim workouts.
+- `--dry-run`: Parse the CSV and list the plan without uploading.
+
+## Critical Prerequisites
+
+For the generated workouts to be accurate, you **must** configure your Intervals.icu settings to match the 80/20 Endurance methodology.
+
+### 1. The 7-Zone Prerequisite
+80/20 uses a 7-level zone system with two crossover zones: `1, 2, X, 3, Y, 4, 5`. 
+Intervals.icu supports 7 zones (`Z1` to `Z7`). `eticu` maps them sequentially. 
+**You MUST update your Intervals.icu HR zones (and Power zones, if using `--cycling-power`) to match the numbers from the 80/20 zone calculator.**
+
+| 80/20 Zone | Intervals.icu Zone |
+|------------|--------------------|
+| Zone 1     | Z1                 |
+| Zone 2     | Z2                 |
+| Zone X     | Z3                 |
+| **Zone 3** | **Z4**             |
+| Zone Y     | Z5                 |
+| Zone 4     | Z6                 |
+| Zone 5     | Z7                 |
+
+*Note: Because of crossover Zone X, 80/20's "Zone 3" maps to Intervals "Z4".*
+
+### 2. The `--cycling-power` Option & ERG Mode
+By default, 80/20 workouts use Heart Rate targets. However, platforms like **Zwift** in ERG mode ignore HR targets; they require **Power (%FTP)**.
+
+If you ride on Zwift/TrainerRoad, pass the `--cycling-power` flag. This converts all `Ride` workouts to use Power zones.
+* **Prerequisite**: For this to work, you MUST have your FTP and 7-level Power zones correctly configured in your Intervals.icu settings. If you don't, power targets will be meaningless.
+
+## Core Behaviors
+
+- **Metric Units**: All outputs are metric. Run and Ride distances are rounded to the nearest `0.1 km`. Swims are strictly handled in `meters` (`mtr` in Intervals.icu to distinguish from minutes). 
+- **Pool Lengths**: Only `25m` and `50m` swim workouts are fetched and processed. `25y` files are skipped.
+- **Folder Layout**: Workouts are uploaded into three flat folders (created automatically if they don't exist):
+  - `80/20 - Run`
+  - `80/20 - Bike`
+  - `80/20 - Swim`
+- **Idempotency**: The upload is completely idempotent. It matches workouts by exact name within the folder and skips identical workouts, preventing duplication if the script is run multiple times.
+
+## Credits & License
+This project was heavily inspired by the GPL-3.0 licensed `njg4ne/8020-intervals-icu` project, expanding its capabilities into a fully-typed Python package with deeper FIT file introspection.

eticu-0.2.1/README.md

@@ -0,0 +1,93 @@
+# eticu: 80/20 Endurance to Intervals.icu
+
+`eticu` is a Python CLI pipeline that scrapes the **free** 80/20 Endurance workout library, parses and converts the `.FIT` files into fully structured [Intervals.icu](https://intervals.icu/) workouts, and idempotently uploads them to your Intervals.icu workout library.
+
+It serves as a more robust, metric-first Python reimplementation of the [8020-intervals-icu](https://github.com/njg4ne/8020-intervals-icu) TypeScript project, completely fixing target loss issues during imports, nested repeat structures, and adding idempotent uploading.
+
+> **Scope Note**: Brick (`BR*`) workouts do not exist as `.FIT` files in the library and are therefore also out of scope.
+
+## Installation & Setup
+
+This project uses `uv` for dependency management.
+
+1. **Clone the repository:**
+   ```bash
+   git clone <repo-url>
+   cd 8020-fetcher
+   ```
+
+2. **Environment Variables:**
+   Copy `.env.example` to `.env` and set your Intervals.icu credentials:
+   ```env
+   INTERVALS_API_KEY=your_intervals_api_key
+   INTERVALS_ATHLETE_ID=your_intervals_athlete_id
+   ```
+   You can find these in your Intervals.icu settings.
+
+## Usage
+
+To run the full pipeline (scrape → download → upload):
+```bash
+uv run eticu all
+```
+
+**Options:**
+- `--dry-run`: Do everything except network writes to Intervals.icu.
+- `--cycling-power`: Emit Power targets (instead of Heart Rate) for Ride workouts. (Run and Swim always remain HR).
+- `--cache-dir <dir>`: Directory to cache downloaded `.FIT` files (defaults to `8020_cache`).
+
+To convert and view a single downloaded `.FIT` file locally:
+```bash
+uv run eticu convert 8020_cache/bike/CCI1.FIT
+```
+
+To upload a training plan from a CSV file (e.g. `plans/olympic_distance_level_0.csv`):
+```bash
+uv run eticu upload-plan plans/olympic_distance_level_0.csv --name "Olympic Level 0"
+```
+
+Exercise names in the CSV's should be same as the 80/20 FIT files.
+
+**Options:**
+- `--pool-length`: Pool length in meters (e.g., 25 or 50) for swim workouts.
+- `--dry-run`: Parse the CSV and list the plan without uploading.
+
+## Critical Prerequisites
+
+For the generated workouts to be accurate, you **must** configure your Intervals.icu settings to match the 80/20 Endurance methodology.
+
+### 1. The 7-Zone Prerequisite
+80/20 uses a 7-level zone system with two crossover zones: `1, 2, X, 3, Y, 4, 5`. 
+Intervals.icu supports 7 zones (`Z1` to `Z7`). `eticu` maps them sequentially. 
+**You MUST update your Intervals.icu HR zones (and Power zones, if using `--cycling-power`) to match the numbers from the 80/20 zone calculator.**
+
+| 80/20 Zone | Intervals.icu Zone |
+|------------|--------------------|
+| Zone 1     | Z1                 |
+| Zone 2     | Z2                 |
+| Zone X     | Z3                 |
+| **Zone 3** | **Z4**             |
+| Zone Y     | Z5                 |
+| Zone 4     | Z6                 |
+| Zone 5     | Z7                 |
+
+*Note: Because of crossover Zone X, 80/20's "Zone 3" maps to Intervals "Z4".*
+
+### 2. The `--cycling-power` Option & ERG Mode
+By default, 80/20 workouts use Heart Rate targets. However, platforms like **Zwift** in ERG mode ignore HR targets; they require **Power (%FTP)**.
+
+If you ride on Zwift/TrainerRoad, pass the `--cycling-power` flag. This converts all `Ride` workouts to use Power zones.
+* **Prerequisite**: For this to work, you MUST have your FTP and 7-level Power zones correctly configured in your Intervals.icu settings. If you don't, power targets will be meaningless.
+
+## Core Behaviors
+
+- **Metric Units**: All outputs are metric. Run and Ride distances are rounded to the nearest `0.1 km`. Swims are strictly handled in `meters` (`mtr` in Intervals.icu to distinguish from minutes). 
+- **Pool Lengths**: Only `25m` and `50m` swim workouts are fetched and processed. `25y` files are skipped.
+- **Folder Layout**: Workouts are uploaded into three flat folders (created automatically if they don't exist):
+  - `80/20 - Run`
+  - `80/20 - Bike`
+  - `80/20 - Swim`
+- **Idempotency**: The upload is completely idempotent. It matches workouts by exact name within the folder and skips identical workouts, preventing duplication if the script is run multiple times.
+
+## Credits & License
+This project was heavily inspired by the GPL-3.0 licensed `njg4ne/8020-intervals-icu` project, expanding its capabilities into a fully-typed Python package with deeper FIT file introspection.

eticu-0.2.1/docs/ISSUES.md

@@ -0,0 +1,74 @@
+# Test results [RESOLVED]
+
+PS C:\Users\melih\Development\8020 Fetcher> uv run ruff check .
+All checks passed!
+PS C:\Users\melih\Development\8020 Fetcher> uv run ruff format .         
+18 files left unchanged
+PS C:\Users\melih\Development\8020 Fetcher> uv run pytest -q
+........................................                                                                                            [100%]
+40 passed in 1.65s
+PS C:\Users\melih\Development\8020 Fetcher> uv run mypy src
+src\eticu\fit_parse.py:19: error: Skipping analyzing "fitdecode": module is installed, but missing library stubs or py.typed marker  [import-untyped]
+src\eticu\fit_parse.py:19: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
+src\eticu\intervals_client.py:49: error: Unused "type: ignore" comment  [unused-ignore]
+src\eticu\intervals_client.py:50: error: Returning Any from function declared to return "list[dict[str, Any]]"  [no-any-return]
+src\eticu\intervals_client.py:77: error: Unused "type: ignore" comment  [unused-ignore]
+src\eticu\intervals_client.py:77: error: Returning Any from function declared to return "list[dict[str, Any]]"  [no-any-return]
+src\eticu\intervals_client.py:77: note: Error code "no-any-return" not covered by "type: ignore[return-value]" comment
+Found 5 errors in 2 files (checked 11 source files)
+
+# Loop issue [RESOLVED]
+
+- 8020/Z1 1s Z1
+- 8020/Z2 1s Z2
+2x
+- 8020/Z3 1s Z4
+- 8020/Z1 0s Z1
+
+- 8020/Z2 1s Z2
+- 8020/Z1 2s Z1
+
+This is from intervals.icu
+
+It is wrong, there should be a empty space before 2x so that loop is introduced correctly.
+
+# Duration issue [RESOLVED]
+
+for example in RF3:
+
+- 8020/Z1 0s Z1 HR
+- 8020/Z2 1s Z2 HR
+- 8020/Z1 0s Z1 HR
+
+(Fixed: FIT decode scaling for duration_value was incorrectly assumed to always be milliseconds. Duration parsing is now extracted as raw floating-point values since fitdecode automatically applies profile multipliers (producing seconds and meters directly).)
+
+# Swim issue [RESOLVED]
+
+INFO HTTP Request: GET https://intervals.icu/api/v1/athlete/i632678/folders "HTTP/1.1 200 OK"
+INFO HTTP Request: POST https://intervals.icu/api/v1/athlete/i632678/workouts "HTTP/1.1 200 OK"
+INFO Created workout 'SSI2 50m' (id=1064)
+WARNING Step 4: no zone found in notes None — defaulting to Z1
+WARNING Step has no zone; defaulting to 8020/Z1 (Z1)
+WARNING Step has no zone; defaulting to 8020/Z1 (Z1)
+WARNING Step has no zone; defaulting to 8020/Z1 (Z1)
+
+(Fixed: convert.py no longer logs a warning for unzoned steps if their intensity is 'rest' or 'recovery', as these steps correctly don't require zones.)
+
+# Too much workouts [RESOLVED]
+
+INFO HTTP Request: POST https://intervals.icu/api/v1/athlete/i632678/workouts "HTTP/1.1 200 OK"
+INFO Created workout 'STT2 50m' (id=1100)
+  created=1100  updated=0  skipped=0  error=0
+
+while scrape says
+
+Total: 550  (Run=190  Ride=218  Swim=142)
+
+So everythin is posted twice
+
+# Intervals ICU Syntax Guide [RESOLVED]
+
+Use https://forum.intervals.icu/t/workout-builder-syntax-quick-guide/123701 for syntax. Reevaluate existing base with that guide.
+
+(Evaluated and confirmed that the loops correctly use the empty line spacing syntax outlined in the guide, avoiding nested loop issues and correctly formatting `x` repeat blocks.)
+