gitlytics 0.1.2__tar.gz → 0.1.3__tar.gz

{gitlytics-0.1.2 → gitlytics-0.1.3}/PKG-INFO

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: gitlytics
-Version: 0.1.2
+Version: 0.1.3
 Summary: Monitor and automate your GitHub repository traffic analytics.
 Author: Ameya Chopade
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/ameyac11/gitlytics
+Project-URL: Repository, https://github.com/ameyac11/gitlytics
+Project-URL: Bug Tracker, https://github.com/ameyac11/gitlytics/issues
 Keywords: github,traffic,analytics,automation,cli
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -12,17 +14,20 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests
-Requires-Dist: pandas
-Requires-Dist: python-dotenv
-Requires-Dist: croniter
+Requires-Dist: requests>=2.32.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: croniter>=2.0.0
 Provides-Extra: dashboard
-Requires-Dist: fastapi; extra == "dashboard"
-Requires-Dist: uvicorn; extra == "dashboard"
-Requires-Dist: python-multipart; extra == "dashboard"
+Requires-Dist: fastapi>=0.111.0; extra == "dashboard"
+Requires-Dist: uvicorn>=0.30.0; extra == "dashboard"
+Requires-Dist: python-multipart>=0.0.9; extra == "dashboard"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: Faker>=20.0.0; extra == "dev"
+Requires-Dist: anyio[trio]>=4.0.0; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
@@ -159,7 +164,7 @@ import gitlytics
 # Fetch traffic for all repositories accessible by the token
 df = gitlytics.fetch_traffic(
     token="ghp_your_token",
-    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (React Chart-ready dict), or "raw" (JSON API payload)
+    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (chart-ready dict), or "summary" (per-repo totals dict)
 )
 
 # Fetch traffic for a single specific repository and print the table to stdout
@@ -183,7 +188,7 @@ gitlytics.fetch_traffic(
 | `token` | `str` | *Required* | GitHub Personal Access Token with `repo` scope enabled. |
 | `repo_name` | `str` | `None` | Specific repository name (e.g. `"user/repo"`). If `None`, fetches all repositories. |
 | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
-| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"`, or `"raw"`. |
+| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
 | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
 
 ---

{gitlytics-0.1.2 → gitlytics-0.1.3}/README.md

@@ -132,7 +132,7 @@ import gitlytics
 # Fetch traffic for all repositories accessible by the token
 df = gitlytics.fetch_traffic(
     token="ghp_your_token",
-    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (React Chart-ready dict), or "raw" (JSON API payload)
+    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (chart-ready dict), or "summary" (per-repo totals dict)
 )
 
 # Fetch traffic for a single specific repository and print the table to stdout
@@ -156,7 +156,7 @@ gitlytics.fetch_traffic(
 | `token` | `str` | *Required* | GitHub Personal Access Token with `repo` scope enabled. |
 | `repo_name` | `str` | `None` | Specific repository name (e.g. `"user/repo"`). If `None`, fetches all repositories. |
 | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
-| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"`, or `"raw"`. |
+| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
 | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
 
 ---

gitlytics-0.1.3/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gitlytics"
+version = "0.1.3"
+description = "Monitor and automate your GitHub repository traffic analytics."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Ameya Chopade" }
+]
+# Fix #20: Add version lower-bounds to prevent silent breakage on old environments.
+# These match the constraints already documented in requirements.txt.
+dependencies = [
+    "requests>=2.32.0",
+    "pandas>=2.2.0",
+    "python-dotenv>=1.0.1",
+    "croniter>=2.0.0"
+]
+keywords = [
+    "github",
+    "traffic",
+    "analytics",
+    "automation",
+    "cli"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/ameyac11/gitlytics"
+Repository = "https://github.com/ameyac11/gitlytics"
+"Bug Tracker" = "https://github.com/ameyac11/gitlytics/issues"
+
+[project.optional-dependencies]
+# Fix #20: dashboard extras are optional — base package works without them.
+# requirements.txt was including them as mandatory; that was wrong.
+dashboard = [
+    "fastapi>=0.111.0",
+    "uvicorn>=0.30.0",
+    "python-multipart>=0.0.9"
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "httpx>=0.27.0",      # required by FastAPI TestClient (used in test_api.py)
+    "Faker>=20.0.0",      # used by pytest-faker plugin for generating test data
+    "anyio[trio]>=4.0.0"  # async test support
+]
+
+
+[project.scripts]
+gitlytics = "gitlytics.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gitlytics*"]
+
+[tool.setuptools.package-data]
+"gitlytics" = ["static/**/*", "static/*"]
+
+[tool.pytest.ini_options]
+# Only collect files that match the offline test naming convention.
+# live_*.py scripts are excluded — they need a real GitHub token.
+testpaths = ["tests"]
+python_files  = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

gitlytics-0.1.3/src/gitlytics/__init__.py

@@ -0,0 +1,140 @@
+"""
+gitlytics/__init__.py
+The public API for the gitlytics package.
+"""
+import os
+import logging
+import json
+
+# Single source of truth for the package version.
+# Mirrors the version in pyproject.toml — keep them in sync.
+__version__ = "0.1.3"
+
+# Import the internal building blocks — users never call these directly
+from .core import fetch_traffic_data, print_repo_table
+from .automation import run_sync
+from .process import build_json_payload
+
+# Set up a silent logger so gitlytics never messes with your app's logging
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_format: str = "dataframe", save_file: str = None):
+    """
+    Fetches the last 14 days of traffic data for one or all repositories.
+
+    Args:
+        token: GitHub Personal Access Token with `repo` scope.
+        repo_name: Specific repo name (e.g. ``"user/repo"``) or list of names.
+            If ``None``, fetches all repositories accessible by the token.
+        print_table: If ``True``, prints an ASCII summary table to stdout.
+        return_format: Shape of the returned data. One of:
+            ``"dataframe"`` (default) — returns a ``pandas.DataFrame``.
+            ``"timeseries"`` — returns a nested JSON-serialisable dict.
+            ``"summary"`` — returns a per-repo totals dict.
+        save_file: Optional path to save the output. Extension determines
+            format: ``.json`` writes JSON, anything else writes CSV.
+
+    Returns:
+        A ``pandas.DataFrame`` when ``return_format="dataframe"``, otherwise
+        a ``dict`` matching the requested format.
+    """
+    # Hit the GitHub API and get back a tidy DataFrame (one row per day per repo)
+    df = fetch_traffic_data(token, repo_name)
+
+    # Print the ASCII table to the console if the user asked for it
+    if print_table:
+        print_repo_table(df)
+
+    # --- dataframe mode: just return the raw DataFrame, optionally save it ---
+    if return_format == "dataframe":
+        if save_file:
+            if save_file.endswith(".json"):
+                # Save as a chart-ready JSON file
+                payload = build_json_payload(df, return_format="timeseries", export_public_only=True)
+                with open(save_file, "w", encoding="utf-8") as f:
+                    json.dump(payload, f, indent=2)
+            else:
+                # Save as a standard CSV file
+                df.to_csv(save_file, index=False)
+        return df
+
+    # Reject anything that isn't a known format before doing more work
+    valid_formats = {"timeseries", "summary"}
+    if return_format not in valid_formats:
+        raise ValueError(
+            f"Invalid return_format={return_format!r}. "
+            f"Choose one of: 'dataframe', 'timeseries', 'summary'."
+        )
+
+    # Build the JSON-serialisable payload in the requested shape
+    payload = build_json_payload(df, return_format=return_format, export_public_only=False)
+
+    # Save to disk if the user gave us a file path
+    if save_file:
+        with open(save_file, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+
+    return payload
+
+
+def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str = "monthly", schedule_cron: str = None, export_json: str = None, export_public_only: bool = True):
+    """
+    Fetches data and appends it to a local CSV database, optionally running as a permanent background daemon.
+
+    Args:
+        token: GitHub Personal Access Token.
+        repo_name: Specific repository name(s) to sync. If ``None``, syncs all.
+        data_dir: Directory where CSV files are stored.
+        output_mode: ``"monthly"`` (``traffic_YYYY-MM.csv``) or ``"yearly"`` (``traffic_YYYY.csv``).
+        schedule_cron: Standard cron expression (e.g. ``"0 23 * * *"``). If set,
+            runs an infinite scheduler loop.
+        export_json: Path to export the merged historical database as a JSON file.
+        export_public_only: If ``True`` (default), strips private repos from the
+            exported JSON — acts as a security firewall.
+    """
+    # Hand off to the automation engine — it handles deduplication and schema migration
+    run_sync(
+        token=token,
+        repo_names=repo_name,
+        data_dir=data_dir,
+        output_mode=output_mode,
+        schedule_cron=schedule_cron,
+        export_json=export_json,
+        export_public_only=export_public_only
+    )
+
+
+def serve_dashboard(host: str = "127.0.0.1", port: int = 8000, token: str = None, data_dir: str = None):
+    """
+    Starts the React + FastAPI dashboard server.
+
+    ``uvicorn`` and ``fastapi`` are optional dependencies installed via::
+
+        pip install "gitlytics[dashboard]"
+
+    Args:
+        host: Host IP to bind. Use ``"0.0.0.0"`` to listen on all interfaces.
+        port: Port number (default ``8000``).
+        token: Optional GitHub token — pre-authenticates the dashboard session.
+        data_dir: Optional path to the historical CSV database directory.
+    """
+    # Only import uvicorn when the user actually calls serve_dashboard,
+    # so the base `pip install gitlytics` doesn't crash without it
+    try:
+        import uvicorn
+    except ImportError:
+        raise ImportError(
+            "The dashboard requires additional dependencies. "
+            "Install them with: pip install \"gitlytics[dashboard]\""
+        )
+
+    # Pass the token and data folder to the FastAPI app via environment variables
+    if token:
+        os.environ["GITLYTICS_TOKEN"] = token
+    if data_dir:
+        os.environ["GITLYTICS_DATA_DIR"] = os.path.abspath(data_dir)
+
+    # Start the web server — it won't return until the user presses Ctrl+C
+    uvicorn.run("gitlytics.api:app", host=host, port=port, reload=False)

gitlytics-0.1.3/src/gitlytics/__main__.py

@@ -0,0 +1,9 @@
+"""
+gitlytics/__main__.py
+Makes `python -m gitlytics` work identically to the `gitlytics` console command.
+This is the entry point Python calls when the package is run with -m.
+"""
+from gitlytics.cli import main
+
+# Run the CLI when invoked as `python -m gitlytics`
+main()

gitlytics-0.1.3/src/gitlytics/api.py

@@ -0,0 +1,177 @@
+"""
+gitlytics/api.py
+Powers the FastAPI backend — serves traffic data and the React dashboard to the browser.
+"""
+import logging
+import os
+from pathlib import Path
+
+import pandas as pd
+from fastapi import FastAPI, HTTPException, Body, File, UploadFile
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from gitlytics.core import validate_token, get_user_profile, fetch_traffic_data
+from gitlytics.process import process_uploaded_csv, build_react_payload
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="GitHub Traffic API")
+
+# Only allow requests from localhost — this dashboard is never deployed publicly
+_ALLOWED_ORIGINS = [
+    "http://localhost",
+    "http://localhost:3000",
+    "http://localhost:5173",
+    "http://localhost:8000",
+    "http://127.0.0.1",
+    "http://127.0.0.1:3000",
+    "http://127.0.0.1:5173",
+    "http://127.0.0.1:8000",
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["GET", "POST"],
+    allow_headers=["Content-Type"],
+)
+
+
+def _get_token(token: str = None) -> str:
+    # Use the token from the request body, or fall back to the one set in the environment
+    return token or os.environ.get("GITLYTICS_TOKEN")
+
+
+@app.get("/api/config")
+def get_config():
+    # Lets the frontend know if it's running in headless/TV mode with a pre-set token
+    return {
+        "has_token": bool(os.environ.get("GITLYTICS_TOKEN")),
+        "has_data_dir": bool(os.environ.get("GITLYTICS_DATA_DIR"))
+    }
+
+
+@app.post("/api/auth")
+def auth(token: str = Body("", embed=True)):
+    # Validate the token and return the user's GitHub profile info
+    active_token = _get_token(token)
+    if not active_token:
+        raise HTTPException(status_code=401, detail="No token provided and no environment token found.")
+
+    ok, username = validate_token(active_token)
+    if not ok:
+        # Log a warning without echoing the token value into logs
+        logger.warning("Authentication attempt failed for a provided token.")
+        raise HTTPException(status_code=401, detail=username)
+
+    # Fetch the real display name and avatar URL — validate_token only gives us the login
+    profile = get_user_profile(active_token)
+
+    return {
+        "authenticated": True,
+        "username": profile["login"] or username,
+        "name": profile["name"] or username,        # Real display name, e.g. "Ameya Chopade"
+        "avatar_url": profile["avatar_url"],         # Real GitHub avatar URL
+    }
+
+
+@app.post("/api/traffic")
+def get_traffic(token: str = Body("", embed=True)):
+    # Serve traffic data — either from the historical CSV database or live from GitHub
+    active_token = _get_token(token)
+    if not active_token:
+        raise HTTPException(status_code=401, detail="No token provided")
+
+    ok, _ = validate_token(active_token)
+    if not ok:
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+    data_dir = os.environ.get("GITLYTICS_DATA_DIR")
+    if data_dir:
+        # Load from the historical CSV database (headless/TV mode)
+        data_dir_path = Path(data_dir)
+        csv_files = list(data_dir_path.glob("traffic_*.csv")) if data_dir_path.exists() else []
+        dfs = []
+        for f in csv_files:
+            try:
+                dfs.append(pd.read_csv(f))
+            except Exception as exc:
+                logger.warning(f"Skipping unreadable CSV '{f}': {exc}")
+        if dfs:
+            df = pd.concat(dfs, ignore_index=True)
+            # Clean up any duplicate day-repo rows that crept in somehow
+            df = df.drop_duplicates(subset=["date", "repository"], keep="last")
+        else:
+            # No CSVs found — fall through to a live fetch
+            df = fetch_traffic_data(active_token)
+    else:
+        # Default: hit GitHub and get the live 14-day window
+        df = fetch_traffic_data(active_token)
+
+    # Replace any infinity or NaN values before JSON serialisation
+    df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
+
+    # Transform the DataFrame into the array of objects the React app expects
+    payload = build_react_payload(df)
+    return payload
+
+
+@app.post("/api/upload-csv")
+def upload_csv(file: UploadFile = File(...)):
+    # Accept a user-uploaded CSV and convert it to the same format as the API response
+    try:
+        df = process_uploaded_csv(file.file)
+        df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
+        payload = build_react_payload(df)
+        return payload
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# ── Static file serving ───────────────────────────────────────────────────────
+# The React build output lands in gitlytics/static/ after `npm run build`
+frontend_dir = Path(__file__).parent / "static"
+
+
+@app.get("/")
+def serve_index():
+    # Serve the React app's index.html for the root URL
+    index_file = frontend_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+    return JSONResponse(
+        status_code=503,
+        content={"error": "Frontend not found. Run 'npm run build' in the frontend directory."}
+    )
+
+
+@app.get("/{full_path:path}")
+def serve_spa_fallback(full_path: str):
+    """
+    SPA catch-all — any URL that doesn't match an API route returns index.html
+    so React Router can handle client-side navigation on hard refresh.
+    Real static assets (JS/CSS) are served by the StaticFiles mount first.
+    """
+    # Serve the actual file if it exists (e.g. a JS or CSS asset)
+    asset_file = frontend_dir / full_path
+    if asset_file.exists() and asset_file.is_file():
+        return FileResponse(asset_file)
+
+    # For everything else (like /repos/my-repo), hand control to React Router
+    index_file = frontend_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+
+    return JSONResponse(
+        status_code=503,
+        content={"error": "Frontend not found. Run 'npm run build' in the frontend directory."}
+    )
+
+
+# Mount the /assets directory for compiled JS and CSS — must come after route definitions
+assets_dir = frontend_dir / "assets"
+if assets_dir.exists():
+    app.mount("/assets", StaticFiles(directory=assets_dir), name="assets")