pynims 1.0.0__py3-none-any.whl

pynims/__init__.py

@@ -0,0 +1,3 @@
+from .client import NIMSClient as NIMSClient
+
+__version__ = "1.0.0"

pynims/cli.py

@@ -0,0 +1,402 @@
+import json
+import logging
+import re
+import typer
+from datetime import time, timedelta
+from typing import Optional
+from pathlib import Path
+
+from pynims import __version__
+from pynims.client import NIMSClient
+from pynims.workflows import (
+    get_camera_list,
+    get_image_list_for_camera,
+    save_image_list_to_file,
+    download_images_for_camera,
+)
+
+FILTER_PANEL = "Filter Options"
+
+
+def version_callback(value: bool):
+    if value:
+        typer.echo(f"pynims {__version__}")
+        raise typer.Exit()
+
+
+def _parse_interval(value: str) -> timedelta:
+    """Parse interval string like '24h', '7d', '30m' into timedelta."""
+    match = re.fullmatch(r"(\d+)([dhm])", value.strip())
+    if not match:
+        raise typer.BadParameter(
+            f"Invalid interval: {value}. Use e.g. '24h', '7d', '30m'"
+        )
+    n, unit = int(match.group(1)), match.group(2)
+    if unit == "d":
+        return timedelta(days=n)
+    elif unit == "h":
+        return timedelta(hours=n)
+    else:
+        return timedelta(minutes=n)
+
+
+def _parse_nth_per_group(value: str) -> tuple:
+    """Parse nth-per-group string like 'day:first', 'month:12:00'."""
+    parts = value.split(":", 1)
+    if len(parts) != 2:
+        raise typer.BadParameter(
+            f"Invalid format: {value}. Use e.g. 'day:first', 'month:12:00'"
+        )
+    group_by = parts[0]
+    position_str = parts[1]
+    if position_str in ("first", "last"):
+        return (group_by, position_str)
+    try:
+        h, m = position_str.split(":")
+        return (group_by, time(int(h), int(m)))
+    except (ValueError, TypeError):
+        raise typer.BadParameter(
+            f"Invalid position: {position_str}. Use 'first', 'last', or 'HH:MM'"
+        )
+
+
+def _build_filters(
+    hours,
+    months,
+    days_of_week,
+    days_of_month,
+    years,
+    date_range,
+    recurring_range,
+    interval,
+    nth_per_group,
+    times_of_day,
+    times_max_delta,
+) -> Optional[dict]:
+    """Build a filters dict from CLI flag values. Returns None if no filters specified."""
+    filters = {}
+    if hours is not None:
+        parts = hours.split("-")
+        if len(parts) != 2:
+            raise typer.BadParameter(f"Invalid hours: {hours}. Use e.g. '8-17'")
+        try:
+            start_h, end_h = int(parts[0]), int(parts[1])
+        except ValueError:
+            raise typer.BadParameter(f"Invalid hours: {hours}. Use e.g. '8-17'")
+        if not (0 <= start_h <= 23 and 0 <= end_h <= 23):
+            raise typer.BadParameter(f"Hours must be 0-23, got: {hours}")
+        filters["hours"] = (start_h, end_h)
+    if months is not None:
+        filters["months"] = [int(m) for m in months.split(",")]
+    if days_of_week is not None:
+        filters["days_of_week"] = [int(d) for d in days_of_week.split(",")]
+    if days_of_month is not None:
+        filters["days_of_month"] = [int(d) for d in days_of_month.split(",")]
+    if years is not None:
+        filters["years"] = [int(y) for y in years.split(",")]
+    if date_range is not None:
+        parts = date_range.split(",")
+        if len(parts) != 2:
+            raise typer.BadParameter(
+                f"Invalid date-range: {date_range}. Use e.g. '2023-06-01,2023-09-30'"
+            )
+        filters["date_range"] = (parts[0], parts[1])
+    if recurring_range is not None:
+        try:
+            start_part, end_part = recurring_range.split(",")
+            sm, sd = start_part.split("-")
+            em, ed = end_part.split("-")
+            filters["recurring_range"] = (int(sm), int(sd), int(em), int(ed))
+        except (ValueError, TypeError):
+            raise typer.BadParameter(
+                f"Invalid recurring-range: {recurring_range}. Use e.g. '5-1,9-30'"
+            )
+    if interval is not None:
+        filters["interval"] = _parse_interval(interval)
+    if nth_per_group is not None:
+        filters["nth_per_group"] = _parse_nth_per_group(nth_per_group)
+    if times_of_day is not None:
+        times = []
+        for t in times_of_day.split(","):
+            h, m = t.strip().split(":")
+            times.append(time(int(h), int(m)))
+        td_args: dict[str, object] = {"times": times}
+        if times_max_delta is not None:
+            td_args["max_delta"] = _parse_interval(times_max_delta)
+        filters["times_of_day"] = td_args
+    return filters or None
+
+
+app = typer.Typer(help="NIMS Workflow CLI")
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit",
+    ),
+):
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+@app.command()
+def cameras(
+    full: bool = typer.Option(False, "--full", help="Show full camera info"),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    api_key: Optional[str] = typer.Option(None, help="NIMS API key"),
+    site_id: Optional[str] = typer.Option(None, help="NWIS site ID"),
+    cam_id: Optional[str] = typer.Option(None, help="Camera ID"),
+):
+    """List cameras (IDs or full info)."""
+    result = get_camera_list(
+        ids_only=not full, api_key=api_key, site_id=site_id, cam_id=cam_id
+    )
+    if output_json:
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        for item in result:
+            typer.echo(item if isinstance(item, str) else json.dumps(item))
+
+
+@app.command()
+def camera(
+    camera_id: str = typer.Argument(..., help="Camera ID"),
+    api_key: Optional[str] = typer.Option(None, help="NIMS API key"),
+):
+    """Show details for a single camera."""
+    try:
+        with NIMSClient(api_key=api_key) as client:
+            result = client.get_camera(camera_id)
+        typer.echo(json.dumps(result, indent=2))
+    except ValueError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def image_list(
+    camera_id: str = typer.Argument(..., help="Camera ID"),
+    start: Optional[str] = typer.Option(None, help="Start datetime (ISO 8601)"),
+    end: Optional[str] = typer.Option(None, help="End datetime (ISO 8601)"),
+    recursive: Optional[bool] = typer.Option(None, help="Use recursive fetching"),
+    max_results: Optional[int] = typer.Option(
+        None, help="Max number of images to include in list"
+    ),
+    save_dir: Optional[Path] = typer.Option(None, help="Directory to save image list"),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    api_key: Optional[str] = typer.Option(None, help="NIMS API key"),
+    tz: Optional[str] = typer.Option(
+        None,
+        help="Timezone for filtering (default: camera tz)",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    hours: Optional[str] = typer.Option(
+        None, help="Hour range, e.g. 8-17", rich_help_panel=FILTER_PANEL
+    ),
+    months: Optional[str] = typer.Option(
+        None, help="Months, e.g. 6,7,8", rich_help_panel=FILTER_PANEL
+    ),
+    days_of_week: Optional[str] = typer.Option(
+        None,
+        help="Days of week (0=Mon-6=Sun), e.g. 0,1,2,3,4",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    days_of_month: Optional[str] = typer.Option(
+        None, help="Days of month, e.g. 1,15", rich_help_panel=FILTER_PANEL
+    ),
+    years: Optional[str] = typer.Option(
+        None, help="Years, e.g. 2023,2024", rich_help_panel=FILTER_PANEL
+    ),
+    date_range: Optional[str] = typer.Option(
+        None,
+        help="Date range, e.g. 2023-06-01,2023-09-30",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    recurring_range: Optional[str] = typer.Option(
+        None,
+        help="Recurring month-day range, e.g. 5-1,9-30",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    interval: Optional[str] = typer.Option(
+        None, help="Sampling interval, e.g. 24h, 7d, 30m", rich_help_panel=FILTER_PANEL
+    ),
+    nth_per_group: Optional[str] = typer.Option(
+        None,
+        help="Pick per group, e.g. day:first, month:12:00",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    times_of_day: Optional[str] = typer.Option(
+        None,
+        help="Pick nearest image to each time per day, e.g. 08:00,12:00,14:00 (no distance limit unless --times-max-delta is set)",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    times_max_delta: Optional[str] = typer.Option(
+        None,
+        help="Max delta for times-of-day, e.g. 2m, 30m",
+        rich_help_panel=FILTER_PANEL,
+    ),
+):
+    """Fetch image list for a camera."""
+    filters = _build_filters(
+        hours,
+        months,
+        days_of_week,
+        days_of_month,
+        years,
+        date_range,
+        recurring_range,
+        interval,
+        nth_per_group,
+        times_of_day,
+        times_max_delta,
+    )
+    if save_dir is not None:
+        save_image_list_to_file(
+            camera_id=camera_id,
+            start=start,
+            end=end,
+            recursive=recursive,
+            max_results=max_results,
+            save_dir=save_dir,
+            api_key=api_key,
+            filters=filters,
+            tz=tz,
+        )
+        typer.echo(f"Saved image list for {camera_id} to {save_dir}")
+    else:
+        images = get_image_list_for_camera(
+            camera_id=camera_id,
+            start=start,
+            end=end,
+            recursive=recursive,
+            max_results=max_results,
+            api_key=api_key,
+            filters=filters,
+            tz=tz,
+        )
+        if output_json:
+            typer.echo(json.dumps(images, indent=2))
+        else:
+            for img in images:
+                typer.echo(img)
+
+
+@app.command()
+def download_images(
+    camera_id: Optional[str] = typer.Argument(
+        None, help="Camera ID (required unless --image-list-file is provided)"
+    ),
+    start: Optional[str] = typer.Option(None, help="Start datetime (ISO 8601)"),
+    end: Optional[str] = typer.Option(None, help="End datetime (ISO 8601)"),
+    recursive: Optional[bool] = typer.Option(None, help="Use recursive fetching"),
+    max_results: Optional[int] = typer.Option(
+        None, help="Max number of images to download"
+    ),
+    save_dir: Optional[Path] = typer.Option(
+        None, help="Parent directory to save images"
+    ),
+    image_list_file: Optional[Path] = typer.Option(
+        None, help="JSON file containing list of image names to download"
+    ),
+    api_key: Optional[str] = typer.Option(None, help="NIMS API key"),
+    size: str = typer.Option("full", help="Image size: full, thumb, or small"),
+    tz: Optional[str] = typer.Option(
+        None,
+        help="Timezone for filtering (default: camera tz)",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    hours: Optional[str] = typer.Option(
+        None, help="Hour range, e.g. 8-17", rich_help_panel=FILTER_PANEL
+    ),
+    months: Optional[str] = typer.Option(
+        None, help="Months, e.g. 6,7,8", rich_help_panel=FILTER_PANEL
+    ),
+    days_of_week: Optional[str] = typer.Option(
+        None,
+        help="Days of week (0=Mon-6=Sun), e.g. 0,1,2,3,4",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    days_of_month: Optional[str] = typer.Option(
+        None, help="Days of month, e.g. 1,15", rich_help_panel=FILTER_PANEL
+    ),
+    years: Optional[str] = typer.Option(
+        None, help="Years, e.g. 2023,2024", rich_help_panel=FILTER_PANEL
+    ),
+    date_range: Optional[str] = typer.Option(
+        None,
+        help="Date range, e.g. 2023-06-01,2023-09-30",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    recurring_range: Optional[str] = typer.Option(
+        None,
+        help="Recurring month-day range, e.g. 5-1,9-30",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    interval: Optional[str] = typer.Option(
+        None, help="Sampling interval, e.g. 24h, 7d, 30m", rich_help_panel=FILTER_PANEL
+    ),
+    nth_per_group: Optional[str] = typer.Option(
+        None,
+        help="Pick per group, e.g. day:first, month:12:00",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    times_of_day: Optional[str] = typer.Option(
+        None,
+        help="Pick nearest image to each time per day, e.g. 08:00,12:00,14:00 (no distance limit unless --times-max-delta is set)",
+        rich_help_panel=FILTER_PANEL,
+    ),
+    times_max_delta: Optional[str] = typer.Option(
+        None,
+        help="Max delta for times-of-day, e.g. 2m, 30m",
+        rich_help_panel=FILTER_PANEL,
+    ),
+):
+    """Download images for a camera."""
+    image_list = None
+    if image_list_file:
+        image_list = json.loads(image_list_file.read_text())
+    if not camera_id and not image_list:
+        typer.echo(
+            "Error: CAMERA_ID is required unless --image-list-file is provided",
+            err=True,
+        )
+        raise typer.Exit(1)
+    filters = _build_filters(
+        hours,
+        months,
+        days_of_week,
+        days_of_month,
+        years,
+        date_range,
+        recurring_range,
+        interval,
+        nth_per_group,
+        times_of_day,
+        times_max_delta,
+    )
+    result = download_images_for_camera(
+        camera_id=camera_id,
+        start=start,
+        end=end,
+        recursive=recursive,
+        max_results=max_results,
+        save_dir=save_dir,
+        image_list=image_list,
+        api_key=api_key,
+        size=size,
+        filters=filters,
+        tz=tz,
+    )
+    typer.echo(
+        f"Downloaded {result['downloaded']}, "
+        f"skipped {result['skipped']}, "
+        f"not found {result['not_found']}"
+    )
+
+
+if __name__ == "__main__":
+    app()