gslides-automator 0.4.0__py3-none-any.whl

gslides_automator/__init__.py

@@ -0,0 +1,43 @@
+"""
+Package exports for gslides_automator.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from gslides_automator.auth import load_credentials
+from gslides_automator.generate_data import generate_data as _gd
+from gslides_automator.generate_report import generate_report as _gr
+from gslides_automator.drive_layout import DriveLayout, resolve_layout
+
+
+def generate_data(
+    shared_drive_url: str,
+    service_account_credentials: str,
+) -> dict:
+    """Populate L1-Data from L0-Data using the shared-drive layout."""
+    creds = load_credentials(service_account_credentials)
+    layout: DriveLayout = resolve_layout(shared_drive_url, creds)
+
+    return _gd.generate_data(
+        creds=creds,
+        layout=layout,
+    )
+
+
+def generate_report(
+    shared_drive_url: str,
+    service_account_credentials: str,
+) -> dict:
+    """Build Google Slides reports from L1-Data for entities marked with generate=Y."""
+    creds = load_credentials(service_account_credentials)
+    layout: DriveLayout = resolve_layout(shared_drive_url, creds)
+
+    return _gr.generate_report(
+        creds=creds,
+        input_folder_id=layout.l1_data_id,
+        template_id=layout.report_template_id,
+        output_folder_id=layout.l2_report_id,
+        layout=layout,
+    )

gslides_automator/__main__.py

@@ -0,0 +1,7 @@
+"""Module entrypoint for `python -m gslides_automator`."""
+
+from .cli import main
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

gslides_automator/auth.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Shared authentication module for Google API access.
+Provides service account credential management for Google Sheets, Drive, and Slides APIs.
+"""
+
+from google.oauth2 import service_account
+import os
+
+# Combined scopes required by all scripts
+SCOPES = [
+    'https://www.googleapis.com/auth/spreadsheets',  # Full access (covers readonly)
+    'https://www.googleapis.com/auth/drive.readonly',  # For reading/copying templates
+    'https://www.googleapis.com/auth/drive.file',  # For creating and moving files
+    'https://www.googleapis.com/auth/drive',  # Full Drive access for modifying file permissions
+    'https://www.googleapis.com/auth/presentations'  # For modifying slides
+]
+
+# Get the project root directory
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SERVICE_ACCOUNT_CREDENTIALS = os.path.join(PROJECT_ROOT, 'service-account-credentials.json')
+
+
+def get_oauth_credentials(service_account_credentials: str | None = None, scopes=None):
+    """
+    Get service account credentials using a JSON key file. Defaults to service-account-credentials.json in repo root.
+
+    Args:
+        service_account_credentials: Optional path to a service account key JSON.
+        scopes: Optional list of scopes to request.
+
+    Returns:
+        google.oauth2.service_account.Credentials: Service account credentials object
+
+    Raises:
+        FileNotFoundError: If the credentials file is not found
+    """
+    key_path = service_account_credentials or SERVICE_ACCOUNT_CREDENTIALS
+    if not os.path.exists(key_path):
+        raise FileNotFoundError(
+            f"Service account credentials file '{key_path}' not found. "
+            "Please download service account credentials from Google Cloud Console."
+        )
+
+    requested_scopes = scopes or SCOPES
+
+    creds = service_account.Credentials.from_service_account_file(
+        key_path,
+        scopes=requested_scopes
+    )
+
+    return creds
+
+
+def load_credentials(service_account_credentials: str):
+    """
+    Load service-account credentials from a provided path.
+
+    Args:
+        service_account_credentials: Path to the service account JSON key file.
+
+    Returns:
+        google.oauth2.service_account.Credentials: Service account credentials object
+
+    Raises:
+        ValueError: If service_account_credentials is empty
+        FileNotFoundError: If the credentials file is not found
+    """
+    if not service_account_credentials:
+        raise ValueError("service_account_credentials is required.")
+    if not os.path.exists(service_account_credentials):
+        raise FileNotFoundError(f"Credentials file not found: {service_account_credentials}")
+    return get_oauth_credentials(service_account_credentials=service_account_credentials, scopes=SCOPES)
+
+
+def get_service_account_email():
+    """
+    Get the service account email from the credentials file.
+    Useful for sharing files/folders with the service account.
+
+    Returns:
+        str: Service account email address
+
+    Raises:
+        FileNotFoundError: If service-account-credentials.json is not found
+        KeyError: If email is not found in the credentials file
+    """
+    import json
+
+    if not os.path.exists(SERVICE_ACCOUNT_CREDENTIALS):
+        raise FileNotFoundError(
+            f"Service account credentials file '{SERVICE_ACCOUNT_CREDENTIALS}' not found."
+        )
+
+    with open(SERVICE_ACCOUNT_CREDENTIALS, 'r') as f:
+        creds_data = json.load(f)
+
+    email = creds_data.get('client_email')
+    if not email:
+        raise KeyError("'client_email' not found in service account credentials file")
+
+    return email
+

gslides_automator/cli.py

@@ -0,0 +1,96 @@
+"""Command-line interface for gslides_automator."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Callable
+
+
+def _run_generate_data(args: argparse.Namespace) -> int:
+    """Entrypoint for the `generate-data` subcommand."""
+    from .generate_data import generate_data, get_oauth_credentials, resolve_layout
+
+    creds = get_oauth_credentials(service_account_credentials=args.service_account_credentials)
+    layout = resolve_layout(args.shared_drive_url, creds)
+    generate_data(
+        creds=creds,
+        layout=layout,
+    )
+    return 0
+
+
+def _run_generate_report(args: argparse.Namespace) -> int:
+    """Entrypoint for the `generate-report` subcommand."""
+    from .generate_report import generate_report, get_oauth_credentials, resolve_layout
+
+    creds = get_oauth_credentials(service_account_credentials=args.service_account_credentials)
+    layout = resolve_layout(args.shared_drive_url, creds)
+    generate_report(
+        creds=creds,
+        layout=layout,
+    )
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gslides_automator",
+        description="Utilities for generating data and reports from Google Drive and Sheets.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    gen_parser = subparsers.add_parser(
+        "generate-data",
+        help="Generate L1 data from the shared drive layout.",
+    )
+    gen_parser.add_argument(
+        "--shared-drive-url",
+        required=True,
+        help="Shared Drive root URL or ID that contains L0/L1 data and templates.",
+    )
+    gen_parser.add_argument(
+        "--service-account-credentials",
+        default=None,
+        help="Path to the service account JSON key file. Defaults to service-account-credentials.json in the project root.",
+    )
+    gen_parser.set_defaults(func=_run_generate_data)
+
+    report_parser = subparsers.add_parser(
+        "generate-report",
+        help="Generate Google Slides reports from L1 data.",
+    )
+    report_parser.add_argument(
+        "--shared-drive-file",
+        required=True,
+        help="Shared Drive root URL or ID that contains L1/L2 data, templates, and entities.",
+    )
+    report_parser.add_argument(
+        "--credentials",
+        dest="credentials",
+        default=None,
+        help="Path to the service account JSON key file. Defaults to service-account-credentials.json in the project root.",
+    )
+    report_parser.set_defaults(func=_run_generate_report)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    handler: Callable[[argparse.Namespace], int] | None = getattr(args, "func", None)
+    if handler is None:
+        parser.print_help()
+        return 1
+
+    try:
+        return handler(args)
+    except Exception as exc:  # pragma: no cover - CLI guardrail
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

gslides_automator/drive_layout.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import csv
+import io
+import re
+from typing import Dict, Iterable, List, Optional, Sequence, Set
+
+from googleapiclient.discovery import build
+from googleapiclient.http import MediaIoBaseDownload
+
+
+@dataclass
+class DriveLayout:
+    root_id: str
+    l0_data_id: str
+    l1_data_id: str
+    l2_report_id: str
+    templates_id: str
+    data_template_id: str
+    report_template_id: str
+    entities_csv_id: str
+
+
+def _extract_id_from_url(shared_drive_url: str) -> str:
+    """
+    Extract a Drive folder/file ID from a shared Drive URL or raw ID.
+    """
+    if re.fullmatch(r"[A-Za-z0-9_\-]+", shared_drive_url):
+        return shared_drive_url
+
+    patterns = [
+        r"/folders/([A-Za-z0-9_\-]+)",
+        r"[?&]id=([A-Za-z0-9_\-]+)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, shared_drive_url)
+        if match:
+            return match.group(1)
+    raise ValueError("Could not extract Drive folder ID from URL. Pass a folder link or ID.")
+
+
+def _find_child_by_name(
+    drive_service,
+    parent_id: str,
+    names: str | Sequence[str],
+    mime_type: str | None = None,
+) -> str:
+    """
+    Locate a child by exact name (supports multiple candidate names).
+    """
+    candidates: Iterable[str] = [names] if isinstance(names, str) else names
+    mime_clause = f" and mimeType='{mime_type}'" if mime_type else ""
+
+    for name in candidates:
+        query = f"'{parent_id}' in parents and name='{name}' and trashed=false{mime_clause}"
+        result = drive_service.files().list(
+            q=query,
+            fields="files(id,name,mimeType)",
+            supportsAllDrives=True,
+            includeItemsFromAllDrives=True,
+            pageSize=5,
+        ).execute()
+        files = result.get("files", [])
+        if files:
+            return files[0]["id"]
+
+    raise FileNotFoundError(
+        f"Could not find any of {list(candidates)} inside parent id {parent_id}"
+    )
+
+
+def resolve_layout(shared_drive_url: str, creds) -> DriveLayout:
+    """
+    Discover the standard folder/file layout starting from the shared drive URL.
+    """
+    drive_service = build("drive", "v3", credentials=creds)
+    root_id = _extract_id_from_url(shared_drive_url)
+
+    l0_id = _find_child_by_name(drive_service, root_id, "L0-Data", mime_type="application/vnd.google-apps.folder")
+    l1_id = _find_child_by_name(drive_service, root_id, "L1-Data", mime_type="application/vnd.google-apps.folder")
+    l2_id = _find_child_by_name(drive_service, root_id, "L2-Reports", mime_type="application/vnd.google-apps.folder")
+    templates_id = _find_child_by_name(drive_service, root_id, "Templates", mime_type="application/vnd.google-apps.folder")
+
+    data_template_id = _find_child_by_name(
+        drive_service,
+        templates_id,
+        names=("data-template.gsheet", "data-template"),
+        mime_type="application/vnd.google-apps.spreadsheet",
+    )
+    report_template_id = _find_child_by_name(
+        drive_service,
+        templates_id,
+        names=("report-template.gslide", "report-template"),
+        mime_type="application/vnd.google-apps.presentation",
+    )
+    entities_csv_id = _find_child_by_name(
+        drive_service,
+        root_id,
+        names=("entities.csv", "entities"),
+        mime_type="text/csv",
+    )
+
+    return DriveLayout(
+        root_id=root_id,
+        l0_data_id=l0_id,
+        l1_data_id=l1_id,
+        l2_report_id=l2_id,
+        templates_id=templates_id,
+        data_template_id=data_template_id,
+        report_template_id=report_template_id,
+        entities_csv_id=entities_csv_id,
+    )
+
+
+def load_entities(entities_csv_id: str, creds) -> List[str]:
+    """
+    Download entities.csv and return entity names (first column) where the adjacent
+    `generate` column (second column) is exactly `Y`.
+    """
+    drive_service = build("drive", "v3", credentials=creds)
+    request = drive_service.files().get_media(fileId=entities_csv_id, supportsAllDrives=True)
+    buffer = io.BytesIO()
+    downloader = MediaIoBaseDownload(buffer, request)
+    done = False
+    while not done:
+        status, done = downloader.next_chunk()
+    buffer.seek(0)
+    content = buffer.read().decode("utf-8")
+
+    reader = csv.reader(io.StringIO(content))
+    entities: List[str] = []
+    for row in reader:
+        if not row:
+            continue
+
+        name = row[0].strip()
+        generate_flag = row[1].strip() if len(row) > 1 else ""
+
+        if not name:
+            continue
+
+        # Skip header row
+        if not entities and name.lower().startswith("entity"):
+            continue
+
+        # Only include rows explicitly marked for generation
+        if generate_flag == "Y":
+            entities.append(name)
+    return entities
+
+def _parse_slides_value(slides_value: str) -> Optional[Set[int]]:
+    """
+    Parse a slides column value into a set of slide numbers.
+
+    Accepts comma-separated numbers and ranges (e.g., "1,2-4,6").
+    Returns None when the value is blank or no valid numbers are found
+    to indicate that all slides should be processed.
+    """
+    if not slides_value:
+        return None
+
+    slides: Set[int] = set()
+    for part in slides_value.split(","):
+        part = part.strip()
+        if not part:
+            continue
+
+        if "-" in part:
+            bounds = part.split("-", 1)
+            if len(bounds) != 2:
+                continue
+            try:
+                start = int(bounds[0].strip())
+                end = int(bounds[1].strip())
+            except ValueError:
+                continue
+
+            if start > end:
+                start, end = end, start
+
+            for num in range(start, end + 1):
+                if num > 0:
+                    slides.add(num)
+        else:
+            try:
+                value = int(part)
+            except ValueError:
+                continue
+            if value > 0:
+                slides.add(value)
+
+    return slides or None
+
+
+def load_entities_with_slides(entities_csv_id: str, creds) -> Dict[str, Optional[Set[int]]]:
+    """
+    Download entities.csv and return a mapping of entity name to requested slide
+    numbers for rows marked with generate=Y. A value of None means all slides.
+    """
+    drive_service = build("drive", "v3", credentials=creds)
+    request = drive_service.files().get_media(fileId=entities_csv_id, supportsAllDrives=True)
+    buffer = io.BytesIO()
+    downloader = MediaIoBaseDownload(buffer, request)
+    done = False
+    while not done:
+        status, done = downloader.next_chunk()
+    buffer.seek(0)
+    content = buffer.read().decode("utf-8")
+
+    reader = csv.reader(io.StringIO(content))
+    entities: Dict[str, Optional[Set[int]]] = {}
+    for row in reader:
+        if not row:
+            continue
+
+        name = row[0].strip()
+        generate_flag = row[1].strip() if len(row) > 1 else ""
+        slides_value = row[2].strip() if len(row) > 2 else ""
+
+        if not name:
+            continue
+
+        # Skip header row
+        if not entities and name.lower().startswith("entity"):
+            continue
+
+        if generate_flag == "Y":
+            slides = _parse_slides_value(slides_value)
+            entities[name] = slides
+
+    return entities
+