gitlytics 0.6.0__tar.gz → 0.6.2__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.
Files changed (53) hide show
  1. {gitlytics-0.6.0 → gitlytics-0.6.2}/PKG-INFO +104 -162
  2. gitlytics-0.6.2/README.md +323 -0
  3. {gitlytics-0.6.0 → gitlytics-0.6.2}/pyproject.toml +1 -1
  4. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/__init__.py +1 -1
  5. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/core.py +120 -105
  6. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics.egg-info/PKG-INFO +104 -162
  7. gitlytics-0.6.0/README.md +0 -381
  8. {gitlytics-0.6.0 → gitlytics-0.6.2}/LICENSE +0 -0
  9. {gitlytics-0.6.0 → gitlytics-0.6.2}/setup.cfg +0 -0
  10. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/__main__.py +0 -0
  11. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/api.py +0 -0
  12. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/automation.py +0 -0
  13. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/cli.py +0 -0
  14. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/process.py +0 -0
  15. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/_headers +0 -0
  16. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/_redirects +0 -0
  17. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/android-chrome-192x192.png +0 -0
  18. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/android-chrome-512x512.png +0 -0
  19. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/apple-touch-icon.png +0 -0
  20. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/CardModal-9oHMecdc.js +0 -0
  21. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/ExportModal-M_KmGZ_C.js +0 -0
  22. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/html2canvas-pro.esm-9xys3ejh.js +0 -0
  23. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/html2canvas.esm-DXEQVQnt.js +0 -0
  24. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/index-Bro5YaCJ.css +0 -0
  25. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/index-wOhawfKi.js +0 -0
  26. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/index.es-tlOthHFQ.js +0 -0
  27. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/jspdf.es.min-DD49TTEi.js +0 -0
  28. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/assets/purify.es-CC4Brkr_.js +0 -0
  29. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/favicon-16x16.png +0 -0
  30. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/favicon-32x32.png +0 -0
  31. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/favicon-48x48.png +0 -0
  32. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/favicon.ico +0 -0
  33. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/gitlytics-logo.png +0 -0
  34. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/google-search-icon-48x48.png +0 -0
  35. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/google-search-icon.png +0 -0
  36. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/index.html +0 -0
  37. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/llms-full.txt +0 -0
  38. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/llms.txt +0 -0
  39. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/robots.txt +0 -0
  40. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/site.webmanifest +0 -0
  41. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics/static/sitemap.xml +0 -0
  42. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics.egg-info/SOURCES.txt +0 -0
  43. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics.egg-info/dependency_links.txt +0 -0
  44. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics.egg-info/entry_points.txt +0 -0
  45. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics.egg-info/requires.txt +0 -0
  46. {gitlytics-0.6.0 → gitlytics-0.6.2}/src/gitlytics.egg-info/top_level.txt +0 -0
  47. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_api.py +0 -0
  48. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_automation.py +0 -0
  49. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_cli.py +0 -0
  50. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_core.py +0 -0
  51. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_process.py +0 -0
  52. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_star_history.py +0 -0
  53. {gitlytics-0.6.0 → gitlytics-0.6.2}/tests/test_username.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: gitlytics
3
- Version: 0.6.0
3
+ Version: 0.6.2
4
4
  Summary: Monitor and automate your GitHub repository traffic analytics.
5
5
  Author-email: Ameya Chopade <ameyaccod171@gmail.com>
6
6
  License: Apache-2.0
@@ -35,8 +35,8 @@ Dynamic: license-file
35
35
 
36
36
  <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/logo.png" alt="Gitlytics Logo" width="150" />
37
37
 
38
- # Gitlytics
39
- ### GitHub Traffic Analytics & Automation
38
+ # Gitlytics v0.6.2
39
+ ### GitHub Traffic Analytics, Dynamic Widgets & Automation
40
40
 
41
41
  [![License](https://api.gitlytics.dev/api/badge/tech.svg?slug=license&style=icon_label_value&label=License&label_color=%23555555&variant=plastic&value=Apache+2.0&value_color=%232F81F7)](LICENSE)
42
42
  [![Python](https://api.gitlytics.dev/api/badge/tech.svg?slug=python&style=icon_label_value&label=Python&label_color=%23555555&variant=plastic&value=3.9%2B&value_color=%233776AB)](https://www.python.org/)
@@ -45,23 +45,25 @@ Dynamic: license-file
45
45
  [![FastAPI](https://api.gitlytics.dev/api/badge/tech.svg?slug=fastapi&style=icon_label_value&label=Backend&label_color=%23555555&variant=plastic&value=FastAPI&value_color=%23009688)](https://fastapi.tiangolo.com/)
46
46
  [![Automation](https://api.gitlytics.dev/api/badge/tech.svg?slug=githubactions&style=icon_label_value&label=Data+Backup&label_color=%23555555&variant=plastic&value=Automation&value_color=%232088FF)](https://github.com/ameyac11/gitlytics-github-traffic-automation)
47
47
  [![Homepage](https://api.gitlytics.dev/api/badge/tech.svg?slug=homepage&style=icon_label_value&label=Homepage&label_color=%23555555&variant=plastic&value=gitlytics.dev&value_color=%233FB950)](https://gitlytics.dev)
48
+ [![Blog](https://api.gitlytics.dev/api/badge/tech.svg?slug=blog&style=icon_label_value&label=Blog&label_color=%23555555&variant=plastic&value=blog.gitlytics.dev&value_color=%233FB950)](https://blog.gitlytics.dev)
48
49
  [![Live](https://api.gitlytics.dev/api/badge/tech.svg?slug=livedemo&style=icon_label_value&label=Live+Demo&label_color=%23555555&variant=plastic&value=dashboard.gitlytics.dev&value_color=%233FB950)](https://dashboard.gitlytics.dev)
49
50
  [![Docs](https://api.gitlytics.dev/api/badge/tech.svg?slug=docs&style=icon_label_value&label=Docs&label_color=%23555555&variant=plastic&value=docs.gitlytics.dev&value_color=%233FB950)](https://docs.gitlytics.dev)
50
51
 
51
52
  <br/>Please consider giving this project a ⭐ if you find it helpful! <br/>
52
53
 
53
- **Beautiful GitHub traffic analytics for all your repositories — public and private.** <br/> Track views, clones, referrers, and popular paths indefinitely.
54
+ **Beautiful GitHub traffic analytics for all your repositories — public and private.** <br/> Track views, clones, referrers, popular paths, stargazer trajectories, and health metrics indefinitely.
54
55
 
55
56
  ✨ **[Try the live dashboard at dashboard.gitlytics.dev](https://dashboard.gitlytics.dev)** ✨
57
+ 📝 **[Read engineering deep-dives at blog.gitlytics.dev](https://blog.gitlytics.dev)** ✨
56
58
  📚 **[Read the documentation at docs.gitlytics.dev](https://docs.gitlytics.dev)**
57
59
 
58
60
  </div>
59
61
 
60
62
  ---
61
63
 
62
- ## 🎨 Interactive Profile Widgets & Badges (Live Demo)
64
+ ## 🎨 Interactive Profile Widgets, Cards & Badges
63
65
 
64
- Elevate your GitHub profile README and developer portfolios with Gitlytics' native, dynamic widget rendering suite. Serve real-time stats cards, commit-level language breakdowns, concept tags, and social badges.
66
+ Elevate your GitHub profile README and developer portfolios with Gitlytics' native, dynamic widget rendering suite. Serve real-time stats cards, commit-level language breakdowns, repository health scorecards, concept tags, and tech badges.
65
67
 
66
68
  ### 📇 Profile & Repository Cards
67
69
  Showcase your global activity or project metrics with gorgeous, theme-customizable cards:
@@ -71,87 +73,83 @@ Showcase your global activity or project metrics with gorgeous, theme-customizab
71
73
  <tr>
72
74
  <td align="center" width="50%">
73
75
  <b>👤 User Profile Details Card</b> (Tokyo Night + Coral Title)<br/>
74
- <img src="https://api.gitlytics.dev/api/cards/profile-details/demo.svg?theme=tokyonight&title=ff9e64&text=a9b1d6&accent_secondary=7aa2f7" alt="Profile Details" width="380" />
76
+ <img src="https://api.gitlytics.dev/api/cards/profile-details/demo.svg?theme=tokyonight&title=ff9e64&text=a9b1d6&accent_secondary=7aa2f7&v=2" alt="Profile Details" width="380" />
75
77
  </td>
76
78
  <td align="center" width="50%">
77
79
  <b>📈 Repository Metrics Card</b> (Nord + Dark Steel Slate)<br/>
78
- <img src="https://api.gitlytics.dev/api/cards/stats/demo.svg?theme=nord&title=88c0d0&text=d8dee9&bg=2e3440&border=4c566a" alt="Repository Stats" width="380" />
80
+ <img src="https://api.gitlytics.dev/api/cards/stats/demo.svg?theme=nord&title=88c0d0&text=d8dee9&bg=2e3440&border=4c566a&v=2" alt="Repository Stats" width="380" />
79
81
  </td>
80
82
  </tr>
81
83
  <tr>
82
84
  <td align="center" width="50%">
83
85
  <b>📊 Language Distribution Chart</b> (Radical + Pink Accents)<br/>
84
- <img src="https://api.gitlytics.dev/api/cards/repos-per-language/demo.svg?theme=radical&title=fe60a1&accent_secondary=a6e22e" alt="Language Distribution" width="380" />
86
+ <img src="https://api.gitlytics.dev/api/cards/repos-per-language/demo.svg?theme=radical&title=fe60a1&accent_secondary=a6e22e&v=2" alt="Language Distribution" width="380" />
85
87
  </td>
86
88
  <td align="center" width="50%">
87
89
  <b>🔥 Contribution Streak Tracker</b> (Solarized Dark + Olive green)<br/>
88
- <img src="https://api.gitlytics.dev/api/cards/contribution-streak/demo.svg?theme=solarized_dark&title=268bd2&text=859900&bg=002b36&hide_border=true" alt="Contribution Streak" width="380" />
90
+ <img src="https://api.gitlytics.dev/api/cards/contribution-streak/demo.svg?theme=solarized_dark&title=268bd2&text=859900&bg=002b36&hide_border=true&v=2" alt="Contribution Streak" width="380" />
89
91
  </td>
90
92
  </tr>
91
93
  </table>
92
94
  </div>
93
95
 
94
- ### 🏷️ Multi-Source Tech Badges & Concepts
96
+ ### 🏷️ Multi-Source Tech Badges & Concept Capsules
95
97
  Generate beautifully styled capsule badges for your tech stack. Support for **200+ technology logos** from official libraries, plus **custom text-only capsule badges** for concepts without brand icons (e.g. AI/ML methods, SRE, RAG):
96
98
 
97
99
  <div align="center">
98
100
 
99
101
  **🛠️ Languages & Frameworks (Multi-color & Flat Brand Colors)**
100
102
 
101
- <img src="https://api.gitlytics.dev/api/logos/python.svg?style=logo_text" alt="Python" /> &nbsp;
102
- <img src="https://api.gitlytics.dev/api/logos/typescript.svg?style=logo_text" alt="TypeScript" /> &nbsp;
103
- <img src="https://api.gitlytics.dev/api/logos/react.svg?style=logo_text" alt="React" /> &nbsp;
104
- <img src="https://api.gitlytics.dev/api/logos/fastapi.svg?style=logo_text" alt="FastAPI" /> &nbsp;
105
- <img src="https://api.gitlytics.dev/api/logos/docker.svg?style=logo_text" alt="Docker" /> &nbsp;
106
- <img src="https://api.gitlytics.dev/api/logos/aws.svg?style=logo_text" alt="AWS" />
103
+ <img src="https://api.gitlytics.dev/api/logos/typescript.svg?style=logo_text&v=2" alt="TypeScript" /> &nbsp;
104
+ <img src="https://api.gitlytics.dev/api/logos/python.svg?style=logo_text&v=2" alt="Python" /> &nbsp;
105
+ <img src="https://api.gitlytics.dev/api/logos/react.svg?style=logo_text&v=2" alt="React" /> &nbsp;
106
+ <img src="https://api.gitlytics.dev/api/logos/fastapi.svg?style=logo_text&v=2" alt="FastAPI" /> &nbsp;
107
+ <img src="https://api.gitlytics.dev/api/logos/aws.svg?style=logo_text&v=2" alt="AWS" /> &nbsp;
108
+ <img src="https://api.gitlytics.dev/api/logos/docker.svg?style=logo_text&v=2" alt="Docker" />
107
109
 
108
110
  <br/><br/>
109
111
 
110
112
  **🧠 AI/ML & Engineering Concepts (Text-Only Capsules)**
111
113
 
112
- <img src="https://api.gitlytics.dev/api/logos/rag.svg" alt="RAG" /> &nbsp;
113
- <img src="https://api.gitlytics.dev/api/logos/embeddings.svg" alt="Embeddings" /> &nbsp;
114
- <img src="https://api.gitlytics.dev/api/logos/vectorsearch.svg" alt="Vector Search" /> &nbsp;
115
- <img src="https://api.gitlytics.dev/api/logos/agenticai.svg" alt="Agentic AI" /> &nbsp;
116
- <img src="https://api.gitlytics.dev/api/logos/finetuning.svg" alt="Fine-Tuning" />
114
+ <img src="https://api.gitlytics.dev/api/logos/agenticai.svg?v=2" alt="Agentic AI" /> &nbsp;
115
+ <img src="https://api.gitlytics.dev/api/logos/rag.svg?v=2" alt="RAG" /> &nbsp;
116
+ <img src="https://api.gitlytics.dev/api/logos/embeddings.svg?v=2" alt="Embeddings" /> &nbsp;
117
+ <img src="https://api.gitlytics.dev/api/logos/vectorsearch.svg?v=2" alt="Vector Search" /> &nbsp;
118
+ <img src="https://api.gitlytics.dev/api/logos/finetuning.svg?v=2" alt="Fine-Tuning" />
117
119
 
118
120
  <br/><br/>
119
121
 
120
122
  **🔗 Contact & Platform Connectors**
121
123
 
122
- <img src="https://api.gitlytics.dev/api/logos/portfolio.svg" alt="Portfolio" /> &nbsp;
123
- <img src="https://api.gitlytics.dev/api/logos/linkedin.svg?style=logo_text" alt="LinkedIn" /> &nbsp;
124
- <img src="https://api.gitlytics.dev/api/logos/gmail.svg?style=logo_text" alt="Gmail" /> &nbsp;
125
- <img src="https://api.gitlytics.dev/api/logos/github.svg?style=logo_text" alt="GitHub" /> &nbsp;
126
- <img src="https://api.gitlytics.dev/api/logos/x.svg?style=logo_text" alt="X" />
124
+ <img src="https://api.gitlytics.dev/api/logos/github.svg?style=logo_text&v=2" alt="GitHub" /> &nbsp;
125
+ <img src="https://api.gitlytics.dev/api/logos/linkedin.svg?style=logo_text&v=2" alt="LinkedIn" /> &nbsp;
126
+ <img src="https://api.gitlytics.dev/api/logos/gmail.svg?style=logo_text&v=2" alt="Gmail" /> &nbsp;
127
+ <img src="https://api.gitlytics.dev/api/logos/portfolio.svg?v=2" alt="Portfolio" /> &nbsp;
128
+ <img src="https://api.gitlytics.dev/api/logos/x.svg?style=logo_text&v=2" alt="X" />
127
129
 
128
130
  </div>
129
131
 
130
132
  ---
131
133
 
132
- <div align="center">
133
- <img src="https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_1.png" width="100%" />
134
- </div>
135
-
136
- ---
137
-
138
134
  ## 📌 Table of Contents
139
135
 
140
136
  - [🔗 The Gitlytics Ecosystem](#-the-gitlytics-ecosystem)
141
- - [🚨 The 14-Day Catch (And How We Fix It)](#-the-14-day-catch-and-how-we-fix-it)
137
+ - [🤖 Cloud AI Analysis & Automated Insights](#-cloud-ai-analysis--automated-insights)
138
+ - [📝 Blog & Engineering Space](#-blog--engineering-space)
139
+ - [🔑 Flexible Authentication Modes](#-flexible-authentication-modes)
140
+ - [🚨 Defeating GitHub's 14-Day Traffic Limit](#-defeating-githubs-14-day-traffic-limit)
142
141
  - [🛠️ Installation](#installation)
143
- - [🔑 Generating a GitHub Personal Access Token](#generating-a-github-personal-access-token)
144
- - [⌨️ The 4 Core CLI Commands](#the-4-core-cli-commands)
145
- - [1️⃣ `gitlytics fetch` (Live Terminal Data)](#1-gitlytics-fetch-live-terminal-data)
146
- - [2️⃣ `gitlytics sync` (Background Database Cron)](#2-gitlytics-sync-background-database-cron)
147
- - [3️⃣ `gitlytics dashboard` (React Web UI)](#3-gitlytics-dashboard-react-web-ui)
148
- - [4️⃣ `gitlytics stars` (Stargazer History)](#4-gitlytics-stars-stargazer-history)
142
+ - [⌨️ Core CLI Commands](#core-cli-commands)
143
+ - [1️⃣ `gitlytics fetch`](#1-gitlytics-fetch-live-terminal-data)
144
+ - [2️⃣ `gitlytics sync`](#2-gitlytics-sync-background-database-cron)
145
+ - [3️⃣ `gitlytics dashboard`](#3-gitlytics-dashboard-react-web-ui)
146
+ - [4️⃣ `gitlytics stars`](#4-gitlytics-stars-stargazer-history)
149
147
  - [🐍 Native Python API](#native-python-api)
150
148
  - [1️⃣ `gitlytics.fetch_traffic()`](#1-gitlyticsfetch_traffic)
151
149
  - [2️⃣ `gitlytics.sync()`](#2-gitlyticssync)
152
150
  - [3️⃣ `gitlytics.serve_dashboard()`](#3-gitlyticsserve_dashboard)
153
151
  - [4️⃣ `gitlytics.fetch_star_history()`](#4-gitlyticsfetch_star_history)
154
- - [📊 CSV Output Columns](#csv-output-columns)
152
+ - [📊 CSV Database Schema](#csv-database-schema)
155
153
  - [🌟 Show Your Support](#show-your-support)
156
154
  - [📄 License](#license)
157
155
 
@@ -159,22 +157,58 @@ Generate beautifully styled capsule badges for your tech stack. Support for **20
159
157
 
160
158
  ## 🔗 The Gitlytics Ecosystem
161
159
 
162
- The full Gitlytics ecosystem spans across a few repositories. If you are looking for the live web dashboard or the automation cron job, check out the links below:
160
+ The full Gitlytics platform consists of modular open-source components:
163
161
 
164
- - 📊 **[Gitlytics Live Dashboard](https://dashboard.gitlytics.dev)**: The production web interface to visualize repository traffic analytics, trends, and historical charts.
165
- - ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: The GitHub Action companion tool that automates fetching and saving to defeat GitHub's 14-day traffic limit.
162
+ - 📊 **[Gitlytics Live Dashboard](https://dashboard.gitlytics.dev)**: Production web interface to visualize repository traffic, trends, and historical charts.
163
+ - 📝 **[Gitlytics Blog](https://blog.gitlytics.dev)**: Engineering deep-dives, comparison guides, and open-source analytics tutorials.
164
+ - 📚 **[Gitlytics Metadata Pages & Docs](https://docs.gitlytics.dev)**: Technical reference, badge explorer, and CLI documentation.
165
+ - ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: GitHub Action companion tool that fetches and backs up traffic data automatically.
166
166
 
167
167
  ---
168
168
 
169
- ## 🚨 The 14-Day Catch (And How We Fix It)
169
+ ## 🤖 Cloud AI Analysis & Automated Insights
170
+
171
+ Gitlytics Cloud includes an automated AI intelligence engine powered by LLMs (Groq API) and cloud database synchronization (Supabase):
172
+
173
+ - **Automated AI Repository Health Checks**: Analyzes repository traffic trends, CI stability, PR cycle times, and contributor activity to produce automated health scorecards.
174
+ - **Anomaly & Spike Detection**: Identifies traffic surges, viral referrer shifts, and clone spikes, surfacing actionable insights.
175
+ - **Cloud Persistence & Multi-Repo Aggregation**: Synchronizes historical snapshots to cloud storage, enabling seamless multi-repository comparison and organization-wide analytics.
176
+ - **Weekly Email Digest Reports**: Delivers automated weekly summaries (via Resend API) summarizing top referral channels, view growth, and stargazer milestones directly to your inbox.
177
+
178
+ ---
179
+
180
+ ## 📝 Blog & Engineering Space
181
+
182
+ Explore our official engineering publication at **[blog.gitlytics.dev](https://blog.gitlytics.dev)**:
183
+
184
+ - **Engineering Deep-Dives**: Learn how Gitlytics solves GitHub's 14-day traffic retention cap, renders high-performance SVG badges, and handles multi-repository data pipelines.
185
+ - **Comparison Guides**: Detailed breakdowns comparing Gitlytics with native GitHub Insights, Shields.io, and third-party analytics platforms.
186
+ - **AI Agent Context**: The blog provides a dedicated structured text endpoint ([`https://blog.gitlytics.dev/llms-full.txt`](https://blog.gitlytics.dev/llms-full.txt)) formatted specifically for consumption by AI agents and LLM tools.
187
+
188
+ ---
189
+
190
+ ## 🔑 Flexible Authentication Modes
191
+
192
+ Gitlytics v0.6.2 supports 3 authentication modes:
193
+
194
+ 1. **Token Authentication (PAT)**: Pass your GitHub Personal Access Token (Classic or Fine-Grained) with `repo` scope to fetch private & public repository metrics.
195
+ 2. **Demo Mode (Instant Exploration)**: Explore the web dashboard and CLI immediately using curated sample data without entering any credentials.
196
+ 3. **Headless TV & Kiosk Mode**: Pre-authenticate sessions for office monitors or team dashboards:
197
+ ```bash
198
+ gitlytics dashboard --token "ghp_xxxx" --data-dir "./data"
199
+ ```
200
+
201
+ ---
202
+
203
+ ## 🚨 Defeating GitHub's 14-Day Traffic Limit
170
204
 
171
205
  > **⚠️ Did you know?** GitHub normally **only saves your repository traffic data for 14 days**. After two weeks, your valuable views and clones data is permanently deleted.
172
206
 
173
- **Don't lose your data!** We built a companion automation tool that runs silently in the background every 13 days using GitHub Actions to fetch and save your data permanently.
207
+ We built a companion automation tool that runs silently every 13 days using GitHub Actions to snapshot and preserve your traffic data.
174
208
 
175
- 👉 **[Set up GitHub Traffic Automation here](https://github.com/ameyac11/gitlytics-github-traffic-automation)** (It takes literally 2 minutes to set up!)
209
+ 👉 **[Set up GitHub Traffic Automation here](https://github.com/ameyac11/gitlytics-github-traffic-automation)** (Takes under 2 minutes to set up!)
176
210
 
177
- Once you have your automated CSV data saved from that tool, you can seamlessly plug it right into `gitlytics` to visualize beautiful, long-term historical charts stretching back months or years!
211
+ Once your traffic snapshots are saved, Gitlytics automatically merges overlaps to build continuous historical analytics over months or years.
178
212
 
179
213
  ---
180
214
 
@@ -183,28 +217,21 @@ Once you have your automated CSV data saved from that tool, you can seamlessly p
183
217
  Install via PyPI:
184
218
 
185
219
  ```bash
186
- # Basic CLI and Python Module installation
220
+ # Basic CLI and Python Core Module
187
221
  pip install gitlytics
188
222
 
189
- # Full installation (includes React Dashboard dependencies)
223
+ # Full installation (includes React Dashboard web engine)
190
224
  pip install "gitlytics[dashboard]"
191
225
  ```
192
226
 
193
- ### 🔑 Generating a GitHub Personal Access Token
194
- To use the tools, you'll need a GitHub token.
195
- 1. Go to **[GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)**
196
- 2. Click **Generate new token (classic)**
197
- 3. Select the **`repo`** scope *(required to read traffic data for private repositories)*
198
- 4. Click **Generate token** and copy it!
199
-
200
227
  ---
201
228
 
202
- ## ⌨️ The 4 Core CLI Commands
229
+ ## ⌨️ Core CLI Commands
203
230
 
204
- Gitlytics is powered by 4 massive command-line tools. You can run them anywhere in your terminal.
231
+ Gitlytics provides 4 primary command-line utilities:
205
232
 
206
233
  ### 1️⃣ `gitlytics fetch` (Live Terminal Data)
207
- Fetch your live 14-day traffic and print a beautiful ASCII table directly in your console.
234
+ Fetch your live 14-day traffic and print ASCII tables directly in your console.
208
235
  ```bash
209
236
  gitlytics fetch --token ghp_your_token_here --print-table
210
237
 
@@ -213,32 +240,24 @@ gitlytics fetch --token ghp_your_token_here --print-table --metrics views clones
213
240
  ```
214
241
 
215
242
  ### 2️⃣ `gitlytics sync` (Background Database Cron)
216
- Tired of losing data? Use `sync` to permanently append today's traffic to a CSV database. You can even run it as a background cron job (perfect for Raspberry Pi or Linux/Cloud servers)!
243
+ Append traffic snapshots to local CSV databases. Can run as a background cron job:
217
244
  ```bash
218
245
  # Sync once
219
246
  gitlytics sync --token ghp_your_token --data-dir ./data
220
247
 
221
- # Sync specific metrics only
222
- gitlytics sync --token ghp_your_token --data-dir ./data --metrics views clones
223
-
224
- # Run permanently in the background as a cron job (runs at 11:00 PM every day)
248
+ # Run as a background cron job (runs daily at 11:00 PM)
225
249
  gitlytics sync --token ghp_your_token --data-dir ./data --schedule-cron "0 23 * * *"
226
250
  ```
227
251
 
228
252
  ### 3️⃣ `gitlytics dashboard` (React Web UI)
229
- Launch the beautiful React + FastAPI web interface.
253
+ Launch the React + FastAPI web dashboard.
230
254
  ```bash
231
255
  gitlytics dashboard
232
256
  ```
233
- > **📺 Headless TV Mode:** Want to display the dashboard on an office TV monitor? Pass the historical database and token directly so the UI auto-loads without requiring a manual browser login!
234
- > ```bash
235
- > gitlytics dashboard --token "ghp_xxx" --data-dir "./data"
236
- > ```
237
257
 
238
258
  ### 4️⃣ `gitlytics stars` (Stargazer History)
239
- Fetch the historical cumulative stargazer growth trajectory for a repository.
259
+ Fetch the historical cumulative stargazer growth trajectory for a repository.
240
260
  ```bash
241
- # Fetch and print star history table
242
261
  gitlytics stars owner/repo --token ghp_your_token
243
262
  ```
244
263
 
@@ -246,137 +265,60 @@ gitlytics stars owner/repo --token ghp_your_token
246
265
 
247
266
  ## 🐍 Native Python API
248
267
 
249
- You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
250
-
251
- 📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
268
+ Import Gitlytics into Python applications to build custom analytics pipelines or host the web engine programmatically.
252
269
 
253
270
  ### 1️⃣ `gitlytics.fetch_traffic()`
254
- Fetches the last 14 days of traffic data (views, clones, referrers, paths) for one or more repositories.
255
-
256
271
  ```python
257
272
  import gitlytics
258
273
 
259
- # Fetch traffic for all repositories accessible by the token
274
+ # Fetch traffic for all accessible repositories
260
275
  df = gitlytics.fetch_traffic(
261
276
  token="ghp_your_token",
262
- return_format="dataframe" # Options: "dataframe" (Pandas), "timeseries" (chart-ready dict), or "summary" (per-repo totals dict)
263
- )
264
-
265
- # Fetch traffic for a single specific repository and print the table to stdout
266
- gitlytics.fetch_traffic(
267
- token="ghp_your_token",
268
- repo_name="username/my-repo",
269
- print_table=True
270
- )
271
-
272
- # Save output directly to a file (CSV or JSON depending on file extension)
273
- gitlytics.fetch_traffic(
274
- token="ghp_your_token",
275
- return_format="dataframe",
276
- save_file="./data/traffic.csv"
277
+ return_format="dataframe" # Options: "dataframe", "timeseries", or "summary"
277
278
  )
278
279
  ```
279
280
 
280
- #### ⚙️ Parameters:
281
- | Parameter | Type | Default | Description |
282
- |---|---|---|---|
283
- | `token` | `str` | *Required* | GitHub Personal Access Token with `repo` scope enabled. |
284
- | `repo_name` | `str` | `None` | Specific repository name (e.g. `"user/repo"`). If `None`, fetches all repositories. |
285
- | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
286
- | `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
287
- | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
288
- | `metrics` | `list` | `None` | Optional. List of metrics to fetch (e.g., `["views", "clones"]`). |
289
-
290
- ---
291
-
292
281
  ### 2️⃣ `gitlytics.sync()`
293
- Fetches the live traffic data and appends it to a persistent CSV database. Handles merging overlaps and duplicates. Can be scheduled with an internal cron scheduler for cloud deployments.
294
-
295
282
  ```python
296
283
  import gitlytics
297
284
 
298
- # Standard run: Syncs current snapshots to the CSV database and exports UI JSON
299
- gitlytics.sync(
300
- token="ghp_your_token",
301
- data_dir="./data",
302
- export_json="./data/export.json",
303
- export_public_only=True # Security Firewall: Exclude private repos from the public-facing export.json
304
- )
305
-
306
- # Scheduled Cloud Worker: Run infinitely using standard cron schedule syntax
285
+ # Sync snapshots and export consolidated JSON for the dashboard
307
286
  gitlytics.sync(
308
287
  token="ghp_your_token",
309
288
  data_dir="./data",
310
- schedule_cron="0 23 * * *", # Runs everyday at 11:00 PM UTC
311
289
  export_json="./data/export.json"
312
290
  )
313
291
  ```
314
292
 
315
- #### ⚙️ Parameters:
316
- | Parameter | Type | Default | Description |
317
- |---|---|---|---|
318
- | `token` | `str` | *Required* | GitHub Personal Access Token. |
319
- | `repo_name` | `str` or `list` | `None` | Specific repository name(s) to sync. If `None`, syncs all repositories. |
320
- | `data_dir` | `str` | `"./data"` | Directory where CSV files are saved. |
321
- | `output_mode` | `str` | `"monthly"` | File grouping frequency: `"monthly"` (creates `traffic_YYYY-MM.csv`) or `"yearly"` (creates `traffic_YYYY.csv`). |
322
- | `schedule_cron` | `str` | `None` | Optional cron expression (e.g., `"*/15 * * * *"`). If set, runs an infinite scheduler loop. |
323
- | `export_json` | `str` | `None` | Optional. Path to compile and export a consolidated history JSON for the frontend. |
324
- | `export_public_only` | `bool` | `True` | Security firewall: if `True`, strips private repository data from the compiled `export_json`. |
325
- | `metrics` | `list` | `None` | Optional. List of metrics to sync (e.g., `["views", "clones"]`). |
326
-
327
- ---
328
-
329
293
  ### 3️⃣ `gitlytics.serve_dashboard()`
330
- Launches the FastAPI backend and hosts the embedded React SPA dashboard.
331
-
332
294
  ```python
333
295
  import gitlytics
334
296
 
335
- # Host the dashboard programmatically on a custom host/port
297
+ # Serve the dashboard programmatically on a custom port
336
298
  gitlytics.serve_dashboard(
337
299
  host="0.0.0.0",
338
300
  port=8080,
339
- token="ghp_your_token", # Pre-authenticates the dashboard session
340
- data_dir="./data" # Folder containing the historical databases
301
+ token="ghp_your_token",
302
+ data_dir="./data"
341
303
  )
342
304
  ```
343
305
 
344
- #### ⚙️ Parameters:
345
- | Parameter | Type | Default | Description |
346
- |---|---|---|---|
347
- | `host` | `str` | `"127.0.0.1"` | Host IP to bind the FastAPI server. Use `"0.0.0.0"` to listen on all interfaces. |
348
- | `port` | `int` | `8000` | Port to run the web server on. |
349
- | `token` | `str` | `None` | Optional. Pre-authenticates the dashboard session to bypass the login screen. |
350
- | `data_dir` | `str` | `None` | Optional. Path to the folder containing your synced CSV or JSON databases. |
351
-
352
- ---
353
-
354
306
  ### 4️⃣ `gitlytics.fetch_star_history()`
355
- Fetches a list of cumulative star counts per date for a given repository.
356
-
357
307
  ```python
358
308
  import gitlytics
359
309
 
360
- # Fetch stargazer history timeline
361
310
  points = gitlytics.fetch_star_history(
362
311
  owner="ameyac11",
363
312
  repo="gitlytics",
364
- token="ghp_your_token" # Optional for public repos, recommended to avoid rate limits
313
+ token="ghp_your_token"
365
314
  )
366
315
  ```
367
316
 
368
- #### ⚙️ Parameters:
369
- | Parameter | Type | Default | Description |
370
- |---|---|---|---|
371
- | `owner` | `str` | *Required* | Owner of the repository. |
372
- | `repo` | `str` | *Required* | Repository name. |
373
- | `token` | `str` | `None` | Optional GitHub Personal Access Token. |
374
-
375
317
  ---
376
318
 
377
- ## 📊 CSV Output Columns
319
+ ## 📊 CSV Database Schema
378
320
 
379
- When you sync data, the local CSV databases track 23 detailed metrics by default. If you customize the metrics using the `--metrics` CLI flag or `metrics` Python parameter, the CSV columns will dynamically include only the columns corresponding to your selection (along with the default `date`, `repository`, and `is_private` identification columns).
321
+ Local CSV databases track up to 23 metrics per snapshot:
380
322
 
381
323
  | Column | Type | Description |
382
324
  |---|---|---|
@@ -395,11 +337,11 @@ When you sync data, the local CSV databases track 23 detailed metrics by default
395
337
  | `pushed_at` | `str` | Last push ISO timestamp. |
396
338
  | `created_at` | `str` | Repository creation ISO timestamp. |
397
339
  | `open_issues_count` | `int` | Total number of open issues. |
398
- | `top_referrer` | `str` | Top external traffic referral source (14-day rolling window). |
340
+ | `top_referrer` | `str` | Top external traffic referral source. |
399
341
  | `top_referrer_views` | `int` | Views sent by the top referrer. |
400
342
  | `top_referrer_uniques` | `int` | Uniques sent by the top referrer. |
401
343
  | `_raw_referrers` | `str` | Raw JSON array of all referral sources. |
402
- | `top_path` | `str` | Most visited repository file path (14-day rolling window). |
344
+ | `top_path` | `str` | Most visited repository file path. |
403
345
  | `top_path_views` | `int` | Views for the top path. |
404
346
  | `top_path_uniques` | `int` | Uniques for the top path. |
405
347
  | `_raw_paths` | `str` | Raw JSON array of all popular paths. |
@@ -408,7 +350,7 @@ When you sync data, the local CSV databases track 23 detailed metrics by default
408
350
 
409
351
  ## 🌟 Show Your Support
410
352
 
411
- If you find this project useful, please consider giving it a ⭐ on [GitHub](https://github.com/ameyac11/gitlytics)! It helps more people discover the tool.
353
+ If you find this project useful, please consider giving it a ⭐ on [GitHub](https://github.com/ameyac11/gitlytics)!
412
354
 
413
355
  ## 📄 License
414
356
  Licensed under the [Apache License 2.0](LICENSE).