gitpulse-analytics 0.2.0__py3-none-any.whl

gitpulse/__init__.py

@@ -0,0 +1,3 @@
+"""Local GitHub repository analytics."""
+
+__version__ = "0.2.0"

gitpulse/cli.py

@@ -0,0 +1,367 @@
+"""Command-line interface for GitPulse."""
+
+from __future__ import annotations
+
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+
+from gitpulse import __version__
+from gitpulse.github_api import GitHubAPIError, GitHubClient
+from gitpulse.org import OrgReport, collect_org
+from gitpulse.report import render_html
+from gitpulse.storage import SnapshotStore
+
+app = typer.Typer(
+    name="gitpulse",
+    help="Local GitHub repository traffic and release analytics.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"gitpulse {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show the version and exit."
+    ),
+) -> None:
+    """Local GitHub repository traffic and release analytics."""
+
+
+def _client() -> GitHubClient:
+    try:
+        return GitHubClient()
+    except GitHubAPIError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+def _run(action: Any) -> Any:
+    try:
+        return action()
+    except GitHubAPIError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+def _repo_parts(repository: str) -> tuple[str, str]:
+    parts = repository.strip("/").split("/")
+    if len(parts) != 2 or not all(parts):
+        raise typer.BadParameter("Use the OWNER/REPO format, for example octocat/Hello-World")
+    return parts[0], parts[1]
+
+
+def _traffic_table(owner: str, repo: str, metric: str, data: dict[str, Any]) -> Table:
+    table = Table(title=f"{owner}/{repo} · {metric}", header_style="bold cyan")
+    if metric in {"views", "clones"}:
+        table.add_column("Date")
+        table.add_column("Count", justify="right")
+        table.add_column("Unique", justify="right")
+        for item in data.get("views", data.get("clones", [])):
+            table.add_row(str(item.get("timestamp", ""))[:10], str(item.get("count", 0)), str(item.get("uniques", 0)))
+        if not table.row_count:
+            table.add_row("No recent data", "0", "0")
+    elif metric == "referrers":
+        table.add_column("Referrer")
+        table.add_column("Views", justify="right")
+        table.add_column("Unique", justify="right")
+        for item in data.get("referrers", []):
+            table.add_row(str(item.get("referrer", "")), str(item.get("count", 0)), str(item.get("uniques", 0)))
+        if not table.row_count:
+            table.add_row("No recent data", "0", "0")
+    else:
+        table.add_column("Path")
+        table.add_column("Title")
+        table.add_column("Views", justify="right")
+        table.add_column("Unique", justify="right")
+        for item in data.get("popular/paths", []):
+            table.add_row(str(item.get("path", "")), str(item.get("title", "")), str(item.get("count", 0)), str(item.get("uniques", 0)))
+        if not table.row_count:
+            table.add_row("No recent data", "", "0", "0")
+    return table
+
+
+@app.command("repos")
+def list_repos(
+    all_repos: bool = typer.Option(False, "--all", help="Include forks and archived repositories."),
+) -> None:
+    """List repositories the authenticated account can access."""
+    repos = _run(_client().list_repositories)
+    if not all_repos:
+        repos = [repo for repo in repos if not repo.get("fork") and not repo.get("archived")]
+    table = Table(title="Your repositories", header_style="bold cyan")
+    table.add_column("Repository")
+    table.add_column("Visibility")
+    table.add_column("Stars", justify="right")
+    table.add_column("Forks", justify="right")
+    table.add_column("Updated")
+    for repo in repos:
+        table.add_row(
+            repo.get("full_name", ""),
+            "private" if repo.get("private") else "public",
+            str(repo.get("stargazers_count", 0)),
+            str(repo.get("forks_count", 0)),
+            str(repo.get("updated_at", ""))[:10],
+        )
+    console.print(table)
+    console.print(f"[dim]{len(repos)} repositories[/dim]")
+
+
+@app.command()
+def traffic(
+    repository: str = typer.Argument(..., help="Repository in OWNER/REPO format."),
+    metric: str = typer.Option("views", "--metric", "-m", help="views, clones, referrers, or popular/paths"),
+    save: bool = typer.Option(False, "--save", help="Save this response to local history."),
+) -> None:
+    """Show recent views, clones, referrers, or popular paths."""
+    owner, repo = _repo_parts(repository)
+    if metric not in {"views", "clones", "referrers", "popular/paths"}:
+        raise typer.BadParameter("Choose views, clones, referrers, or popular/paths")
+    client = _client()
+    data = _run(lambda: client.traffic(owner, repo, metric))
+    console.print(_traffic_table(owner, repo, metric, data))
+    if save and metric in {"views", "clones"}:
+        SnapshotStore().save(owner, repo, metric, data)
+        console.print("[green]Snapshot saved locally.[/green]")
+    console.print("[dim]GitHub provides aggregate traffic data, not visitor identities; traffic history is typically limited to 14 days.[/dim]")
+
+
+@app.command()
+def snapshot(
+    repository: str = typer.Argument(..., help="Repository in OWNER/REPO format."),
+) -> None:
+    """Fetch and save today's views and clone traffic snapshots."""
+    owner, repo = _repo_parts(repository)
+    client = _client()
+    store = SnapshotStore()
+    for metric in ("views", "clones"):
+        data = _run(lambda metric=metric: client.traffic(owner, repo, metric))
+        store.save(owner, repo, metric, data)
+        console.print(_traffic_table(owner, repo, metric, data))
+    console.print("[green]Snapshots saved. Run this regularly to build longer-term history.[/green]")
+
+
+@app.command()
+def history(
+    repository: str = typer.Argument(..., help="Repository in OWNER/REPO format."),
+    metric: str = typer.Option("views", "--metric", "-m", help="views or clones"),
+    limit: int = typer.Option(30, min=1, max=1000, help="Number of saved snapshots to show."),
+) -> None:
+    """Show snapshots collected on this machine."""
+    owner, repo = _repo_parts(repository)
+    if metric not in {"views", "clones"}:
+        raise typer.BadParameter("History is available for views or clones")
+    rows = SnapshotStore().history(owner, repo, metric, limit)
+    table = Table(title=f"Local history · {owner}/{repo} · {metric}", header_style="bold cyan")
+    table.add_column("Collected at")
+    table.add_column("14-day total", justify="right")
+    table.add_column("Sum of daily uniques*", justify="right")
+    series_key = metric
+    found = False
+    for row in rows:
+        series = row.get(series_key, [])
+        total = sum(item.get("count", 0) for item in series)
+        uniques = sum(item.get("uniques", 0) for item in series)
+        table.add_row(row.get("fetched_at", ""), str(total), str(uniques))
+        found = True
+    if not found:
+        console.print("No snapshots yet. Run `gitpulse snapshot OWNER/REPO` to start collecting history.")
+    else:
+        console.print(table)
+        console.print("[dim]*Daily unique counts can overlap; this is not a distinct-visitor total.[/dim]")
+
+
+@app.command("downloads")
+def release_downloads(
+    repository: str = typer.Argument(..., help="Repository in OWNER/REPO format."),
+) -> None:
+    """Show GitHub release asset download counts (not Homebrew install counts)."""
+    owner, repo = _repo_parts(repository)
+    release_count, assets = _run(lambda: _client().release_downloads(owner, repo))
+    table = Table(title=f"Release asset downloads · {owner}/{repo}", header_style="bold cyan")
+    table.add_column("Release")
+    table.add_column("Asset")
+    table.add_column("Downloads", justify="right")
+    for asset in assets:
+        table.add_row(asset["release"], asset["name"], str(asset["download_count"]))
+    if not release_count:
+        console.print("No releases found.")
+    elif not assets:
+        console.print(
+            f"Found {release_count} release(s), but none have uploaded assets. GitHub does not "
+            "report download counts for the automatic source code archives."
+        )
+    else:
+        console.print(table)
+    console.print("[dim]Release asset counts do not indicate Homebrew formula installs or identify downloaders.[/dim]")
+
+
+SPARK_CHARS = "▁▂▃▄▅▆▇█"
+
+
+def _spark(values: list[int]) -> str:
+    peak = max(values, default=0)
+    if not peak:
+        return "[dim]" + "·" * len(values) + "[/dim]"
+    # Scale min..max so day-to-day movement shows even when traffic never drops to zero.
+    low = min(values)
+    span = (peak - low) or 1
+    return "".join(SPARK_CHARS[round((v - low) / span * (len(SPARK_CHARS) - 1))] for v in values)
+
+
+def _org_summary(report: OrgReport) -> None:
+    views = report.daily("views_daily")
+    days = [day for day, _ in views]
+    window = f"{days[0]} → {days[-1]}" if days else "no traffic data"
+    name = report.profile.get("name") or report.owner
+    console.print(
+        Panel.fit(
+            f"[bold]{name}[/bold] [dim]@{report.owner}[/dim]\n"
+            f"{len(report.repos)} repositories · traffic {window}",
+            border_style="cyan",
+        )
+    )
+
+    def tile(label: str, value: int, style: str = "bold") -> Panel:
+        return Panel(f"[{style}]{value:,}[/{style}]\n[dim]{label}[/dim]", expand=True, border_style="dim")
+
+    tiles = [
+        tile("views · 14d", report.total("views"), "bold cyan"),
+        tile("unique visitors*", report.total("view_uniques")),
+        tile("clones · 14d", report.total("clones"), "bold magenta"),
+        tile("stars", report.total("stars"), "bold yellow"),
+        tile("forks", report.total("forks")),
+        tile("release downloads", report.total("downloads"), "bold green"),
+    ]
+    grid = Table.grid(expand=True, padding=(0, 1))
+    for _ in range(3):
+        grid.add_column(ratio=1)
+    grid.add_row(*tiles[:3])
+    grid.add_row(*tiles[3:])
+    console.print(grid)
+    if views:
+        console.print(f"  [dim]daily views[/dim]  [cyan]{_spark([c for _, c in views])}[/cyan]")
+        clones = [c for _, c in report.daily("clones_daily")]
+        console.print(f"  [dim]daily clones[/dim] [magenta]{_spark(clones)}[/magenta]\n")
+
+    table = Table(header_style="bold cyan", box=box.SIMPLE_HEAD, expand=True)
+    table.add_column("Repository", overflow="fold")
+    table.add_column("Lang", style="dim")
+    for column in ("Stars", "Forks", "Views", "Unique", "Clones", "Downloads"):
+        table.add_column(column, justify="right")
+    table.add_column("14-day views")
+    for repo in report.repos:
+        ok = repo.traffic_error is None
+        na = "[dim]n/a[/dim]"
+        table.add_row(
+            repo.name + (" [dim](private)[/dim]" if repo.private else ""),
+            repo.language or "—",
+            f"{repo.stars:,}",
+            f"{repo.forks:,}",
+            f"{repo.views:,}" if ok else na,
+            f"{repo.view_uniques:,}" if ok else na,
+            f"{repo.clones:,}" if ok else na,
+            f"{repo.downloads:,}" if repo.releases_error is None else na,
+            f"[cyan]{_spark([repo.views_daily.get(d, 0) for d in days])}[/cyan]" if ok and days else "",
+        )
+    console.print(table)
+
+    referrers = report.referrers(limit=5)
+    if referrers:
+        ref_table = Table(title="Top referrers", header_style="bold cyan", box=box.SIMPLE_HEAD)
+        ref_table.add_column("Source")
+        ref_table.add_column("Views", justify="right")
+        ref_table.add_column("Unique*", justify="right")
+        for source, count, uniques in referrers:
+            ref_table.add_row(source, f"{count:,}", f"{uniques:,}")
+        console.print(ref_table)
+
+    missing = [repo for repo in report.repos if repo.traffic_error]
+    if missing:
+        console.print(
+            f"[yellow]Traffic unavailable for {len(missing)} of {len(report.repos)} repositories[/yellow] "
+            "[dim](the token needs Administration: Read or push access). See the dashboard for details.[/dim]"
+        )
+    console.print("[dim]*Unique counts are summed per repository, so one person can be counted more than once.[/dim]")
+
+
+@app.command("org")
+def org_dashboard(
+    owner: str = typer.Argument(..., help="Organization or user login."),
+    output: str = typer.Option(
+        "", "--output", "-o", help="HTML file to write. Defaults to gitpulse-OWNER.html."
+    ),
+    all_repos: bool = typer.Option(False, "--all", help="Include forks and archived repositories."),
+    open_browser: bool = typer.Option(False, "--open", help="Open the dashboard in your browser."),
+    save: bool = typer.Option(False, "--save", help="Also save views and clones snapshots to local history."),
+    workers: int = typer.Option(8, min=1, max=32, help="Repositories to fetch in parallel."),
+) -> None:
+    """Build an HTML dashboard of traffic, stars, and downloads across an organization."""
+    client = _client()
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,
+    ) as progress:
+        task = progress.add_task(f"Listing repositories for {owner}", total=None)
+        report = _run(
+            lambda: collect_org(
+                client,
+                owner,
+                include_all=all_repos,
+                workers=workers,
+                on_start=lambda count: progress.update(
+                    task, total=count, description=f"Fetching stats for {owner}"
+                ),
+                on_repo=lambda repo: progress.update(task, advance=1, description=repo.name),
+            )
+        )
+    if not report.repos:
+        console.print(f"No repositories found for [bold]{owner}[/bold].")
+        raise typer.Exit(code=1)
+
+    _org_summary(report)
+
+    if save:
+        store = SnapshotStore()
+        saved = 0
+        for repo in report.traffic_repos:
+            for metric, payload in repo.raw_traffic.items():
+                store.save(repo.owner, repo.name, metric, payload)
+            saved += 1
+        console.print(f"[green]Saved snapshots for {saved} repositories.[/green]")
+
+    path = Path(output or f"gitpulse-{report.owner}.html").expanduser().resolve()
+    path.write_text(render_html(report), encoding="utf-8")
+    console.print(f"\n[bold green]✓[/bold green] Dashboard written to [link={path.as_uri()}]{path}[/link]")
+    if open_browser:
+        webbrowser.open(path.as_uri())
+
+
+if __name__ == "__main__":
+    app()

gitpulse/github_api.py

@@ -0,0 +1,162 @@
+"""Small GitHub REST API client for GitPulse."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+from gitpulse import __version__
+
+
+class GitHubAPIError(RuntimeError):
+    """An error returned by the GitHub API or the local HTTP client."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class GitHubClient:
+    """Authenticated client for GitHub's REST API."""
+
+    def __init__(self, token: str | None = None, base_url: str = "https://api.github.com") -> None:
+        self.token = token or os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN")
+        if not self.token:
+            raise GitHubAPIError(
+                "No GitHub token found. Set GITHUB_TOKEN or GH_TOKEN to a personal access token."
+            )
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Accept": "application/vnd.github+json",
+                "Authorization": f"Bearer {self.token}",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": f"gitpulse/{__version__}",
+            }
+        )
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        url = path if path.startswith("http") else f"{self.base_url}{path}"
+        try:
+            response = self.session.get(url, params=params, timeout=20)
+        except requests.RequestException as exc:
+            raise GitHubAPIError(f"Could not connect to GitHub: {exc}") from exc
+
+        if response.status_code == 403 and response.headers.get("X-RateLimit-Remaining") == "0":
+            reset = response.headers.get("X-RateLimit-Reset")
+            hint = f" Rate limit resets at Unix time {reset}." if reset else ""
+            raise GitHubAPIError(f"GitHub API rate limit exceeded.{hint}")
+        detail = ""
+        if not response.ok:
+            try:
+                detail = response.json().get("message", "")
+            except (ValueError, AttributeError):
+                pass
+        suffix = f" GitHub said: {detail}" if detail else ""
+        is_traffic = "/traffic/" in url
+
+        if response.status_code == 404:
+            hint = (
+                "your token may lack permission to view its traffic data."
+                if is_traffic
+                else "your token may not have access to it."
+            )
+            raise GitHubAPIError(
+                f"GitHub returned 404. The repository may not exist, or {hint}{suffix}",
+                status=404,
+            )
+        if response.status_code == 403:
+            sso = response.headers.get("X-GitHub-SSO")
+            if sso:
+                raise GitHubAPIError(
+                    "GitHub denied this request because the organization requires SAML SSO. "
+                    f"Authorize your token for the organization ({sso}).{suffix}",
+                    status=403,
+                )
+            hint = (
+                "Traffic endpoints need a token with Administration: Read on this repository "
+                "(classic tokens: the repo scope and push or admin access)."
+                if is_traffic
+                else "Check that your token includes this repository and has Contents: Read "
+                "(classic tokens: the repo scope)."
+            )
+            raise GitHubAPIError(f"GitHub denied this request. {hint}{suffix}", status=403)
+        if not response.ok:
+            raise GitHubAPIError(
+                f"GitHub API returned HTTP {response.status_code}.{suffix}",
+                status=response.status_code,
+            )
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise GitHubAPIError("GitHub returned an invalid JSON response.") from exc
+
+    def _paginate(self, path: str, params: dict[str, Any]) -> list[dict[str, Any]]:
+        items: list[dict[str, Any]] = []
+        page = 1
+        while True:
+            batch = self.get(path, params={**params, "per_page": 100, "page": page})
+            if not isinstance(batch, list) or not batch:
+                break
+            items.extend(batch)
+            if len(batch) < 100:
+                break
+            page += 1
+        return items
+
+    def list_repositories(self) -> list[dict[str, Any]]:
+        return self._paginate(
+            "/user/repos",
+            {"sort": "updated", "affiliation": "owner,collaborator,organization_member"},
+        )
+
+    def owner_profile(self, owner: str) -> dict[str, Any]:
+        """Return the organization or user profile for OWNER."""
+        result = self.get(f"/users/{owner}")
+        return result if isinstance(result, dict) else {}
+
+    def list_owner_repositories(self, owner: str) -> list[dict[str, Any]]:
+        """List every repository owned by an organization or user that the token can see."""
+        try:
+            return self._paginate(f"/orgs/{owner}/repos", {"type": "all", "sort": "pushed"})
+        except GitHubAPIError as exc:
+            if exc.status != 404:
+                raise
+        # Not an organization. For the authenticated user, /user/repos includes private repos.
+        me = self.get("/user")
+        if isinstance(me, dict) and str(me.get("login", "")).lower() == owner.lower():
+            repos = self._paginate("/user/repos", {"affiliation": "owner", "sort": "pushed"})
+            return [r for r in repos if r.get("owner", {}).get("login", "").lower() == owner.lower()]
+        return self._paginate(f"/users/{owner}/repos", {"type": "owner", "sort": "pushed"})
+
+    def traffic(self, owner: str, repo: str, metric: str) -> dict[str, Any]:
+        if metric not in {"views", "clones", "popular/paths", "referrers"}:
+            raise ValueError(f"Unsupported traffic metric: {metric}")
+        # GitHub serves referrers under traffic/popular/referrers.
+        path = "popular/referrers" if metric == "referrers" else metric
+        result = self.get(f"/repos/{owner}/{repo}/traffic/{path}")
+        if isinstance(result, list):
+            key = "popular/paths" if metric == "popular/paths" else "referrers"
+            return {key: result}
+        return result if isinstance(result, dict) else {}
+
+    def release_downloads(self, owner: str, repo: str) -> tuple[int, list[dict[str, Any]]]:
+        """Return the number of releases and a row per uploaded release asset."""
+        releases = self.get(f"/repos/{owner}/{repo}/releases", params={"per_page": 100})
+        if not isinstance(releases, list):
+            releases = []
+        results: list[dict[str, Any]] = []
+        for release in releases:
+            for asset in release.get("assets", []):
+                results.append(
+                    {
+                        "release": release.get("tag_name", ""),
+                        "name": asset.get("name", ""),
+                        "download_count": asset.get("download_count", 0),
+                        "created_at": asset.get("created_at", ""),
+                    }
+                )
+        return len(releases), results