gitpulse-analytics 0.2.0__py3-none-any.whl

gitpulse/storage.py

@@ -0,0 +1,61 @@
+"""SQLite persistence for collected traffic snapshots."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def default_db_path() -> Path:
+    configured = os.getenv("GITPULSE_DB")
+    if configured:
+        return Path(configured).expanduser()
+    return Path.home() / ".local" / "share" / "gitpulse" / "gitpulse.sqlite3"
+
+
+class SnapshotStore:
+    """Store timestamped GitHub traffic responses locally."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or default_db_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS snapshots (
+                    id INTEGER PRIMARY KEY,
+                    owner TEXT NOT NULL,
+                    repo TEXT NOT NULL,
+                    metric TEXT NOT NULL,
+                    fetched_at TEXT NOT NULL,
+                    payload TEXT NOT NULL
+                )"""
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_snapshots_repo_metric "
+                "ON snapshots(owner, repo, metric, fetched_at)"
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.path)
+
+    def save(self, owner: str, repo: str, metric: str, payload: dict[str, Any]) -> None:
+        fetched_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO snapshots(owner, repo, metric, fetched_at, payload) VALUES (?, ?, ?, ?, ?)",
+                (owner, repo, metric, fetched_at, json.dumps(payload)),
+            )
+
+    def history(self, owner: str, repo: str, metric: str, limit: int = 30) -> list[dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                """SELECT fetched_at, payload FROM snapshots
+                   WHERE owner = ? AND repo = ? AND metric = ?
+                   ORDER BY fetched_at DESC, id DESC LIMIT ?""",
+                (owner, repo, metric, limit),
+            ).fetchall()
+        return [{"fetched_at": stamp, **json.loads(payload)} for stamp, payload in reversed(rows)]

gitpulse_analytics-0.2.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: gitpulse-analytics
+Version: 0.2.0
+Summary: GitHub traffic, clones, referrers, and release downloads in your terminal, with org-wide HTML dashboards
+Project-URL: Homepage, https://github.com/fullstackspectrum/gitpulse
+Project-URL: Issues, https://github.com/fullstackspectrum/gitpulse/issues
+Project-URL: Changelog, https://github.com/fullstackspectrum/gitpulse/releases
+Author-email: FullStackSpectrum <dev@fullstackspectrum.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,cli,dashboard,downloads,github,releases,traffic
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: requests<3,>=2.32
+Requires-Dist: rich<15,>=13.7
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GitPulse
+
+A local Python CLI for GitHub repository traffic and release asset download stats. GitPulse can build a dashboard for a whole organization, and it keeps SQLite snapshots so you have history beyond GitHub's short traffic window.
+
+> **What GitHub can tell you:** aggregate daily views and clones, unique counts, popular paths, referrers, and release-asset download totals. It does **not** identify individual visitors or people who cloned a repository. GitHub's traffic data is generally available for the most recent 14 days. Release asset downloads are not Homebrew formula install counts.
+
+![GitPulse organization dashboard](https://raw.githubusercontent.com/fullstackspectrum/gitpulse/main/docs/screenshots/dashboard-light.png)
+
+## Requirements
+
+- Python 3.10+
+- A GitHub token with access to the repositories you want to inspect. Classic tokens need the `repo` scope for private repositories. For fine-grained tokens, grant these repository permissions:
+
+  | Permission | Needed for |
+  | --- | --- |
+  | **Metadata: read** | All commands (always included) |
+  | **Contents: read** | `downloads`, and release downloads in `org` |
+  | **Administration: read** | `traffic`, `snapshot`, and traffic in `org` |
+
+  A fine-grained token only covers repositories owned by its resource owner, so org-owned repositories need a token whose resource owner is that org. Without a required permission, GitHub returns `Resource not accessible by personal access token`.
+
+Traffic endpoints only work for repositories you have push access to. Public visibility alone does not grant access to traffic analytics.
+
+## Install
+
+**Homebrew** (macOS and Linux):
+
+```sh
+brew install fullstackspectrum/gitpulse/gitpulse
+```
+
+**pipx or pip.** The package is called `gitpulse-analytics` on PyPI; the command it installs is `gitpulse`:
+
+```sh
+pipx install gitpulse-analytics
+# or
+python -m pip install gitpulse-analytics
+```
+
+**Docker.** Images for `linux/amd64` and `linux/arm64` are on [Docker Hub](https://hub.docker.com/r/fullstackspectrum/gitpulse). Mount a directory at `/data` to keep the HTML dashboard and snapshot history:
+
+```sh
+docker run --rm -e GITHUB_TOKEN -v "$PWD:/data" fullstackspectrum/gitpulse org ORG
+```
+
+The container runs as UID 1000. On Linux, if your user can't write the mounted directory as that UID, add `--user "$(id -u):$(id -g)"`.
+
+**From source**, for development:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+```
+
+Check the install with `gitpulse --version`.
+
+Set a token in your shell. `GITHUB_TOKEN` and `GH_TOKEN` are both supported. GitPulse never saves the token:
+
+```sh
+export GITHUB_TOKEN="github_pat_..."
+```
+
+If you use the [GitHub CLI](https://cli.github.com/) and are signed in with `gh auth login`, you can reuse its token instead:
+
+```sh
+export GITHUB_TOKEN="$(gh auth token)"
+```
+
+## Organization dashboard
+
+```sh
+gitpulse org ORG                                   # terminal summary + gitpulse-ORG.html
+gitpulse org ORG --open                            # also open the dashboard in your browser
+gitpulse org ORG --save                            # also save views/clones snapshots for `history`
+gitpulse org ORG --all --output reports/org.html   # include forks and archived repos, custom path
+```
+
+`org` works for an organization or a user account. It fetches every repository in parallel (`--workers`, default 8), then prints a summary in the terminal: totals, daily sparklines, a table of every repository, and the top referrers.
+
+![Terminal summary from gitpulse org](https://raw.githubusercontent.com/fullstackspectrum/gitpulse/main/docs/screenshots/terminal.png)
+
+It also writes a self-contained HTML dashboard to `gitpulse-ORG.html` in the current directory, or to the path you pass with `--output`. The dashboard shows:
+
+- Totals for views, unique visitors, clones, stars, forks, release downloads, and open issues and PRs
+- Daily views and clones summed across repositories, with a hover readout for each day
+- The most viewed and most starred repositories, a language breakdown, top referrers, and release downloads by repository
+- A sortable, filterable table of every repository with a 14-day views sparkline
+
+Styles, charts, and scripts are all inline, so it works offline (only the owner's avatar loads from GitHub). It follows your system's light or dark theme, and has a toggle to switch.
+
+![Dashboard in dark mode](https://raw.githubusercontent.com/fullstackspectrum/gitpulse/main/docs/screenshots/dashboard-dark.png)
+
+By default, forks and archived repositories are skipped; `--all` includes them. When your token can't read traffic for a repository, its stars, forks, and downloads still appear, and the dashboard lists which repositories are missing traffic and why. Unique visitor and cloner counts are summed per repository, so one person who visits two repositories is counted twice.
+
+*Screenshots show sample data.*
+
+## Repository commands
+
+```sh
+gitpulse --help
+gitpulse repos
+gitpulse repos --all
+gitpulse traffic OWNER/REPO
+gitpulse traffic OWNER/REPO --metric clones
+gitpulse traffic OWNER/REPO --metric referrers
+gitpulse traffic OWNER/REPO --metric popular/paths
+gitpulse traffic OWNER/REPO --metric views --save
+gitpulse snapshot OWNER/REPO
+gitpulse history OWNER/REPO --metric views
+gitpulse history OWNER/REPO --metric clones
+gitpulse downloads OWNER/REPO
+```
+
+`repos` lists repositories accessible to the authenticated account and filters forks and archived repositories by default. `--all` includes them.
+
+`traffic` displays GitHub's recent traffic response. `snapshot` fetches views and clones and saves both responses locally. Run it on a schedule (for example, daily) to build a history beyond GitHub's 14-day window. `history` displays saved snapshots; it does not backfill earlier data.
+
+`downloads` lists release asset download counts. It does not measure Homebrew formula installation.
+
+## Local data and privacy
+
+Snapshots are stored at `~/.local/share/gitpulse/gitpulse.sqlite3`. The database contains repository names and traffic responses, but no GitHub token. To use another location, set `GITPULSE_DB` to a SQLite file path.
+
+Generated dashboards contain repository names, descriptions, and traffic numbers, including for private repositories. Treat them like any other internal report before sharing. `gitpulse-*.html` files are ignored by git.
+
+## Homebrew tap usage
+
+For tap repositories, clone traffic and unique cloners can be useful directional signals, but they are not install totals. A tap clone, formula installation, and binary download are distinct events. GitHub does not expose an install-by-user report for formulae through these traffic endpoints.
+
+## Development
+
+Run tests with `pytest` and lint with `ruff check .`.
+
+### Releasing
+
+1. Bump `__version__` in `src/gitpulse/__init__.py` and merge to `main`.
+2. Publish a GitHub release with the tag `vX.Y.Z` matching that version.
+
+The `Release` workflow checks that the tag matches the version, then publishes to PyPI. After that it pushes the multi-arch Docker image and updates the formula in [homebrew-gitpulse](https://github.com/fullstackspectrum/homebrew-gitpulse). A release marked as a pre-release goes to PyPI and to Docker Hub under its exact version tag only, without moving `latest` or the Homebrew formula. The formula template lives in `packaging/homebrew/`; edit it there, not in the tap.

gitpulse_analytics-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gitpulse/__init__.py,sha256=uaujMt6z0EBrnPgON1unjO2ySnoGKc_kNgbgC2oG5W4,64
+gitpulse/cli.py,sha256=yR-NEx1DNm65vEFgnDw00JBWYVEX9U8vtn_7TaP8wJo,14849
+gitpulse/github_api.py,sha256=1kg_leP2BvUcoKlPorSIilJ9IZijrSbroWl9PD0L6LY,7104
+gitpulse/org.py,sha256=0rrKFhGvtUOowZmJQgI1XgCyoT94Bzhg-bNelacxRJA,6726
+gitpulse/report.py,sha256=F_gnkh_hwXL5zrB09HKQoz-Brk84ecD-q0IT9TPGQBw,28466
+gitpulse/storage.py,sha256=Sb6aMov3Kfr5e1YsSmB29jV7QuZLmeQGW5r8CEWJWqg,2319
+gitpulse_analytics-0.2.0.dist-info/METADATA,sha256=CYj1ayuzEhBrDFQQqDpruCNmQpjEQ25wf3ajvEJJNfU,8847
+gitpulse_analytics-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+gitpulse_analytics-0.2.0.dist-info/entry_points.txt,sha256=UYYnCPz2E3i16TG3b-nP_W9BealjSq4T-7CJYbsk_pk,46
+gitpulse_analytics-0.2.0.dist-info/licenses/LICENSE,sha256=AiW-x_jnANoG7qKtS_2u_hZjG4Z3a2J_MJU2faxlhzs,1069
+gitpulse_analytics-0.2.0.dist-info/RECORD,,

gitpulse_analytics-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gitpulse_analytics-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitpulse = gitpulse.cli:app

gitpulse_analytics-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin Moynes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.