github-traffic-tracker 0.2.8a0__py3-none-any.whl

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.
Files changed (20) hide show
  1. ghtraf/__init__.py +9 -0
  2. ghtraf/__main__.py +8 -0
  3. ghtraf/_version.py +70 -0
  4. ghtraf/cli.py +172 -0
  5. ghtraf/commands/__init__.py +6 -0
  6. ghtraf/commands/create.py +392 -0
  7. ghtraf/config.py +182 -0
  8. ghtraf/configure.py +215 -0
  9. ghtraf/gh.py +183 -0
  10. ghtraf/gist.py +132 -0
  11. ghtraf/output.py +58 -0
  12. ghtraf/templates/docs/stats/README.md +52 -0
  13. ghtraf/templates/docs/stats/favicon.svg +6 -0
  14. ghtraf/templates/docs/stats/index.html +2715 -0
  15. github_traffic_tracker-0.2.8a0.dist-info/METADATA +159 -0
  16. github_traffic_tracker-0.2.8a0.dist-info/RECORD +20 -0
  17. github_traffic_tracker-0.2.8a0.dist-info/WHEEL +5 -0
  18. github_traffic_tracker-0.2.8a0.dist-info/entry_points.txt +3 -0
  19. github_traffic_tracker-0.2.8a0.dist-info/licenses/LICENSE +674 -0
  20. github_traffic_tracker-0.2.8a0.dist-info/top_level.txt +1 -0
github_traffic_tracker-0.2.8a0.dist-info/METADATA ADDED
@@ -0,0 +1,159 @@
1
+ Metadata-Version: 2.4
2
+ Name: github-traffic-tracker
3
+ Version: 0.2.8a0
4
+ Summary: Zero-server GitHub traffic analytics — daily collection via Actions, gist-backed storage, client-side dashboard
5
+ Author-email: Dustin <6962246+djdarcy@users.noreply.github.com>
6
+ License-Expression: GPL-3.0-or-later
7
+ Project-URL: Homepage, https://github.com/djdarcy/github-traffic-tracker
8
+ Project-URL: Repository, https://github.com/djdarcy/github-traffic-tracker
9
+ Project-URL: Issues, https://github.com/djdarcy/github-traffic-tracker/issues
10
+ Project-URL: Dashboard, https://djdarcy.github.io/github-traffic-tracker/stats/
11
+ Keywords: github,traffic,analytics,badges,gist,actions,dashboard,clones,views,stars
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Software Development :: Version Control :: Git
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
26
+ Dynamic: license-file
27
+
28
+ # GitHub Traffic Tracker
29
+
30
+ [![Version][version-badge]][version-url] [![Python 3.10+][python-badge]][python-url] [![License][license-badge]][license-url] [![GitHub Discussions][discussions-badge]][discussions-url] [![Platform][platform-badge]][platform-url]
31
+
32
+ Zero-server GitHub traffic analytics — daily collection, permanent history, smart badges.
33
+
34
+ **Live from this repo's own tracker:**
35
+
36
+ [![Installs][installs-badge]][installs-url] [![Views][views-badge]][views-url] [![Clones][clones-badge]][clones-url]
37
+
38
+ ## The Problem
39
+
40
+ GitHub's Traffic API only retains **14 days** of clone and view data. After that it's gone forever. If you don't capture it daily, you lose permanent visibility into how your project is being used. There's no built-in way to accumulate traffic history over time.
41
+
42
+ GitHub Traffic Tracker solves this with zero infrastructure via a GitHub Actions workflow that collects your data daily and stores it in a Gist, giving you permanent traffic history with no servers and no cost.
43
+
44
+ ## How It Works
45
+
46
+ ```mermaid
47
+ flowchart LR
48
+ A["GitHub Actions<br/>daily · 3am UTC"] -->|"clones · views<br/>downloads · stars"| B["Public Gist<br/>state.json + badges"]
49
+ A -->|"monthly"| C["Archive Gist<br/>long-term snapshots"]
50
+ B -->|"client-side fetch"| D["Dashboard<br/>GitHub Pages"]
51
+ B -->|"shields.io endpoint"| E["Badges<br/>README / anywhere"]
52
+ ```
53
+
54
+ A GitHub Actions workflow runs daily at 3am UTC, fetching clone, view, download, star, and referrer data from the GitHub API. It merges new data into a running `state.json` stored in a public Gist, always preserving the highest values seen (merge upward, never erase). Shields.io-compatible badge JSON files are updated alongside the state. A separate unlisted Gist receives monthly archive snapshots for long-term storage. The static HTML dashboard reads directly from the Gist CDN, completing the loop with no backend at all.
55
+
56
+ ## Features
57
+
58
+ - **Daily data collection** — Clones, views, downloads, stars, forks, referrers, popular paths
59
+ - **Permanent history** — Accumulates beyond the 14-day API window indefinitely
60
+ - **Unique visitor tracking** — Unique cloners and viewers alongside raw counts
61
+ - **CI clone detection** — Separates organic clones from CI/CD checkout noise
62
+ - **Cascading recency badges** — `installs 1,234 (+18 24h)` → `(+88 wk)` → `(+145 mo)`
63
+ - **Tabbed dashboard** — Overview, Installs, Views, Community, Dev tabs
64
+ - **Monthly archives** — Long-term snapshots in a separate unlisted Gist
65
+ - **Zero server** — Pure GitHub Actions + Gist storage + client-side rendering
66
+
67
+ ## Quick Start
68
+
69
+ **Prerequisites:** [gh CLI](https://cli.github.com) installed and authenticated, Python 3.10+
70
+
71
+ ### Option A: ghtraf CLI (recommended)
72
+
73
+ ```bash
74
+ pip install github-traffic-tracker
75
+ ghtraf create --owner YOUR_ORG --repo YOUR_REPO --configure
76
+ ```
77
+
78
+ ### Option B: Standalone script
79
+
80
+ ```bash
81
+ # Interactive — prompts for all values
82
+ python setup-gists.py
83
+
84
+ # Or fully automated
85
+ python setup-gists.py --owner YOUR_ORG --repo YOUR_REPO --configure
86
+
87
+ # Preview without making changes
88
+ python setup-gists.py --dry-run
89
+ ```
90
+
91
+ Both options will:
92
+ 1. Create a public badge Gist and an unlisted archive Gist
93
+ 2. Set repository variables (`TRAFFIC_GIST_ID`, `TRAFFIC_ARCHIVE_GIST_ID`)
94
+ 3. Guide you through creating a PAT with `gist` scope
95
+ 4. Optionally configure the dashboard and workflow files (`--configure`)
96
+
97
+ After setup, copy `.github/workflows/traffic-badges.yml` to your repo, enable GitHub Pages (Settings > Pages > Deploy from branch > main, /docs), and push.
98
+
99
+ ## Badge Showcase
100
+
101
+ | Badge | What it shows | Example |
102
+ |-------|--------------|---------|
103
+ | **Installs** | Downloads + clones combined, with cascading recency | `installs 1,234 (+18 24h)` |
104
+ | **Views** | Repository page views with recency | `views 5,678 (+92 24h)` |
105
+ | **Clones** | Git clones (organic, excluding CI) | `clones 890 (+7 24h)` |
106
+ | **Downloads** | Release asset downloads | `downloads 456` |
107
+
108
+ Recency cascades automatically: the badge shows the most recent non-zero period — `(+N 24h)` if there's activity today, otherwise `(+N wk)`, then `(+N mo)`. This gives visitors a sense of project activity at a glance.
109
+
110
+ ```markdown
111
+ [![Installs](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/USER/GIST_ID/raw/installs.json)](https://USER.github.io/REPO/stats/#installs)
112
+ ```
113
+
114
+ ## Live Dashboards
115
+
116
+ This system is actively running on:
117
+
118
+ - **[GitHub Traffic Tracker](https://djdarcy.github.io/github-traffic-tracker/stats/)** — This project (dogfooding since day 1)
119
+ - **[NCSI Resolver](https://dazzletools.github.io/Windows-No-Internet-Secured-BUGFIX/stats/)** — Origin project (v0.7.12)
120
+ - **[ComfyUI Triton & SageAttention](https://dazzleml.github.io/comfyui-triton-and-sageattention-installer/stats/#installs)** — First port (v0.8.3)
121
+
122
+ ## Roadmap
123
+
124
+ See [ROADMAP.md](ROADMAP.md) or [Issue #1 — Roadmap](https://github.com/djdarcy/github-traffic-tracker/issues/1) for the full plan.
125
+
126
+ ## Contributing
127
+
128
+ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
129
+
130
+ Like the project?
131
+
132
+ [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)
133
+
134
+ ## License
135
+
136
+ Github-Traffic-Tracker (ghtraf), Copyright (C) 2025 Dustin Darcy
137
+
138
+ This project is licensed under the GNU General Public License v3.0 — see [LICENSE](LICENSE) for details.
139
+
140
+ <!-- Badge references -->
141
+
142
+ [version-badge]: https://img.shields.io/github/v/release/djdarcy/github-traffic-tracker?sort=semver&color=darkgreen
143
+ [version-url]: https://github.com/djdarcy/github-traffic-tracker/releases
144
+ [installs-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/installs.json
145
+ [installs-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#installs
146
+ [views-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/views.json
147
+ [views-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#views
148
+ [clones-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/clones.json
149
+ [clones-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#clones
150
+ [downloads-badge]: https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/djdarcy/fffb1b8632243b40ad183a161ff0f32e/raw/downloads.json
151
+ [downloads-url]: https://djdarcy.github.io/github-traffic-tracker/stats/#installs
152
+ [python-badge]: https://img.shields.io/badge/python-3.10+-darkgreen
153
+ [python-url]: https://www.python.org/downloads/
154
+ [license-badge]: https://img.shields.io/badge/license-GPLv3-darkgreen
155
+ [license-url]: https://www.gnu.org/licenses/gpl-3.0
156
+ [discussions-badge]: https://img.shields.io/github/discussions/djdarcy/github-traffic-tracker
157
+ [discussions-url]: https://github.com/djdarcy/github-traffic-tracker/discussions
158
+ [platform-badge]: https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey
159
+ [platform-url]: docs/platform-support.md
github_traffic_tracker-0.2.8a0.dist-info/RECORD ADDED
@@ -0,0 +1,20 @@
1
+ ghtraf/__init__.py,sha256=s6epIJ4xjEyHucEwYwf23WSGCRdnQbnI0Jl3a0vJOHk,257
2
+ ghtraf/__main__.py,sha256=kVDd_ybS3jGHWW8TRpJ4bk2VcHkE-JDCOOOGsdY5VAc,131
3
+ ghtraf/_version.py,sha256=R458OGpQSDig-kaHypIsn36JSftdIiCZQoK4fbB-O9Q,2003
4
+ ghtraf/cli.py,sha256=vVrGu4cQHv8vBMbRV0lUHfM_-xHCh-nnUxJm--WatlE,5944
5
+ ghtraf/config.py,sha256=63hiKfy8fqBJ9AeM-HqjKvMBNa7DIdxyOJCvhQXP4lY,5846
6
+ ghtraf/configure.py,sha256=QZ0IifXjMQLRHKUtKmG5cFF06XrL9MVkWQPTl5flHqw,7196
7
+ ghtraf/gh.py,sha256=kfK-f4396bhtWI2hkjyR26mRKZSA4LCrfKvSG9GyBnc,4986
8
+ ghtraf/gist.py,sha256=V2Evc4K93e2HNUt3DFumWbBnijSEt9TjnChcPIXZ-RI,4134
9
+ ghtraf/output.py,sha256=M5ULt6FEQQcOVHVTbNTmKjFubWzyV812LnDx6BveYAw,1270
10
+ ghtraf/commands/__init__.py,sha256=lO6Cpk9piJxNLUsqStMbPRCYfDdn8ZEh5rmlrIG6ed4,160
11
+ ghtraf/commands/create.py,sha256=5iC0_-xkNS2ZuQovF2y-SYHdA9Y3kKQRaYCuzkxFfjE,14616
12
+ ghtraf/templates/docs/stats/README.md,sha256=bQKI7XGsrKqfTOdaEbk3UAxCYrfDEhIqZOqn5JlqHig,2477
13
+ ghtraf/templates/docs/stats/favicon.svg,sha256=rv6g5Huw5D7acsO1pf_5YEfTYpM_E3lVnHcwD6EY11c,287
14
+ ghtraf/templates/docs/stats/index.html,sha256=ZHnjTz67WFVf8SXhZL1iidLa4XkDp1tGYGfYj7odjbU,119105
15
+ github_traffic_tracker-0.2.8a0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
16
+ github_traffic_tracker-0.2.8a0.dist-info/METADATA,sha256=7Uae8jLJNT6fF7E0tdrPEcWnQZq2jl4GnLHTY4nlAJ0,8372
17
+ github_traffic_tracker-0.2.8a0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
18
+ github_traffic_tracker-0.2.8a0.dist-info/entry_points.txt,sha256=ANRdTzM692-rby-jZC5kdJFdGNb6TE_kQXIqmNxKOas,84
19
+ github_traffic_tracker-0.2.8a0.dist-info/top_level.txt,sha256=_SEH2RoP_JdsjPBk1zflw6VPJZZ4plqXIAMRd5bzE6I,7
20
+ github_traffic_tracker-0.2.8a0.dist-info/RECORD,,
github_traffic_tracker-0.2.8a0.dist-info/WHEEL ADDED
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
github_traffic_tracker-0.2.8a0.dist-info/entry_points.txt ADDED
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ ghtraf = ghtraf.cli:main
3
+ github-traffic-tracker = ghtraf.cli:main