fastdotcom-ng 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fastdotcom_ng-1.0.0/.github/workflows/live_api.yml +27 -0
- fastdotcom_ng-1.0.0/.github/workflows/main.yml +44 -0
- fastdotcom_ng-1.0.0/.github/workflows/publish.yml +34 -0
- fastdotcom_ng-1.0.0/.gitignore +39 -0
- fastdotcom_ng-1.0.0/.pre-commit-config.yaml +15 -0
- fastdotcom_ng-1.0.0/AGENTS.md +126 -0
- fastdotcom_ng-1.0.0/CHANGELOG.md +19 -0
- fastdotcom_ng-1.0.0/LICENSE +21 -0
- fastdotcom_ng-1.0.0/PKG-INFO +134 -0
- fastdotcom_ng-1.0.0/PLAN.md +113 -0
- fastdotcom_ng-1.0.0/README.md +103 -0
- fastdotcom_ng-1.0.0/fastdotcom/__init__.py +158 -0
- fastdotcom_ng-1.0.0/fastdotcom/cli.py +163 -0
- fastdotcom_ng-1.0.0/fastdotcom/client.py +794 -0
- fastdotcom_ng-1.0.0/fastdotcom/const.py +38 -0
- fastdotcom_ng-1.0.0/fastdotcom/exceptions.py +19 -0
- fastdotcom_ng-1.0.0/fastdotcom/models.py +59 -0
- fastdotcom_ng-1.0.0/fastdotcom/py.typed +0 -0
- fastdotcom_ng-1.0.0/pyproject.toml +109 -0
- fastdotcom_ng-1.0.0/tests/__init__.py +0 -0
- fastdotcom_ng-1.0.0/tests/conftest.py +247 -0
- fastdotcom_ng-1.0.0/tests/test_cli.py +100 -0
- fastdotcom_ng-1.0.0/tests/test_client.py +703 -0
- fastdotcom_ng-1.0.0/tests/test_ha_compat.py +100 -0
- fastdotcom_ng-1.0.0/tests/test_real_api_calls.py +31 -0
- fastdotcom_ng-1.0.0/uv.lock +1456 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
name: Live Fast.com API Smoke Test
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
schedule:
|
|
5
|
+
- cron: "0 10 * * 1"
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
live-api:
|
|
10
|
+
name: Live fast.com speedtest
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
|
|
13
|
+
steps:
|
|
14
|
+
- name: Check out repository
|
|
15
|
+
uses: actions/checkout@v7
|
|
16
|
+
|
|
17
|
+
- name: Set up uv and Python 3.13
|
|
18
|
+
uses: astral-sh/setup-uv@v10.4.0
|
|
19
|
+
with:
|
|
20
|
+
enable-cache: true
|
|
21
|
+
python-version: "3.13"
|
|
22
|
+
|
|
23
|
+
- name: Install dependencies
|
|
24
|
+
run: uv sync --locked --all-groups
|
|
25
|
+
|
|
26
|
+
- name: Run live Fast.com smoke tests
|
|
27
|
+
run: uv run pytest -m real_api_call --no-cov
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
name: Python ${{ matrix.python-version }}
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
strategy:
|
|
14
|
+
fail-fast: false
|
|
15
|
+
matrix:
|
|
16
|
+
python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
|
|
17
|
+
|
|
18
|
+
steps:
|
|
19
|
+
- name: Check out repository
|
|
20
|
+
uses: actions/checkout@v7
|
|
21
|
+
|
|
22
|
+
- name: Set up uv and Python ${{ matrix.python-version }}
|
|
23
|
+
uses: astral-sh/setup-uv@v10.4.0
|
|
24
|
+
with:
|
|
25
|
+
enable-cache: true
|
|
26
|
+
python-version: ${{ matrix.python-version }}
|
|
27
|
+
|
|
28
|
+
- name: Install dependencies
|
|
29
|
+
run: uv sync --locked --all-groups
|
|
30
|
+
|
|
31
|
+
- name: Ruff lint
|
|
32
|
+
run: uv run ruff check --no-fix .
|
|
33
|
+
|
|
34
|
+
- name: Ruff format check
|
|
35
|
+
run: uv run ruff format --check .
|
|
36
|
+
|
|
37
|
+
- name: Mypy type check
|
|
38
|
+
run: uv run mypy fastdotcom tests
|
|
39
|
+
|
|
40
|
+
- name: Run offline test suite with branch coverage
|
|
41
|
+
run: uv run pytest --cov-report=xml:coverage.xml
|
|
42
|
+
|
|
43
|
+
- name: Build package
|
|
44
|
+
run: uv build
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
publish:
|
|
10
|
+
name: Build and publish to PyPI
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment:
|
|
13
|
+
name: pypi
|
|
14
|
+
url: https://pypi.org/p/fastdotcom-ng
|
|
15
|
+
permissions:
|
|
16
|
+
contents: read
|
|
17
|
+
id-token: write
|
|
18
|
+
|
|
19
|
+
steps:
|
|
20
|
+
- name: Check out repository
|
|
21
|
+
uses: actions/checkout@v7
|
|
22
|
+
|
|
23
|
+
- name: Set up uv
|
|
24
|
+
uses: astral-sh/setup-uv@v10.4.0
|
|
25
|
+
with:
|
|
26
|
+
python-version: "3.13"
|
|
27
|
+
|
|
28
|
+
- name: Build distribution artifacts
|
|
29
|
+
run: uv build
|
|
30
|
+
|
|
31
|
+
- name: Publish package to PyPI
|
|
32
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
33
|
+
with:
|
|
34
|
+
attestations: true
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# Packaging / distribution
|
|
7
|
+
*.egg-info/
|
|
8
|
+
.installed.cfg
|
|
9
|
+
*.egg
|
|
10
|
+
dist/
|
|
11
|
+
build/
|
|
12
|
+
|
|
13
|
+
# Virtual environments
|
|
14
|
+
.venv/
|
|
15
|
+
venv/
|
|
16
|
+
ENV/
|
|
17
|
+
|
|
18
|
+
# Test, lint & type-check caches
|
|
19
|
+
.pytest_cache/
|
|
20
|
+
.mypy_cache/
|
|
21
|
+
.ruff_cache/
|
|
22
|
+
.tox/
|
|
23
|
+
.nox/
|
|
24
|
+
|
|
25
|
+
# Coverage reports
|
|
26
|
+
.coverage
|
|
27
|
+
.coverage.*
|
|
28
|
+
coverage.xml
|
|
29
|
+
htmlcov/
|
|
30
|
+
|
|
31
|
+
# Environment & secrets
|
|
32
|
+
.env
|
|
33
|
+
.env.*
|
|
34
|
+
|
|
35
|
+
# IDEs & OS artifacts
|
|
36
|
+
.vscode/
|
|
37
|
+
.idea/
|
|
38
|
+
.DS_Store
|
|
39
|
+
Thumbs.db
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
repos:
|
|
2
|
+
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
3
|
+
rev: v6.0.0
|
|
4
|
+
hooks:
|
|
5
|
+
- id: trailing-whitespace
|
|
6
|
+
- id: end-of-file-fixer
|
|
7
|
+
- id: check-yaml
|
|
8
|
+
- id: check-toml
|
|
9
|
+
- id: check-merge-conflict
|
|
10
|
+
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
11
|
+
rev: v0.17.6
|
|
12
|
+
hooks:
|
|
13
|
+
- id: ruff-check
|
|
14
|
+
args: [--fix]
|
|
15
|
+
- id: ruff-format
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# AGENTS.md — `fastdotcom-ng`
|
|
2
|
+
|
|
3
|
+
## 1. Project Identity & Mission
|
|
4
|
+
|
|
5
|
+
**`fastdotcom-ng`** is a **clean-room, from-scratch** asynchronous Python library and CLI for measuring Internet speed (download, upload, unloaded latency, and loaded latency) using Netflix's [Fast.com](https://fast.com/) API v2.
|
|
6
|
+
|
|
7
|
+
- **Why starting from scratch (`0`-legacy codebase):** The upstream [`nkgilley/fast.com`](https://github.com/nkgilley/fast.com) (`fastdotcom`) package suffers from fundamental architectural and legal/maintenance issues:
|
|
8
|
+
- Mixes synchronous `urllib.request`, `requests.Session`, daemon `threading.Thread`s (which leak past download completion and pollute the subsequent upload test), and `asyncio.run(async_ping(...))` inside worker threads.
|
|
9
|
+
- Uses a module-global `download_started = Event()` that is never reset across runs.
|
|
10
|
+
- Relies on `icmplib` ICMP sockets (which fail without raw-socket privileges inside containers/Home Assistant OS), calls `api.fast.com/netflix/speedtest` 4 redundant times per test, bottlenecks Raspberry Pi CPUs with `os.urandom()` inside the upload loop, swallows exceptions returning `0` (causing false `0 Mbps` drops in HA), and uses `setup.py` + `distutils` fallback with zero unit tests.
|
|
11
|
+
- Carries mixed `LICENSE` (LGPL-3.0 from `sanderjo/fast.com`) vs `setup.py`/`README.md` (`MIT`) metadata.
|
|
12
|
+
- **Mission:** Build a modern, 100% original, MIT-licensed `asyncio` + `aiohttp` implementation from a clean slate with zero legacy code, while staying **100% drop-in compatible** with Home Assistant Core's `fastdotcom` integration.
|
|
13
|
+
- **Repository & License:** Public repository at `https://github.com/marcomsousa/fastdotcom-ng` under the **MIT License** (`Copyright (c) 2026 Marco Sousa`).
|
|
14
|
+
- **Package vs Import Name:** PyPI distribution name is **`fastdotcom-ng`**, while the Python import package remains **`fastdotcom`** (`[tool.hatch.build.targets.wheel] packages = ["fastdotcom"]`) for seamless Home Assistant drop-in replacement.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 2. Empirical Fast.com Protocol Specification & Design Goals
|
|
19
|
+
|
|
20
|
+
All protocol behaviors below were empirically verified against live `fast.com` and `api.fast.com` endpoints (`2026-11-21`):
|
|
21
|
+
|
|
22
|
+
1. **Pure `asyncio` + `aiohttp>=3.10.0` (Zero Sync HTTP / Zero ICMP):**
|
|
23
|
+
- Python `>=3.11` stdlib (`asyncio.timeout`, built-in `TimeoutError`, `asyncio.Event`, `asyncio.TaskGroup`/task lifecycle) + `aiohttp>=3.10.0`.
|
|
24
|
+
- No `requests`, no `urllib.request`, no `threading`, no `icmplib`.
|
|
25
|
+
|
|
26
|
+
2. **Public Token Discovery:**
|
|
27
|
+
- `GET https://fast.com/` → parse HTML for the bundle `<script[^>]+src="([^"]+\.js)"` (note: bare `urllib` can receive HTTP `403 Forbidden`; `aiohttp` succeeds cleanly — wrap non-200 or missing matches in typed exceptions).
|
|
28
|
+
- `GET https://fast.com<js_path>` → extract token via `token:"([^"]+)"` regex.
|
|
29
|
+
|
|
30
|
+
3. **Targets Discovery via API v2 (Single Call per Speedtest Run):**
|
|
31
|
+
- `GET https://api.fast.com/netflix/speedtest/v2?https=true&token=<token>&urlCount=5`
|
|
32
|
+
- Returns JSON dict with `"client"` (`ip`, `asn`, `isp`, `location: {city, country}`) and `"targets"` (`[{name, url, location}]`), plus optional support for legacy v1 list payloads (`[{"url": ...}]`).
|
|
33
|
+
- **CRITICAL Encoding Gotcha (Verified Live):** Despite `Content-Type: application/json`, Netflix's v2 endpoint can return Latin-1 encoded city/location bytes (e.g., byte `0xe1` for `á`) that crash strict `.decode("utf-8")` with `UnicodeDecodeError`. Always decode raw response bytes using UTF-8 with `latin-1` fallback before `json.loads`.
|
|
34
|
+
|
|
35
|
+
4. **HTTP Unloaded & Loaded Latency (No ICMP / No Root Privileges):**
|
|
36
|
+
- Rewrite target URL path trailing `/speedtest` (or `/speedtest/range/...`) to `/speedtest/range/0-0` using `urllib.parse.urlsplit`/`urlunsplit`, preserving all query parameters (`c=...`, `n=...`, `tok=...`).
|
|
37
|
+
- Send 1 keep-alive warmup `GET /speedtest/range/0-0` so TCP+TLS handshake overhead does not inflate RTT, then measure `count` sequential `GET /speedtest/range/0-0` requests (`HTTP 200`, 1-byte body; empirically ~3–4 ms on fiber).
|
|
38
|
+
- Measure **loaded latency** via an async probe coroutine running concurrently during `measure_download` after a per-run local `download_started: asyncio.Event` fires (never a module-level global).
|
|
39
|
+
|
|
40
|
+
5. **Download & Upload Engines with Dynamic Scaling & Leak-Free Cancellation:**
|
|
41
|
+
- **Download:** Parallel `asyncio.Task` workers (`connections_min=1` scaling dynamically `1 -> 3 -> 5 -> connections_max=8` based on moving-window speed thresholds `>1 Mbps`, `>10 Mbps`, `>50 Mbps`) streaming `128 KiB` chunks until `stop_event` is set. Peak speed is calculated over a sliding window (default 3 snapshots of ~0.5s each).
|
|
42
|
+
- **Upload:** `POST` to `/speedtest/range/0-0` (`HTTP 200` verified live) with `Content-Type: application/octet-stream`, streaming chunks from a **single pre-allocated reusable buffer** (`bytes(chunk_size)`, e.g., `256 KiB` up to `4 MiB` per request) via an async generator so there is **zero `os.urandom()` CPU bottleneck**. Same dynamic parallel worker scaling and sliding-window speed tracking.
|
|
43
|
+
- **Cleanup Guarantee:** Both download and upload wrap worker + latency probe orchestration in `try ... finally` that sets `stop_event`, cancels every worker/probe task, and awaits `asyncio.gather(*tasks, return_exceptions=True)` so zero tasks or open HTTP streams leak between phases or runs.
|
|
44
|
+
|
|
45
|
+
6. **Typed Models & Errors (No Silent `0` Swallowing):**
|
|
46
|
+
- Frozen slotted dataclasses (`FastLocation`, `FastClientInfo`, `FastTarget`, `FastSpeedtestResult`).
|
|
47
|
+
- Explicit exception hierarchy: `FastDotComError` → `FastDotComConnectionError`, `FastDotComTokenError`, `FastDotComTimeoutError`.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Target Repository Architecture
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
fastdotcom-ng/
|
|
55
|
+
├── fastdotcom/
|
|
56
|
+
│ ├── __init__.py # Public exports, async_fast_com, drop-in sync fast_com wrapper
|
|
57
|
+
│ ├── const.py # Endpoints, default timings, chunk sizes, connection bounds
|
|
58
|
+
│ ├── exceptions.py # FastDotComError hierarchy
|
|
59
|
+
│ ├── models.py # Frozen dataclasses (FastSpeedtestResult, FastTarget, FastClientInfo, FastLocation)
|
|
60
|
+
│ ├── client.py # FastDotComClient (session lifecycle, token, v2 targets, latency, download, upload)
|
|
61
|
+
│ ├── cli.py # CLI entrypoint (`fastdotcom` console script with --json, --no-upload, etc.)
|
|
62
|
+
│ └── py.typed # PEP 561 typed package marker
|
|
63
|
+
├── tests/
|
|
64
|
+
│ ├── conftest.py # Offline aiohttp mock fixtures & sample v2 (including Latin-1) payloads
|
|
65
|
+
│ ├── test_client.py # Unit tests: token, v2 decoding, latency, download, upload, cancellation, IPv4/6, fast_com
|
|
66
|
+
│ ├── test_cli.py # CLI tests (human output, JSON output, error exit codes)
|
|
67
|
+
│ └── test_real_api_calls.py # Marked `real_api_call` (deselected by default)
|
|
68
|
+
├── .github/workflows/
|
|
69
|
+
│ ├── main.yml # CI: ruff, mypy, pytest (>=95% branch cov), uv build across Python 3.11-3.15
|
|
70
|
+
│ ├── publish.yml # Release-triggered PyPI publish via OIDC Trusted Publishing + PEP 740 attestations
|
|
71
|
+
│ └── live_api.yml # Weekly cron + workflow_dispatch live fast.com smoke test
|
|
72
|
+
├── pyproject.toml # PEP 621 / 639 / 735 metadata, hatchling backend, ruff, pytest, coverage, mypy
|
|
73
|
+
├── uv.lock # Reproducible uv lockfile
|
|
74
|
+
├── .pre-commit-config.yaml
|
|
75
|
+
├── LICENSE # MIT License (Marco Sousa)
|
|
76
|
+
├── README.md
|
|
77
|
+
└── CHANGELOG.md
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 4. Home Assistant Compatibility Invariants (Must Not Break)
|
|
83
|
+
|
|
84
|
+
- **Drop-In Sync Contract (for HA Core PR 1):**
|
|
85
|
+
- `from fastdotcom import fast_com` must work cleanly in HA's executor (`hass.async_add_executor_job(fast_com)`) and accept legacy keyword parameters (`verbose`, `max_time`, `ping_count`, `force_ipv4`, `force_ipv6`, `payload_size`, `max_payload_size`).
|
|
86
|
+
- `fast_com()` / `FastSpeedtestResult.to_dict()` returns:
|
|
87
|
+
```python
|
|
88
|
+
{
|
|
89
|
+
"download_speed": float, # Mbps rounded to 2 decimals
|
|
90
|
+
"upload_speed": float, # Mbps rounded to 2 decimals
|
|
91
|
+
"unloaded_ping": float, # ms rounded to 2 decimals
|
|
92
|
+
"loaded_ping": float, # ms rounded to 2 decimals
|
|
93
|
+
"success": 1,
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
- On network/API/timeout errors, raise `FastDotComError` instead of silently returning `0` — HA's `FastdotcomDataUpdateCoordinator._async_update_data` catches `Exception` and converts it to `UpdateFailed`, eliminating fake `0 Mbps` drops in HA history.
|
|
97
|
+
- **Native Async Contract (for HA Core PR 2):**
|
|
98
|
+
- `FastDotComClient(session=...)` and `async_fast_com(session=...)` accept an external `aiohttp.ClientSession` (HA's `async_get_clientsession(hass)`).
|
|
99
|
+
- **Session Ownership Rule:** **NEVER** close an externally injected `session` in `close()` or `__aexit__()`; only close sessions created internally by `FastDotComClient`.
|
|
100
|
+
- Support selective flags (`measure_download`, `measure_upload`, `measure_latency`) so HA can expose **Download**, **Upload**, **Unloaded Latency**, and **Loaded Latency** sensors with optional bandwidth-saving toggles.
|
|
101
|
+
- **2-PR Home Assistant Core Strategy:**
|
|
102
|
+
- **PR 1:** Minimal dependency bump only (`homeassistant/components/fastdotcom/manifest.json`, `requirements_all.txt`, `requirements_test_all.txt`, and `package_constraints.txt` if needed). Audit `git diff` to ensure no unrelated lines change.
|
|
103
|
+
- **PR 2 (only after PR 1 merges):** Migrate `fastdotcom` coordinator to native async `async_fast_com` and add Upload + Unloaded/Loaded Latency sensors, options flow, etc.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 5. Development, Testing, CI/CD & Release Guidelines
|
|
108
|
+
|
|
109
|
+
- **Toolchain (`uv` + `hatchling`):**
|
|
110
|
+
- Use `uv lock`, `uv sync --all-groups`, `uv run ...`, and `uv build`. Never use `poetry`, `pip`, or `pytest-sugar` (`pytest-sugar` crashes under `pytest 9.x`).
|
|
111
|
+
- Keep dependency lower bounds conservative (`aiohttp>=3.10.0`) rather than pinning cutting-edge minimums.
|
|
112
|
+
- **Quality Gates:**
|
|
113
|
+
- `uv run ruff check --no-fix .` and `uv run ruff format --check .` (line length `88`, strict lint rule set including `ASYNC`, `B`, `C4`, `I`, `PTH`, `RUF`, `SIM`, `TCH`).
|
|
114
|
+
- `uv run mypy fastdotcom tests` (`check_untyped_defs = true` for `fastdotcom.*`).
|
|
115
|
+
- `uv run pytest` runs offline by default (`-m 'not real_api_call'`), treats all warnings as errors (`filterwarnings = ["error"]`), and enforces **>= 95% branch coverage** (`branch = true`, `fail_under = 95`).
|
|
116
|
+
- `uv run pytest -m real_api_call --no-cov` validates live `fast.com` endpoints manually and in `.github/workflows/live_api.yml`.
|
|
117
|
+
- **GitHub Actions:**
|
|
118
|
+
- Use `actions/checkout@v7` and **pin `astral-sh/setup-uv` to an exact semver tag** (e.g., `astral-sh/setup-uv@v10.4.0` — never a floating major tag like `@v10`, which fails tag resolution).
|
|
119
|
+
- Matrix test `python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]`.
|
|
120
|
+
- Gate PyPI publishing strictly on `release: types: [published]` + `workflow_dispatch` using OIDC Trusted Publishing (`permissions: id-token: write`, `environment: pypi`, `pypa/gh-action-pypi-publish@release/v1` with `attestations: true`).
|
|
121
|
+
- **PyPI Immutable Filenames:** PyPI permanently rejects re-uploading any deleted version filename — always bump the patch version before retrying.
|
|
122
|
+
- **README & Badges:**
|
|
123
|
+
- Include GitHub Actions CI, PyPI, Python versions, and PePy downloads badge (`[](https://pepy.tech/projects/fastdotcom-ng)`).
|
|
124
|
+
- **Git Conventions:**
|
|
125
|
+
- Commit as `Marco Sousa <marcomsousa@gmail.com>` under GitHub user `marcomsousa`.
|
|
126
|
+
- Use clean, atomic Conventional Commits (`feat(...)`, `fix(...)`, `refactor(...)`, `test(...)`, `ci(...)`, `docs(...)`, `chore(...)`).
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.0.0] - 2026-11-21
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- Clean-room `asyncio` + `aiohttp` implementation of the Fast.com API v2 speedtest client (`FastDotComClient`, `async_fast_com`) under the MIT License.
|
|
12
|
+
- Single-call Fast.com API v2 target discovery (`get_targets`) with legacy v1 list fallback and UTF-8 / `latin-1` JSON decoding (`decode_json_bytes`).
|
|
13
|
+
- Rootless HTTP `/speedtest/range/0-0` latency measurements for unloaded and concurrent loaded latency (replacing ICMP sockets).
|
|
14
|
+
- Dynamically scaling parallel download and upload workers with sliding-window peak Mbps calculation, early stability termination, and leak-free task cancellation.
|
|
15
|
+
- Pre-allocated reusable upload buffer streaming with explicit `Content-Length` headers compatible with Netflix OCA servers.
|
|
16
|
+
- Frozen slotted dataclasses (`FastLocation`, `FastClientInfo`, `FastTarget`, `FastSpeedtestResult`) and typed exception hierarchy (`FastDotComError`, `FastDotComConnectionError`, `FastDotComTokenError`, `FastDotComTimeoutError`).
|
|
17
|
+
- Drop-in synchronous `fast_com(...)` facade compatible with Home Assistant Core's `fastdotcom` integration, safe across executor threads and active event loops.
|
|
18
|
+
- `fastdotcom` CLI entry point (`--max-time`, `--min-time`, `--ping-count`, `--no-download`, `--no-upload`, `--no-latency`, `--ipv4`, `--ipv6`, `--json`, `--verbose`).
|
|
19
|
+
- PEP 561 `py.typed` marker and offline, Home Assistant compatibility, CLI, and live API test suites.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Marco Sousa
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fastdotcom-ng
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Clean-room async Python library and CLI to measure Internet speed with Fast.com (Home Assistant drop-in compatible)
|
|
5
|
+
Project-URL: Homepage, https://github.com/marcomsousa/fastdotcom-ng
|
|
6
|
+
Project-URL: Repository, https://github.com/marcomsousa/fastdotcom-ng
|
|
7
|
+
Project-URL: Issues, https://github.com/marcomsousa/fastdotcom-ng/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/marcomsousa/fastdotcom-ng/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Marco Sousa <marcomsousa@gmail.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: aiohttp,asyncio,fast.com,home-assistant,network,speedtest
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Framework :: AsyncIO
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: System Administrators
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
25
|
+
Classifier: Topic :: Internet
|
|
26
|
+
Classifier: Topic :: System :: Networking :: Monitoring
|
|
27
|
+
Classifier: Typing :: Typed
|
|
28
|
+
Requires-Python: >=3.11
|
|
29
|
+
Requires-Dist: aiohttp>=3.10.0
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# fastdotcom-ng
|
|
33
|
+
|
|
34
|
+
[](https://github.com/marcomsousa/fastdotcom-ng/actions/workflows/main.yml)
|
|
35
|
+
[](https://pypi.org/project/fastdotcom-ng/)
|
|
36
|
+
[](https://pypi.org/project/fastdotcom-ng/)
|
|
37
|
+
[](LICENSE)
|
|
38
|
+
[](https://pepy.tech/projects/fastdotcom-ng)
|
|
39
|
+
|
|
40
|
+
A clean-room, modern `asyncio` + `aiohttp` Python library and CLI to measure Internet speed (download, upload, unloaded latency, and loaded latency) using Netflix's [Fast.com](https://fast.com/) API v2 — designed as a **100% drop-in compatible** replacement for `fastdotcom` in Home Assistant.
|
|
41
|
+
|
|
42
|
+
## Highlights
|
|
43
|
+
|
|
44
|
+
- **Pure `asyncio` + `aiohttp`**: Zero `requests`, `urllib.request`, `threading`, or `icmplib`.
|
|
45
|
+
- **Single API v2 Discovery Call**: Discovers client metadata and targets in one call, with UTF-8 + `latin-1` fallback decoding for non-UTF-8 city names.
|
|
46
|
+
- **Rootless HTTP Latency Probes**: Uses `GET /speedtest/range/0-0` keep-alive requests instead of ICMP raw sockets (works unprivileged inside containers and Home Assistant OS).
|
|
47
|
+
- **Dynamic Scaling & Clean Cancellation**: Dynamically scales parallel connections (`1 -> 3 -> 5 -> max`) with sliding-window speed tracking and guaranteed task cleanup.
|
|
48
|
+
- **Zero-Bottleneck Upload Streaming**: Streams a pre-allocated reusable buffer with explicit `Content-Length` (required by Netflix OCA endpoints) instead of calling `os.urandom()` per loop.
|
|
49
|
+
- **Home Assistant Drop-In & Native Async Ready**:
|
|
50
|
+
- `from fastdotcom import fast_com` provides synchronous drop-in compatibility.
|
|
51
|
+
- `async_fast_com(session=...)` and `FastDotComClient(session=...)` accept an external `aiohttp.ClientSession` without ever closing caller-owned sessions.
|
|
52
|
+
- Typed exceptions (`FastDotComError`) replace silent `0` returns.
|
|
53
|
+
- **PEP 561 Typed**: Ships `py.typed` with strict `mypy` verification.
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
uv add fastdotcom-ng
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Or with `pip`:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pip install fastdotcom-ng
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Usage
|
|
68
|
+
|
|
69
|
+
### Native Async (Recommended)
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import asyncio
|
|
73
|
+
import aiohttp
|
|
74
|
+
from fastdotcom import async_fast_com
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
async def main() -> None:
|
|
78
|
+
async with aiohttp.ClientSession() as session:
|
|
79
|
+
result = await async_fast_com(session=session)
|
|
80
|
+
print(
|
|
81
|
+
f"Download: {result.download_speed} Mbps | "
|
|
82
|
+
f"Upload: {result.upload_speed} Mbps | "
|
|
83
|
+
f"Unloaded: {result.unloaded_ping} ms | "
|
|
84
|
+
f"Loaded: {result.loaded_ping} ms"
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
asyncio.run(main())
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Reusable Client
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
import asyncio
|
|
95
|
+
from fastdotcom import FastDotComClient
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
async def main() -> None:
|
|
99
|
+
async with FastDotComClient() as client:
|
|
100
|
+
result = await client.run_speedtest(max_time=10.0, ping_count=5)
|
|
101
|
+
print(result.to_dict())
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
asyncio.run(main())
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Synchronous Drop-In (Home Assistant Compatible)
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from fastdotcom import fast_com
|
|
111
|
+
|
|
112
|
+
metrics = fast_com()
|
|
113
|
+
# {
|
|
114
|
+
# "download_speed": 612.45,
|
|
115
|
+
# "upload_speed": 318.92,
|
|
116
|
+
# "unloaded_ping": 3.41,
|
|
117
|
+
# "loaded_ping": 14.28,
|
|
118
|
+
# "success": 1,
|
|
119
|
+
# }
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Command-Line Interface
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
fastdotcom
|
|
126
|
+
fastdotcom --json --max-time 10 --ping-count 5
|
|
127
|
+
fastdotcom --no-upload --ipv4
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Provenance & License
|
|
131
|
+
|
|
132
|
+
`fastdotcom-ng` is an independent, clean-room MIT implementation written from scratch by [Marco Sousa](https://github.com/marcomsousa) to replace the unmaintained legacy `fastdotcom` package ([`nkgilley/fast.com`](https://github.com/nkgilley/fast.com)) while preserving its public `fastdotcom` import namespace and Home Assistant dictionary contract.
|
|
133
|
+
|
|
134
|
+
Licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# PLAN.md — `fastdotcom-ng` Implementation Roadmap
|
|
2
|
+
|
|
3
|
+
Clean-room build plan for `marcomsousa/fastdotcom-ng` (PyPI: `fastdotcom-ng`, Python import: `fastdotcom`). Work sequentially phase-by-phase and verify each gate before moving on.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Phase 1: Repository Foundation & `uv` Packaging
|
|
8
|
+
|
|
9
|
+
1. **Create `LICENSE`**: Standard **MIT License**, `Copyright (c) 2026 Marco Sousa`.
|
|
10
|
+
2. **Create `.gitignore`**: Standard Python / `uv` / coverage / cache / `.env` / IDE ignores.
|
|
11
|
+
3. **Create `pyproject.toml`**:
|
|
12
|
+
- `[build-system]`: `requires = ["hatchling>=1.27"]`, `build-backend = "hatchling.build"`.
|
|
13
|
+
- `[tool.hatch.build.targets.wheel]`: `packages = ["fastdotcom"]`.
|
|
14
|
+
- `[project]`: `name = "fastdotcom-ng"`, `version = "1.0.0"`, `requires-python = ">=3.11"`, `license = "MIT"`, `license-files = ["LICENSE"]`, `authors = [{ name = "Marco Sousa", email = "marcomsousa@gmail.com" }]`, `dependencies = ["aiohttp>=3.10.0"]`, `[project.scripts] fastdotcom = "fastdotcom.cli:main"`.
|
|
15
|
+
- `[dependency-groups] dev`: `mypy>=1.15.0`, `pre-commit>=4.0.0`, `pytest>=9.0.0`, `pytest-asyncio>=1.0.0`, `pytest-cov>=6.0.0`, `pytest-timeout>=2.3.0`, `ruff>=0.11.0` (do **not** include `pytest-sugar`).
|
|
16
|
+
- Configure `[tool.ruff]`, `[tool.coverage.run]` (`branch = true`, `source = ["fastdotcom"]`), `[tool.coverage.report]` (`fail_under = 95`), `[tool.pytest.ini_options]` (`filterwarnings = ["error"]`, `addopts = "-vv --cov --cov-report term -m 'not real_api_call'"`, `markers = ["real_api_call: Tests making live requests to fast.com (deselected by default)"]`), `[tool.mypy]` (`python_version = "3.11"`, `check_untyped_defs = true` for `fastdotcom.*`).
|
|
17
|
+
4. **Create `.pre-commit-config.yaml`**: Standard `pre-commit-hooks` + `ruff-pre-commit`.
|
|
18
|
+
5. **Create `README.md` and `CHANGELOG.md`**:
|
|
19
|
+
- Badges: CI, PyPI, Python `3.11–3.15`, PePy (`[](https://pepy.tech/projects/fastdotcom-ng)`).
|
|
20
|
+
- Clear async, sync Home Assistant drop-in, and CLI examples.
|
|
21
|
+
6. **Verify**: Run `uv lock && uv sync --all-groups`.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Phase 2: Clean-Room Async Core & CLI (`fastdotcom/`)
|
|
26
|
+
|
|
27
|
+
1. **`fastdotcom/py.typed`**: Empty PEP 561 marker file.
|
|
28
|
+
2. **`fastdotcom/const.py`**:
|
|
29
|
+
- `FAST_COM_URL = "https://fast.com/"`
|
|
30
|
+
- `FAST_API_V2_URL = "https://api.fast.com/netflix/speedtest/v2"`
|
|
31
|
+
- Timeouts, default durations (`DEFAULT_MIN_TIME = 5.0`, `DEFAULT_MAX_TIME = 15.0`), connections (`1..8`), ping defaults (`DEFAULT_PING_COUNT = 5`, `DEFAULT_PING_INTERVAL = 0.5`), chunk sizes (`DEFAULT_DOWNLOAD_CHUNK_SIZE = 128 * 1024`, `DEFAULT_UPLOAD_CHUNK_SIZE = 256 * 1024`, `DEFAULT_UPLOAD_PAYLOAD_SIZE = 4 * 1024 * 1024`).
|
|
32
|
+
3. **`fastdotcom/exceptions.py`**:
|
|
33
|
+
- `FastDotComError(Exception)`
|
|
34
|
+
- `FastDotComConnectionError(FastDotComError)`
|
|
35
|
+
- `FastDotComTokenError(FastDotComError)`
|
|
36
|
+
- `FastDotComTimeoutError(FastDotComError)`
|
|
37
|
+
4. **`fastdotcom/models.py`**:
|
|
38
|
+
- Frozen slotted dataclasses: `FastLocation`, `FastClientInfo`, `FastTarget`, `FastSpeedtestResult`.
|
|
39
|
+
- `FastSpeedtestResult.to_dict()` returning `{"download_speed": ..., "upload_speed": ..., "unloaded_ping": ..., "loaded_ping": ..., "success": 1}`.
|
|
40
|
+
5. **`fastdotcom/client.py`**:
|
|
41
|
+
- `decode_json_bytes(raw: bytes) -> Any`: decode UTF-8 with `latin-1` fallback (handles non-UTF-8 city names in Netflix v2 responses); raise `FastDotComConnectionError` on invalid JSON.
|
|
42
|
+
- `to_range_url(url: str, start: int = 0, end: int = 0) -> str`: rewrite `/speedtest` (or `/speedtest/range/...`) suffix to `/speedtest/range/{start}-{end}` preserving query string.
|
|
43
|
+
- `FastDotComClient`:
|
|
44
|
+
- Accepts `session: aiohttp.ClientSession | None = None`, `timeout: float = ...`, `force_ipv4: bool = False`, `force_ipv6: bool = False` (reject both `True` with `ValueError`; configure `aiohttp.TCPConnector(family=socket.AF_INET / AF_INET6)` when creating internal session).
|
|
45
|
+
- Async context manager (`__aenter__` / `__aexit__`) & `close()` — **only close session if created internally, never close an injected session**.
|
|
46
|
+
- `get_token() -> str`: scrape JS bundle URL from `https://fast.com/` and extract `token:"..."`.
|
|
47
|
+
- `get_targets(token=None, *, url_count=5) -> tuple[FastClientInfo | None, list[FastTarget]]`: single call to v2 API (plus v1 list fallback), check HTTP status, decode cleanly, raise `FastDotComConnectionError` if empty.
|
|
48
|
+
- `measure_latency(url, *, count=5, warmup=True) -> tuple[float, list[float]]`: keep-alive `GET /speedtest/range/0-0` probes timed with `time.perf_counter()`.
|
|
49
|
+
- `measure_download(...) -> tuple[float, int, float, list[float]]`: dynamic parallel async tasks (`1 -> 3 -> 5 -> connections_max`), sliding-window peak Mbps, optional concurrent loaded latency probes triggered by local per-run `download_started` `asyncio.Event`, and `finally:` cancellation + `asyncio.gather(..., return_exceptions=True)`.
|
|
50
|
+
- `measure_upload(...) -> tuple[float, int]`: `POST /speedtest/range/0-0` streaming pre-allocated reusable `bytes(chunk_size)` buffer across dynamically scaled parallel async tasks with `finally:` cancellation.
|
|
51
|
+
- `run_speedtest(...) -> FastSpeedtestResult`: single token+targets fetch, optional `measure_download` / `measure_upload` / `measure_latency`, returning rounded values (2 decimals).
|
|
52
|
+
6. **`fastdotcom/__init__.py`**:
|
|
53
|
+
- Export public classes, exceptions, `async_fast_com(...)`, and drop-in sync wrapper `fast_com(...)` accepting legacy kwargs (`verbose`, `max_time`, `ping_count`, `force_ipv4`, `force_ipv6`, `payload_size`, `max_payload_size`) and returning `result.to_dict()`.
|
|
54
|
+
7. **`fastdotcom/cli.py`**:
|
|
55
|
+
- Clean `argparse` CLI (`--max-time`, `--min-time`, `--ping-count`, `--no-download`, `--no-upload`, `--no-latency`, `--ipv4`, `--ipv6`, `--json`, `--verbose`) catching `FastDotComError` cleanly.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Phase 3: Offline & Live Test Suites (`tests/`)
|
|
60
|
+
|
|
61
|
+
1. **`tests/conftest.py`**: Mock `aiohttp` transport / session helpers and sample Fast.com HTML, JS bundle, and v2 API JSON fixtures (including Latin-1 `M\xe1laga` byte `0xe1`).
|
|
62
|
+
2. **`tests/test_client.py`**:
|
|
63
|
+
- Token extraction (success, missing script tag, missing token, HTTP non-200 / client error, timeout).
|
|
64
|
+
- Targets parsing (v2 dict with Latin-1 bytes, v1 list fallback, malformed JSON, empty target list, network/timeout errors).
|
|
65
|
+
- `to_range_url` edge cases (with query params, existing `/range/...`, unexpected paths).
|
|
66
|
+
- Unloaded latency (with & without warmup, probe error handling).
|
|
67
|
+
- Download + loaded latency (sliding window, dynamic worker scaling, clean cancellation with zero leaked tasks).
|
|
68
|
+
- Upload (reusable chunk buffer streaming, dynamic scaling, worker failure, clean cancellation).
|
|
69
|
+
- Session ownership (`session` injected stays open vs internally created closes on `__aexit__`), IPv4/IPv6 mutual exclusion & connector family.
|
|
70
|
+
- `async_fast_com` & sync `fast_com` drop-in dictionary contract.
|
|
71
|
+
3. **`tests/test_cli.py`**: Human-readable output, `--json` output, and clean error exit status.
|
|
72
|
+
4. **`tests/test_real_api_calls.py`**: Marked `@pytest.mark.real_api_call`, tests live `async_fast_com` and `fast_com` end-to-end against `fast.com`.
|
|
73
|
+
5. **Verify quality gates**:
|
|
74
|
+
- `uv run ruff check --no-fix .`
|
|
75
|
+
- `uv run ruff format --check .`
|
|
76
|
+
- `uv run mypy fastdotcom tests`
|
|
77
|
+
- `uv run pytest` (100% offline, `>= 95%` branch coverage, zero warnings)
|
|
78
|
+
- `uv build`
|
|
79
|
+
- `uv run pytest -m real_api_call --no-cov`
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Phase 4: GitHub Actions CI/CD & PyPI Release (`v1.0.0`)
|
|
84
|
+
|
|
85
|
+
1. **Create `.github/workflows/main.yml`**:
|
|
86
|
+
- Triggers: `push` to `main`, `pull_request`, `workflow_dispatch`.
|
|
87
|
+
- Matrix: Python `["3.11", "3.12", "3.13", "3.14", "3.15"]`.
|
|
88
|
+
- Use `actions/checkout@v7` and `astral-sh/setup-uv@v10.4.0` (exact semver tag).
|
|
89
|
+
- Steps: `uv sync --locked` → `ruff check` → `ruff format --check` → `mypy` → `pytest --cov-report xml:coverage.xml` → `uv build`.
|
|
90
|
+
2. **Create `.github/workflows/publish.yml`**:
|
|
91
|
+
- Triggers: `release: types: [published]`, `workflow_dispatch`.
|
|
92
|
+
- `environment: pypi`, `permissions: id-token: write`.
|
|
93
|
+
- Publish via `pypa/gh-action-pypi-publish@release/v1` with `attestations: true`.
|
|
94
|
+
3. **Create `.github/workflows/live_api.yml`**:
|
|
95
|
+
- Triggers: `schedule: [{cron: "0 10 * * 1"}]`, `workflow_dispatch`.
|
|
96
|
+
- Runs `uv run pytest -m real_api_call --no-cov`.
|
|
97
|
+
4. **Push & verify workflows**:
|
|
98
|
+
- Commit cleanly (`git config user.name/email` already set to `Marco Sousa <marcomsousa@gmail.com>`), push to `origin main`, and watch `main.yml` and `live_api.yml` pass green via `gh run list --json` + `gh run watch`.
|
|
99
|
+
5. **PyPI Trusted Publishing & `v1.0.0` Release**:
|
|
100
|
+
- Register Pending Publisher on `pypi.org` for `fastdotcom-ng` (`marcomsousa/fastdotcom-ng`, `publish.yml`, environment `pypi`).
|
|
101
|
+
- Create GitHub Release `v1.0.0` (`gh release create v1.0.0 ...`) and verify `publish.yml` publishes `fastdotcom-ng` with PEP 740 attestations.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Phase 5: Home Assistant Core Integration PRs (2-PR Strategy)
|
|
106
|
+
|
|
107
|
+
1. **PR 1 (Minimal Dependency Bump Only):**
|
|
108
|
+
- Branch off `home-assistant/core:dev`.
|
|
109
|
+
- Update only `homeassistant/components/fastdotcom/manifest.json` (`"fastdotcom-ng==1.0.0"`), `requirements_all.txt`, `requirements_test_all.txt` (and `package_constraints.txt` if needed).
|
|
110
|
+
- Audit `git diff` carefully so nothing unrelated changes, run HA component tests & `hassfest`/requirements checks, and open PR 1.
|
|
111
|
+
2. **PR 2 (Native Async & Extra Sensors — after PR 1 merges):**
|
|
112
|
+
- Update `homeassistant/components/fastdotcom/coordinator.py` to use `await async_fast_com(session=async_get_clientsession(hass))` directly on the event loop instead of `async_add_executor_job`.
|
|
113
|
+
- Expose **Upload**, **Unloaded Latency**, and **Loaded Latency** sensors in `sensor.py` (with optional `options_flow` toggles to disable upload/latency if desired).
|