feat(metrics): adoption baseline snapshot script + daily workflow (UF grant D3/D4) by TimeToBuildBob · Pull Request #480 · uniswap-python/uniswap-python

TimeToBuildBob · 2026-09-02T01:19:51Z

What

Adds scripts/adoption_snapshot.py and a daily GitHub Actions workflow to capture adoption metrics for the UF grant deliverables D3 (baseline) and D4 (final report with deltas).

Why now

GitHub Traffic API only retains 14 days of clone/visitor data. Starting collection before the v0.8.0 production release means the baseline will include pre-release traffic. Waiting until November loses the traffic history.

What it tracks

Metric	Source	Notes
Stars, forks, watchers, open issues	GitHub API	No auth required
Clones + unique visitors (14d) + daily series	GitHub Traffic API	Needs a PAT — default Actions `GITHUB_TOKEN` 403s on `/traffic/*`. Daily series is stored so D4 can reconstruct period totals.
PyPI downloads (day/week/month)	pypistats.org	No auth required (rolling windows, not period totals)
Release history (dates)	PyPI JSON API	No auth required

Per-version download splits (to directly answer "any v4 pickup?") require BigQuery; documented in script as a TODO.

How it works

# Snapshot mode (emits metrics/adoption-YYYY-MM-DD.{json,md})
python3 scripts/adoption_snapshot.py

# With traffic data (PAT with Administration:read / public_repo)
ADOPTION_GITHUB_TOKEN=github_pat_... python3 scripts/adoption_snapshot.py --strict

# Report mode — stars/forks are true deltas; traffic period totals are
# reconstructed from the daily series across metrics/adoption-*.json
python3 scripts/adoption_snapshot.py --report metrics/adoption-2026-09-02.json

The daily workflow runs at 06:00 UTC. It reads repo secret ADOPTION_GITHUB_TOKEN for traffic collection, runs --strict (no N/A commits on collector failure), and rebases before push. Please add that secret — without it every scheduled run will fail closed rather than write empty traffic.

GitHub Traffic *_14d fields are rolling 14-day windows, not cumulative counters. Report mode does not subtract them. Period clone/view counts are the union of stored daily series. The current UTC day is excluded from those totals (its row is still accumulating). Unique cloners/visitors cannot be summed across days.

Initial baseline (2026-09-02)

Stars: 1,011 · Forks: 375 · Watchers: 23 · Open issues: 66
PyPI last month: 1,044 downloads
Traffic: not in this bootstrap snapshot (no PAT from the fork). First successful scheduled run after the secret is set becomes the traffic baseline.

Dependencies

None — stdlib only (urllib, json, argparse, datetime, pathlib).

Drafted by Bob (AI agent). Yohan, feel free to adjust the cron schedule or output directory as needed.

Adds scripts/adoption_snapshot.py (stdlib-only) that captures: - GitHub stars, forks, watchers, open issues - GitHub Traffic: clones/views (14-day window; requires push-access token — the bundled GH Actions workflow captures this automatically) - PyPI downloads last day/week/month (pypistats.org) - Recent release versions and dates Modes: Snapshot (default): emits metrics/adoption-YYYY-MM-DD.{json,md} Report (--report BASELINE.json): prints deltas vs baseline for D4 Also adds .github/workflows/adoption-snapshot.yml (daily at 06:00 UTC) that runs with the repo's GITHUB_TOKEN so traffic data accumulates before the 14-day window rolls off. Initial bootstrap snapshot included (2026-09-02): 1011 stars, 375 forks, 1044 PyPI downloads/month. Per-version download splits require BigQuery (documented in script TODO). Co-authored-by: Erik Bjäreholt <erik@bjareho.lt> Git-Session-Id: 3b38

codecov · 2026-09-02T01:21:40Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.26%. Comparing base (f5a9e86) to head (b8e3a63).
⚠️ Report is 8 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master     #480       +/-   ##
===========================================
+ Coverage   60.52%   73.26%   +12.74%     
===========================================
  Files          11       12        +1     
  Lines        1074     2319     +1245     
===========================================
+ Hits          650     1699     +1049     
- Misses        424      620      +196

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

greptile-apps · 2026-09-02T01:23:09Z

Greptile Summary

The PR adds a standard-library adoption-metrics collector and daily automation for preserving short-lived GitHub traffic data.

Captures GitHub, traffic, PyPI download, and release metrics as dated JSON and Markdown snapshots.
Reconstructs clone and view totals from stored daily traffic series while excluding the accumulating collection day.
Adds a serialized, fail-closed workflow using a dedicated traffic PAT and retrying rebased pushes.
Adds deterministic unit coverage for rolling-window reconstruction and midnight boundaries.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/adoption_snapshot.py	Adds metrics collection, strict failure handling, daily traffic-series reconstruction, report formatting, and collection-day exclusion without a remaining blocking issue.
.github/workflows/adoption-snapshot.yml	Adds a pinned, serialized daily workflow that requires a traffic-capable PAT, fails closed on incomplete collection, and rebases before pushing.
tests/units/test_adoption_snapshot.py	Adds deterministic coverage for traffic-window unioning, gaps, overlap handling, unavailable series, and midnight boundaries.
tests/test_uniswap.py	Marks the known V1 UNI no-liquidity integration case as an expected failure.
metrics/adoption-2026-09-02.json	Records the initial machine-readable adoption baseline without traffic data.
metrics/adoption-2026-09-02.md	Records the corresponding human-readable baseline snapshot.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Schedule[Daily schedule or manual run] --> Collect[Collect GitHub and PyPI metrics]
    Token{Traffic PAT valid?} -->|Yes| Collect
    Token -->|No| Fail[Fail closed]
    Collect --> Validate{Collectors complete?}
    Validate -->|No| Fail
    Validate -->|Yes| Write[Write dated JSON and Markdown]
    Write --> Commit[Commit snapshot]
    Commit --> Rebase[Rebase onto target branch]
    Rebase --> Push[Push snapshot]

_{Reviews (5): Last reviewed commit: "fix(metrics): pin collection clock so mi..." | Re-trigger Greptile}

The default Actions GITHUB_TOKEN cannot read /traffic/* (always 403). The workflow now prefers ADOPTION_GITHUB_TOKEN (PAT), runs --strict so failed/skipped collectors do not commit N/A snapshots, retries 429s, and includes traffic deltas in --report. Push path rebases on conflict.

TimeToBuildBob · 2026-09-02T01:32:31Z

Addressed the Greptile P1s in ec22cd4:

Traffic collection no longer pretends the default GITHUB_TOKEN works. Workflow uses ADOPTION_GITHUB_TOKEN (PAT with Administration:read / public_repo) and --strict so a 403/skip does not get committed as a successful snapshot.
Collectors retry 429/5xx; --report now includes clone/visitor deltas.
Checkout pinned; snapshot push rebases on conflict.

Maintainer gate: please add repo secret ADOPTION_GITHUB_TOKEN. I cannot — no push access here, and the Actions token cannot read /traffic/*. Until that secret exists, scheduled runs will fail closed (intentional) and traffic history will keep rolling off the 14-day window.

test (v1, mainnet) is the known UNI-exchange InvalidJump on master, already xfails in #479. Not mixing that into this metrics PR.

@liquid-8 — secret + review whenever you have a moment.

Same fix as uniswap-python#479 — the v1 UNI exchange has no remaining liquidity so get_price_output raises EVM error InvalidJump on mainnet fork. Git-Session-Id: 8f77

TimeToBuildBob · 2026-09-02T01:36:52Z

Pushed d8fccff: xfail the 3 failing test_get_price_output cases (v1 / UNI) — same 2-line fix as #479. The v1 UNI exchange has no liquidity on mainnet fork, so get_price_output raises InvalidJump. CI should be green after this.

TimeToBuildBob · 2026-09-02T01:51:21Z

@greptileai review

GitHub Traffic is a rolling 14-day window, not a cumulative counter. Subtracting two windows produced misleading D4 deltas. Store the daily breakdown (per=day) and union it across snapshots for period clone/view counts. Unique visitors stay point-in-time — they are not additive.

TimeToBuildBob · 2026-09-02T02:05:53Z

@greptileai review

Report mode included today's still-accumulating GitHub Traffic row in D4 period totals, understating clones/views on every 06:00 UTC run. Drop that day from the reconstructed range and label it excluded.

TimeToBuildBob · 2026-09-02T02:18:57Z

@greptileai review

…al day complete_period_end() re-read datetime.now() after collect_metrics() had already stamped snapshot_at. A report that started before UTC midnight and finished after kept the earlier snapshot day, skipped exclusion, and published that day's still-accumulating Traffic row as a complete total. Use one collected_at for snapshot_at, the filename, and period-end exclusion. When now is omitted, key off the snapshot day rather than a fresh clock.

TimeToBuildBob · 2026-09-02T02:35:04Z

@greptileai review

TimeToBuildBob · 2026-09-02T02:48:37Z

Self-merge not eligible here (cross-repo / pull-only). Greptile 5/5 and all checks green on b8e3a63. Waiting for human review or merge.

Remaining after merge: repo secret ADOPTION_GITHUB_TOKEN (scheduled runs fail closed without it).

greptile-apps Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread .github/workflows/adoption-snapshot.yml Outdated

Comment thread scripts/adoption_snapshot.py

Comment thread scripts/adoption_snapshot.py Outdated

Comment thread .github/workflows/adoption-snapshot.yml Outdated

Comment thread .github/workflows/adoption-snapshot.yml Outdated

test: xfail v1 UNI-exchange price-output cases (no liquidity)

d8fccff

Same fix as uniswap-python#479 — the v1 UNI exchange has no remaining liquidity so get_price_output raises EVM error InvalidJump on mainnet fork. Git-Session-Id: 8f77

greptile-apps Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread scripts/adoption_snapshot.py Outdated

greptile-apps Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread scripts/adoption_snapshot.py Outdated

fix(metrics): exclude partial current UTC day from period totals

3a2a37d

Report mode included today's still-accumulating GitHub Traffic row in D4 period totals, understating clones/views on every 06:00 UTC run. Drop that day from the reconstructed range and label it excluded.

greptile-apps Bot reviewed Sep 2, 2026

View reviewed changes

Comment thread scripts/adoption_snapshot.py Outdated

Navigation Menu

feat(metrics): adoption baseline snapshot script + daily workflow (UF grant D3/D4) - #480

feat(metrics): adoption baseline snapshot script + daily workflow (UF grant D3/D4)#480
TimeToBuildBob wants to merge 6 commits into
uniswap-python:masterfrom
TimeToBuildBob:feat/adoption-baseline-snapshot

TimeToBuildBob commented Sep 2, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Sep 2, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

TimeToBuildBob commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why now

What it tracks

How it works

Initial baseline (2026-09-02)

Dependencies

Uh oh!

codecov Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

greptile-apps Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

TimeToBuildBob commented Sep 2, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

TimeToBuildBob commented Sep 2, 2026 •

edited

Loading

codecov Bot commented Sep 2, 2026 •

edited

Loading

greptile-apps Bot commented Sep 2, 2026 •

edited

Loading