q2google 0.0.1__py3-none-any.whl

q2google/__init__.py

@@ -0,0 +1,23 @@
+"""Public package API for q2google.
+
+Exports the main orchestrator (``GoProToPhotosSync``), Google Photos façade types, session
+persistence protocols, and settings helpers.
+"""
+
+from q2google.config import Q2GoogleSettings, get_settings
+from q2google.gphotos.auth import GooglePhotosOAuth
+from q2google.photos import GooglePhotosClient
+from q2google.state.base import SessionState, SyncStateBackend
+from q2google.state.local import JsonFileBackend
+from q2google.sync import GoProToPhotosSync
+
+__all__ = [
+    "GoProToPhotosSync",
+    "GooglePhotosClient",
+    "GooglePhotosOAuth",
+    "JsonFileBackend",
+    "Q2GoogleSettings",
+    "SessionState",
+    "SyncStateBackend",
+    "get_settings",
+]

q2google/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for ``python -m q2google``.
+
+Delegates to the Typer application defined in :mod:`q2google.cli`.
+"""
+
+from q2google.cli import app
+
+if __name__ == "__main__":
+    app()

q2google/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package for q2google; exposes the Typer application entry point."""
+
+from q2google.cli._app import app
+
+__all__ = ["app"]

q2google/cli/_app.py

@@ -0,0 +1,215 @@
+"""Typer application and CLI command definitions for q2google."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from q2google.cli._logging import _configure_cli_logging
+from q2google.cli._printer import OutputFormat, SyncPrinter
+from q2google.cli._runner import _run_sync
+from q2google.config import get_settings
+from q2google.state.local import JsonFileBackend
+
+app = typer.Typer(
+    help="q2google — sync GoPro cloud media to Google Photos.",
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+)
+
+_err_console = Console(stderr=True, soft_wrap=True)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        version = importlib.metadata.version("q2google")
+        typer.echo(version)
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """q2google — sync GoPro cloud media to Google Photos."""
+
+
+def _parse_iso_datetime(value: str) -> datetime:
+    """Parse an ISO 8601 calendar date or datetime string.
+
+    Args:
+        value: String accepted by :meth:`datetime.datetime.fromisoformat`.
+
+    Returns:
+        Parsed timezone-naive or aware datetime.
+
+    Raises:
+        typer.Exit: Printed to stderr and exits with code 1 when ``value`` is invalid.
+    """
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        _err_console.print(f"[bold red]Error:[/bold red] Invalid ISO date/datetime: {value!r}")
+        raise typer.Exit(code=1)
+
+
+@app.command("sync")
+def sync_command(
+    start_date: str = typer.Option(
+        ...,
+        "--start",
+        help="Capture window start (ISO date or datetime, e.g. 2026-01-08).",
+    ),
+    end_date: str = typer.Option(
+        ...,
+        "--end",
+        help="Capture window end (ISO date or datetime, e.g. 2026-01-09).",
+    ),
+    credentials: Path | None = typer.Option(
+        None,
+        "--credentials",
+        help="Google OAuth client secrets JSON; default from [cyan]Q2GOOGLE_CREDENTIALS_PATH[/cyan] / settings.",
+    ),
+    token: Path | None = typer.Option(
+        None,
+        "--token",
+        help="Authorized user token path; default from [cyan]Q2GOOGLE_TOKEN_PATH[/cyan] / settings.",
+    ),
+    state_dir: Path | None = typer.Option(
+        None,
+        "--state-dir",
+        help="JSON session root; default from [cyan]Q2GOOGLE_STATE_DIR[/cyan] / settings.",
+    ),
+    session_id: str | None = typer.Option(
+        None,
+        "--session-id",
+        help="Resume id; default [cyan]Q2GOOGLE_SESSION_ID[/cyan] / settings, else a new UUID.",
+    ),
+    chunk_multiplier: int | None = typer.Option(
+        None,
+        "--chunk-multiplier",
+        help="Resumable upload chunk multiplier; default from settings.",
+    ),
+    max_items: int | None = typer.Option(
+        None,
+        "--max-items",
+        help="GoPro list_media_items cap; default from settings.",
+    ),
+    prefer_height: int | None = typer.Option(
+        None,
+        "--prefer-height",
+        help="Preferred GoPro download height; default from settings.",
+    ),
+    batch_size: int | None = typer.Option(
+        None,
+        "--batch-size",
+        help="Transfer batch size for new sessions; default from settings.",
+    ),
+    fail_fast: bool | None = typer.Option(
+        None,
+        "--fail-fast/--no-fail-fast",
+        help="Fail-fast mode; default from [cyan]Q2GOOGLE_FAIL_FAST[/cyan] / settings.",
+    ),
+    log_level: str | None = typer.Option(
+        None,
+        "--log-level",
+        help="Logging level (overrides quiet default); e.g. [bold]DEBUG[/bold], [bold]INFO[/bold].",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Log q2google at INFO (libraries stay quieter unless [bold]--log-level DEBUG[/bold]).",
+    ),
+    output: OutputFormat = typer.Option(
+        OutputFormat.rich,
+        "--output",
+        "-o",
+        help="Output format: [bold]rich[/bold] (default), [bold]tsv[/bold], or [bold]json[/bold].",
+    ),
+) -> None:
+    """Run discovery, transfer, and create stages for the given capture window.
+
+    Merges Typer options with :func:`~q2google.config.get_settings`, starts logging, resolves the
+    session id, and executes :func:`~q2google.cli._runner._run_sync` via :func:`asyncio.run`.
+
+    Args:
+        start_date: ISO start of the GoPro capture window (required).
+        end_date: ISO end of the GoPro capture window (required).
+        credentials: OAuth secrets path; defaults from settings when omitted.
+        token: User token path; defaults from settings when omitted.
+        state_dir: Session JSON directory; defaults from settings when omitted.
+        session_id: Explicit resume id; otherwise settings or a new UUID.
+        chunk_multiplier: Upload chunk multiplier; defaults from settings when omitted.
+        max_items: GoPro listing cap; defaults from settings when omitted.
+        prefer_height: Preferred asset height; defaults from settings when omitted.
+        batch_size: New-session transfer batch size; defaults from settings when omitted.
+        fail_fast: Overrides settings when ``True`` or ``False``; ``None`` uses settings.
+        log_level: Explicit logging level; when omitted the CLI defaults to quiet (WARNING).
+        verbose: When True and ``log_level`` is omitted, sets INFO for ``q2google`` loggers.
+        output: Output format selector; ``rich`` (default), ``tsv``, or ``json``.
+    """
+    try:
+        cfg = get_settings()
+        _configure_cli_logging(explicit_level=log_level, verbose=verbose)
+
+        start = _parse_iso_datetime(start_date)
+        end = _parse_iso_datetime(end_date)
+
+        sid = session_id or cfg.session_id or str(uuid.uuid4())
+        resolved_state_dir = state_dir if state_dir is not None else cfg.state_dir
+
+        state_backend = JsonFileBackend(resolved_state_dir)
+        existing_session = state_backend.load(sid)
+
+        printer = SyncPrinter(fmt=output)
+        printer.print_session_start(sid, existing_session, start=start, end=end)
+
+        t0 = time.perf_counter()
+        responses, transfer_metrics = asyncio.run(
+            _run_sync(
+                cfg=cfg,
+                start=start,
+                end=end,
+                credentials=credentials if credentials is not None else cfg.credentials_path,
+                token=token if token is not None else cfg.token_path,
+                state_dir=resolved_state_dir,
+                session_id=sid,
+                chunk_multiplier=(
+                    chunk_multiplier if chunk_multiplier is not None else cfg.chunk_granularity_multiplier
+                ),
+                max_items=max_items if max_items is not None else cfg.gopro_max_items,
+                prefer_height=prefer_height if prefer_height is not None else cfg.gopro_prefer_height,
+                batch_size=batch_size,
+                fail_fast=fail_fast,
+                printer=printer,
+            )
+        )
+        elapsed = time.perf_counter() - t0
+
+        final_state = state_backend.load(sid)
+        if final_state is None:
+            printer.print_state_missing_warning(transfer_metrics, elapsed)
+        else:
+            printer.print_sync_summary(
+                sid, final_state, responses, elapsed_seconds=elapsed, transfer_metrics=transfer_metrics
+            )
+    except (typer.Exit, KeyboardInterrupt):
+        raise
+    except Exception as exc:
+        _err_console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(code=1)

q2google/cli/_formatters.py

@@ -0,0 +1,101 @@
+"""String formatters for durations, byte counts, and transfer rates."""
+
+from __future__ import annotations
+
+from q2google.metrics import SyncTransferMetrics
+
+
+class MetricsFormatter:
+    """Format measurements and transfer metrics into human-readable strings."""
+
+    @staticmethod
+    def duration_compact(seconds: float) -> str:
+        """Format a duration in seconds as a compact human-readable string.
+
+        Args:
+            seconds: Duration in seconds.
+
+        Returns:
+            Formatted string like ``"1.23s"``, ``"5m 30.00s"``, or ``"2h 15m 30.00s"``.
+        """
+        if seconds < 60:
+            return f"{seconds:.2f}s"
+        minutes, sec = divmod(seconds, 60.0)
+        if minutes < 60:
+            return f"{int(minutes)}m {sec:.2f}s"
+        hours, mins = divmod(int(minutes), 60)
+        return f"{hours}h {mins}m {sec:.2f}s"
+
+    @classmethod
+    def execution_time(cls, seconds: float) -> str:
+        """Format wall-clock duration with an ``Execution time:`` prefix.
+
+        Args:
+            seconds: Elapsed seconds.
+
+        Returns:
+            String like ``"Execution time: 1m 23.45s"``.
+        """
+        return f"Execution time: {cls.duration_compact(seconds)}"
+
+    @staticmethod
+    def bytes_human(n: int) -> str:
+        """Format a byte count using binary IEC labels (KiB, MiB, GiB).
+
+        Args:
+            n: Number of bytes.
+
+        Returns:
+            Human-readable size string like ``"12.34 MiB"``.
+        """
+        if n < 1024:
+            return f"{n} B"
+        kib = n / 1024
+        if kib < 1024:
+            return f"{kib:.2f} KiB"
+        mib = n / (1024**2)
+        if mib < 1024:
+            return f"{mib:.2f} MiB"
+        gib = n / (1024**3)
+        return f"{gib:.2f} GiB"
+
+    @staticmethod
+    def rate_mib_s(bytes_count: int, seconds: float) -> str:
+        """Format average throughput as MiB/s.
+
+        Args:
+            bytes_count: Total bytes transferred.
+            seconds: Duration of the transfer.
+
+        Returns:
+            Throughput string like ``"12.34 MiB/s"`` or ``"n/a"`` when undefined.
+        """
+        if seconds <= 0 or bytes_count <= 0:
+            return "n/a"
+        mib_per_s = bytes_count / (1024 * 1024) / seconds
+        return f"{mib_per_s:.2f} MiB/s"
+
+    @classmethod
+    def throughput_rows(cls, m: SyncTransferMetrics) -> list[tuple[str, str]]:
+        """Build label/value pairs for transfer throughput display.
+
+        Args:
+            m: Transfer metrics from the sync run.
+
+        Returns:
+            List of ``(label, value)`` pairs; empty list when no transfer activity occurred.
+        """
+        if m.bytes_downloaded == 0 and m.bytes_uploaded == 0 and m.seconds_transfer_wall <= 0:
+            return []
+        return [
+            (
+                "CDN downloaded",
+                f"{cls.bytes_human(m.bytes_downloaded)}"
+                f"  (avg {cls.rate_mib_s(m.bytes_downloaded, m.seconds_downloading)})",
+            ),
+            (
+                "Uploaded to Google",
+                f"{cls.bytes_human(m.bytes_uploaded)}  (avg {cls.rate_mib_s(m.bytes_uploaded, m.seconds_uploading)})",
+            ),
+            ("Transfer stage wall time", cls.duration_compact(m.seconds_transfer_wall)),
+        ]

q2google/cli/_logging.py

@@ -0,0 +1,43 @@
+"""Logging configuration helpers for the q2google CLI."""
+
+from __future__ import annotations
+
+import logging
+
+_NOISY_LOGGER_NAMES: tuple[str, ...] = (
+    "aiohttp",
+    "aiohttp.client",
+    "google",
+    "google_auth_oauthlib",
+    "urllib3",
+    "gopro_api",
+)
+
+
+def _configure_cli_logging(*, explicit_level: str | None, verbose: bool) -> None:
+    """Configure root logging for Typer; quiet by default, optional verbose or explicit level.
+
+    Third-party libraries stay at WARNING unless root level is DEBUG.
+
+    Args:
+        explicit_level: ``--log-level`` value when provided.
+        verbose: ``True`` when ``-v`` / ``--verbose`` is set.
+    """
+    if explicit_level is not None:
+        root_level = getattr(logging, explicit_level.upper(), logging.WARNING)
+    elif verbose:
+        root_level = logging.INFO
+    else:
+        root_level = logging.WARNING
+
+    logging.basicConfig(
+        level=root_level,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+    if root_level < logging.DEBUG:
+        for name in _NOISY_LOGGER_NAMES:
+            logging.getLogger(name).setLevel(logging.WARNING)
+
+    if explicit_level is None:
+        logging.getLogger("q2google").setLevel(logging.INFO if verbose else logging.WARNING)