ghinsight 0.2.0__py3-none-any.whl

ghinsight/__init__.py

@@ -0,0 +1,32 @@
+"""ghinsight (pronounced "gin-sight"): reusable tools for GitHub analysis.
+
+The core needs only httpx2 and typer:
+
+- :mod:`ghinsight.client`: GitHub REST/GraphQL client and token resolution;
+- :mod:`ghinsight.repos`: repositories of an organisation or user;
+- :mod:`ghinsight.activity`: a user's issue and pull request activity.
+
+:mod:`ghinsight.actions` (GitHub Actions usage and performance, with a
+dashboard) needs the ``actions`` extra: ``pip install 'ghinsight[actions]'``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import GitHubClient, GitHubError, resolve_token
+from .repos import RepoInfo, list_repos
+
+try:
+    __version__ = version("ghinsight")
+except PackageNotFoundError:  # pragma: no cover - running from a bare checkout
+    __version__ = "0+unknown"
+
+__all__ = [
+    "GitHubClient",
+    "GitHubError",
+    "RepoInfo",
+    "__version__",
+    "list_repos",
+    "resolve_token",
+]

ghinsight/actions/__init__.py

@@ -0,0 +1,41 @@
+"""GitHub Actions usage and performance analysis (the ``actions`` extra).
+
+A three-stage, functional pipeline:
+
+1. **fetch** (:mod:`ghinsight.actions.fetch`) — cache raw runs/jobs from GitHub.
+2. **dataset** (:mod:`ghinsight.actions.dataset`) — parse the cache into the
+   canonical tidy intermediate representation, :class:`ActionsDataset`.
+3. **analysis** — derive metric tables (:mod:`ghinsight.actions.metrics`),
+   insights (:mod:`ghinsight.actions.analysis`), and a report
+   (:mod:`ghinsight.actions.report`) — all pure projections of the dataset.
+"""
+
+from __future__ import annotations
+
+from .analysis import UsageSummary, summarize_usage
+from .config import AnalysisConfig, DateRange, load_config, parse_period
+from .csv_export import write_reports
+from .dataset import ActionsDataset
+from .domain import Job, Run, RunnerType, RuntimeOS, Visibility
+from .metrics import performance_table, usage_table
+from .report import build_dashboard, render_html
+
+__all__ = [
+    "ActionsDataset",
+    "AnalysisConfig",
+    "DateRange",
+    "Job",
+    "Run",
+    "RunnerType",
+    "RuntimeOS",
+    "UsageSummary",
+    "Visibility",
+    "build_dashboard",
+    "load_config",
+    "parse_period",
+    "performance_table",
+    "render_html",
+    "summarize_usage",
+    "usage_table",
+    "write_reports",
+]

ghinsight/actions/analysis.py

@@ -0,0 +1,201 @@
+"""Stage 3b — derived insights, as pure functions over the dataset.
+
+This module contains the *interpretation* layer: billed-equivalent minutes,
+plan-cap projections and monthly time-series. It produces plain DataFrames and
+an immutable :class:`UsageSummary`, with no plotting or HTML concerns, so it is
+the natural entry point for ad-hoc analysis (see the Python tutorial) as well as
+the data source for the dashboard.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import pandas as pd
+
+from .config import AnalysisConfig
+from .dataset import ActionsDataset
+from .metrics import usage_table
+
+__all__ = [
+    "UsageSummary",
+    "billed_equivalent_by_os",
+    "billing_monthly_usage",
+    "monthly_comparison",
+    "monthly_usage",
+    "summarize_usage",
+]
+
+MONTHS_PER_YEAR = 12
+
+
+def _multiplier_series(os_column: pd.Series, multipliers: Mapping[str, float]) -> pd.Series:
+    return os_column.astype(str).str.lower().map(multipliers).fillna(1.0)
+
+
+def billed_equivalent_by_os(
+    dataset: ActionsDataset, multipliers: Mapping[str, float]
+) -> pd.DataFrame:
+    """Per-OS usage with the configured billing multiplier applied.
+
+    Columns: ``Runtime OS``, ``Total minutes``, ``Multiplier``,
+    ``Billed equivalent minutes``.
+    """
+    table = usage_table(dataset, "runtime-os").copy()
+    if table.empty:
+        return pd.DataFrame(
+            columns=["Runtime OS", "Total minutes", "Multiplier", "Billed equivalent minutes"]
+        )
+    table["Multiplier"] = _multiplier_series(table["Runtime OS"], multipliers)
+    table["Billed equivalent minutes"] = table["Total minutes"] * table["Multiplier"]
+    return table
+
+
+def monthly_usage(
+    dataset: ActionsDataset, multipliers: Mapping[str, float]
+) -> pd.DataFrame:
+    """Hosted jobs augmented with ``adj_billed`` (billed-equivalent minutes).
+
+    This is the long-form basis for every monthly chart: one row per hosted job
+    with its month, OS, repo, conclusion and multiplier-adjusted minutes.
+    """
+    # Even an empty frame gets ``adj_billed``, so charts over an empty scope
+    # (e.g. private-only when every repository is public) still work.
+    frame = dataset.hosted_jobs_frame.copy()
+    frame["adj_billed"] = frame["billed_minutes"] * _multiplier_series(
+        frame["runtime_os"], multipliers
+    )
+    return frame
+
+
+def billing_monthly_usage(
+    billing_frame: pd.DataFrame, multipliers: Mapping[str, float]
+) -> pd.DataFrame:
+    """Billing-report Actions minutes augmented with ``adj_billed``.
+
+    ``billing_frame`` is :meth:`BillingUsage.actions_minutes_frame
+    <ghinsight.actions.billing.BillingUsage.actions_minutes_frame>`. The result
+    has the same ``month``/``runtime_os``/``adj_billed`` columns as
+    :func:`monthly_usage`, so the same monthly charts apply to it.
+    """
+    frame = billing_frame.copy()
+    frame["adj_billed"] = frame["minutes"].astype(float) * _multiplier_series(
+        frame["runtime_os"], multipliers
+    )
+    return frame
+
+
+def _monthly_all_and_private(
+    frame: pd.DataFrame, column: str
+) -> tuple[pd.Series, pd.Series]:
+    """Monthly sums of ``column`` over all repos and over non-public repos."""
+    if frame.empty:
+        empty = pd.Series(dtype=float)
+        return empty, empty
+    all_repos = frame.groupby("month")[column].sum()
+    private = frame[frame["visibility"] != "public"].groupby("month")[column].sum()
+    return all_repos, private.reindex(all_repos.index, fill_value=0.0)
+
+
+def monthly_comparison(
+    estimated: pd.DataFrame, billed: pd.DataFrame | None = None
+) -> pd.DataFrame:
+    """Monthly billed-equivalent minutes: estimates by scope, and as billed.
+
+    ``estimated`` is :func:`monthly_usage`; its private-only column drops public
+    repos and keeps private, internal and unknown ones. ``billed`` (optional)
+    is :func:`billing_monthly_usage`, taken as is: the billing report already
+    omits free public-repository usage. Billing columns are present only when
+    ``billed`` is given; months missing from one source are ``NaN``.
+    """
+    est_all, est_private = _monthly_all_and_private(estimated, "adj_billed")
+    columns = {"Estimated, all repos": est_all, "Estimated, private only": est_private}
+    if billed is not None:
+        columns |= {
+            "Billed (GitHub report)": billed.groupby("month")["adj_billed"].sum(),
+            "Actions net charge (USD)": billed.groupby("month")["net_amount"].sum(),
+        }
+    table = pd.DataFrame(columns).sort_index()
+    table.index.name = "Month"
+    return table.reset_index()
+
+
+@dataclass(frozen=True, slots=True)
+class UsageSummary:
+    """Headline usage figures for a period. All minutes are billed-equivalent
+    unless named ``raw``."""
+
+    org: str
+    period: str
+    period_label: str
+    raw_total_minutes: float
+    billed_equivalent_minutes: float
+    estimated_monthly_billed: float
+    estimated_daily_billed: float
+    plan_minutes: float | None
+    plan_pct: float | None
+    cap_reached: bool | None
+    estimated_unserved_billed: float
+
+    @property
+    def cap_status_text(self) -> str:
+        """Human-readable description of the plan-cap situation (HTML-safe)."""
+        if self.plan_minutes is None:
+            return ""
+        if self.cap_reached:
+            day_cap_hit = (
+                self.plan_minutes / self.estimated_daily_billed
+                if self.estimated_daily_billed
+                else 0.0
+            )
+            return (
+                f"cap hit around day <b>{day_cap_hit:.1f}</b> of an average month, "
+                f"leaving <b>{self.estimated_unserved_billed:,.0f}</b> "
+                "billed-equivalent minutes unmet"
+            )
+        return (
+            f"cap <b>not reached</b> in an average month "
+            f"(average usage is {self.plan_pct:.0f}% of the "
+            f"{self.plan_minutes:,.0f}-minute cap)"
+        )
+
+
+def summarize_usage(dataset: ActionsDataset, config: AnalysisConfig) -> UsageSummary:
+    """Compute headline KPIs from the dataset and config.
+
+    The selected period is treated as an annual window, so monthly demand is the
+    billed-equivalent total divided by twelve (this matches the original report).
+    """
+    by_os = billed_equivalent_by_os(dataset, config.os_multipliers)
+    raw_total = float(by_os["Total minutes"].sum()) if not by_os.empty else 0.0
+    billed_total = (
+        float(by_os["Billed equivalent minutes"].sum()) if not by_os.empty else 0.0
+    )
+
+    est_monthly = billed_total / MONTHS_PER_YEAR
+    est_daily = est_monthly / config.days_per_month if config.days_per_month else 0.0
+
+    plan = config.plan_minutes
+    plan_pct: float | None = None
+    cap_reached: bool | None = None
+    unserved = 0.0
+    if plan:
+        plan_pct = est_monthly / plan * 100
+        cap_reached = est_monthly > plan
+        if cap_reached:
+            unserved = est_monthly - plan
+
+    return UsageSummary(
+        org=config.org,
+        period=config.period,
+        period_label=config.period_label,
+        raw_total_minutes=raw_total,
+        billed_equivalent_minutes=billed_total,
+        estimated_monthly_billed=est_monthly,
+        estimated_daily_billed=est_daily,
+        plan_minutes=plan,
+        plan_pct=plan_pct,
+        cap_reached=cap_reached,
+        estimated_unserved_billed=unserved,
+    )

ghinsight/actions/billing.py

@@ -0,0 +1,195 @@
+"""GitHub's billing usage report, as an optional companion to the dataset.
+
+The :class:`~ghinsight.actions.dataset.ActionsDataset` *estimates* billed minutes
+from job timestamps. When the account's billing usage report has been cached
+(see :func:`ghinsight.actions.fetch.fetch_billing_usage`), :class:`BillingUsage`
+provides the minutes GitHub actually billed, per day, repository and SKU.
+
+The report is optional. :meth:`BillingUsage.from_cache` returns ``None`` when
+nothing was cached, and every consumer must treat that as "use the estimates
+only". There are two ways to cache it:
+
+* :func:`ghinsight.actions.fetch.fetch_billing_usage`, via the REST API, which
+  appears to admit organisation owners only (billing managers get a 404); or
+* :func:`import_usage_csv`, from the usage report CSV that billing managers can
+  download from the organisation's billing pages (the *summarized* report
+  covers up to a year and has the per-repository breakdown needed here).
+
+The report appears to list only usage that counted towards the plan quota:
+public-repository usage on standard runners, which is free, is omitted. So the
+billed minutes are used as they are, with no visibility filter, and they
+reflect each repository's visibility at the time of use.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from datetime import timezone
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from .config import DateRange
+from .domain import BillingUsageItem, Visibility
+from .fetch import CachePaths, billing_months
+
+__all__ = ["BillingUsage", "BILLING_COLUMNS", "CSV_TO_API_FIELDS", "import_usage_csv"]
+
+BILLING_COLUMNS: tuple[str, ...] = (
+    "date",
+    "month",
+    "repo",
+    "visibility",
+    "sku",
+    "runtime_os",
+    "minutes",
+    "gross_amount",
+    "discount_amount",
+    "net_amount",
+)
+
+
+def _item_to_row(item: BillingUsageItem, visibility: Visibility) -> dict[str, Any]:
+    return {
+        "date": item.date,
+        "month": item.month,
+        "repo": item.repo,
+        "visibility": visibility.value,
+        "sku": item.sku,
+        "runtime_os": item.runtime_os.value,
+        "minutes": item.quantity,
+        "gross_amount": item.gross_amount,
+        "discount_amount": item.discount_amount,
+        "net_amount": item.net_amount,
+    }
+
+
+def _in_range(item: BillingUsageItem, date_range: DateRange) -> bool:
+    if item.date is None:
+        return False
+    date = item.date if item.date.tzinfo else item.date.replace(tzinfo=timezone.utc)
+    since, until = (
+        d if d.tzinfo else d.replace(tzinfo=timezone.utc)
+        for d in (date_range.since, date_range.until)
+    )
+    return since <= date < until
+
+
+@dataclass(frozen=True)
+class BillingUsage:
+    """Cached billing usage items for one account, plus the months they cover."""
+
+    org: str
+    items: tuple[BillingUsageItem, ...]
+    months: tuple[str, ...]
+    expected_months: tuple[str, ...] = ()
+
+    @classmethod
+    def from_cache(
+        cls, org: str, cache_dir: Path, date_range: DateRange | None = None
+    ) -> "BillingUsage | None":
+        """Load the cached report, or ``None`` if no month was cached.
+
+        With ``date_range``, only the months and items inside it are kept and
+        :attr:`expected_months` lists every month the range covers.
+        """
+        paths = CachePaths(cache_dir, org)
+        expected = tuple(billing_months(date_range)) if date_range else ()
+        files = sorted(paths.billing_dir.glob("*.json")) if paths.billing_dir.exists() else []
+        if expected:
+            files = [f for f in files if f.stem in expected]
+        loaded = dict(_load_months(files))
+        if not loaded:
+            return None
+        items = tuple(item for month_items in loaded.values() for item in month_items)
+        if date_range is not None:
+            items = tuple(item for item in items if _in_range(item, date_range))
+        return cls(org=org, items=items, months=tuple(sorted(loaded)), expected_months=expected)
+
+    @property
+    def missing_months(self) -> tuple[str, ...]:
+        """Months in the requested range with no cached report."""
+        return tuple(m for m in self.expected_months if m not in self.months)
+
+    def actions_minutes_frame(self, visibility: Mapping[str, Visibility]) -> pd.DataFrame:
+        """One row per Actions-minutes usage item, tagged with repo visibility."""
+        rows = [
+            _item_to_row(item, visibility.get(item.repo, Visibility.UNKNOWN))
+            for item in self.items
+            if item.is_actions_minutes
+        ]
+        if not rows:
+            return pd.DataFrame(columns=BILLING_COLUMNS)
+        return pd.DataFrame.from_records(rows, columns=BILLING_COLUMNS)
+
+
+def _load_months(files: Iterable[Path]) -> Iterable[tuple[str, list[BillingUsageItem]]]:
+    for path in files:
+        try:
+            payloads = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(payloads, list):
+            continue
+        items = [BillingUsageItem.from_payload(p) for p in payloads if isinstance(p, dict)]
+        yield path.stem, [item for item in items if item is not None]
+
+
+# Usage-report CSV columns and the REST API ``usageItems`` fields they map to.
+CSV_TO_API_FIELDS: Mapping[str, str] = {
+    "date": "date",
+    "product": "product",
+    "sku": "sku",
+    "quantity": "quantity",
+    "unit_type": "unitType",
+    "applied_cost_per_quantity": "pricePerUnit",
+    "gross_amount": "grossAmount",
+    "discount_amount": "discountAmount",
+    "net_amount": "netAmount",
+    "organization": "organizationName",
+    "repository": "repositoryName",
+}
+
+
+def _csv_row_to_item(row: Mapping[str, str]) -> dict[str, Any]:
+    item: dict[str, Any] = {
+        api: row[column] for column, api in CSV_TO_API_FIELDS.items() if column in row
+    }
+    for key in ("quantity", "pricePerUnit", "grossAmount", "discountAmount", "netAmount"):
+        if key in item:
+            try:
+                item[key] = float(item[key])
+            except ValueError:
+                item[key] = 0.0
+    return item
+
+
+def import_usage_csv(csv_path: Path, org: str, cache_dir: Path) -> list[str]:
+    """Cache a billing usage report CSV as if it had been fetched from the API.
+
+    Rows are converted to the API's ``usageItems`` shape and written one file
+    per month under ``{cache_dir}/_billing/{org}/``, replacing any cached
+    month the CSV covers. Rows for other organisations are skipped. A month
+    the CSV only partly covers is cached as partial, so export whole months.
+
+    Returns the months written.
+    """
+    by_month: dict[str, list[dict[str, Any]]] = {}
+    # ``utf-8-sig`` drops the byte-order mark GitHub puts before the header.
+    with csv_path.open(newline="", encoding="utf-8-sig") as handle:
+        for row in csv.DictReader(handle):
+            if row.get("organization", org).lower() != org.lower():
+                continue
+            month = (row.get("date") or "")[:7]
+            if len(month) == 7:
+                by_month.setdefault(month, []).append(_csv_row_to_item(row))
+
+    paths = CachePaths(cache_dir, org)
+    paths.billing_dir.mkdir(parents=True, exist_ok=True)
+    for month, items in by_month.items():
+        paths.billing_file(month).write_text(json.dumps(items), encoding="utf-8")
+    return sorted(by_month)