eolas-data 1.2.0__py3-none-any.whl

eolas_data/client.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import os
+from typing import Optional, Union
+
+import pandas as pd
+import requests
+
+from .dataset import Dataset
+from .exceptions import APIError, AuthenticationError, NotFoundError, RateLimitError
+
+# Imported separately so the names module is also re-exportable for users who
+# want IDE autocomplete on dataset names without instantiating a Client.
+from ._dataset_names import DatasetName  # noqa: F401  (public re-export)
+
+
+BASE_URL = "https://api.eolas.fyi"
+
+
+def _to_geodataframe(df: "pd.DataFrame", force: bool = False):
+    """Convert a DataFrame with a ``geometry_wkt`` column to a GeoDataFrame (CRS WGS84).
+
+    Returns the GeoDataFrame on success, or ``None`` when geopandas isn't installed
+    (and ``force`` is False) so the caller can fall back to the plain DataFrame.
+    Raises ImportError when ``force=True`` but geopandas is missing.
+    """
+    try:
+        import geopandas as gpd
+        from shapely import wkt as _wkt
+    except ImportError:
+        if force:
+            raise ImportError(
+                "geopandas + shapely are required to return geospatial datasets "
+                "as GeoDataFrames. Install with: pip install eolas-data[geo]"
+            )
+        return None
+
+    geom = df["geometry_wkt"].apply(lambda s: _wkt.loads(s) if isinstance(s, str) and s else None)
+    gdf = gpd.GeoDataFrame(df.drop(columns=["geometry_wkt"]), geometry=geom, crs="EPSG:4326")
+    for attr in ("eolas_name", "eolas_source"):
+        if hasattr(df, attr):
+            try:
+                setattr(gdf, attr, getattr(df, attr))
+            except Exception:
+                pass
+    return gdf
+
+
+class Client:
+    """Client for the eolas.fyi statistical data API.
+
+    Args:
+        api_key:  Your API key. Falls back to the ``EOLAS_API_KEY`` env var
+                  (or ``VS_API_KEY`` for back-compat with the legacy library).
+        base_url: Override the API base URL (useful for testing).
+        cache:    Cache responses in memory for the lifetime of the client.
+                  Useful in notebooks to avoid re-fetching on re-runs.
+
+    Examples::
+
+        from eolas_data import Client
+        client = Client("your_api_key")
+
+        # Source-specific helpers
+        df = client.statsnz("nz_cpi", start="2020-01-01")
+        df = client.oecd("nz_gdp")
+
+        # Generic
+        df = client.get("nz_cpi")
+
+        # Discovery
+        all_datasets = client.list()
+        nz_datasets  = client.list("Stats NZ")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = BASE_URL,
+        cache: bool = False,
+    ):
+        self._key   = api_key or os.getenv("EOLAS_API_KEY") or os.getenv("VS_API_KEY") or ""
+        self._base  = base_url.rstrip("/")
+        self._cache: dict | None = {} if cache else None
+        self._session = requests.Session()
+        self._session.headers.update({"X-API-Key": self._key})
+
+    def __repr__(self) -> str:
+        masked = self._key[:8] + "..." if len(self._key) > 8 else self._key
+        cache  = " cache=on" if self._cache is not None else ""
+        return f"<eolas_data.Client key={masked!r}{cache}>"
+
+    # ------------------------------------------------------------------
+    # Discovery
+    # ------------------------------------------------------------------
+
+    def list(self, source: Optional[str] = None) -> list[dict]:
+        """Return metadata for all available datasets.
+
+        Args:
+            source: Optional filter, e.g. ``"Stats NZ"``, ``"OECD"``.
+        """
+        data = self._get("/v1/datasets")
+        items = data.get("datasets", data) if isinstance(data, dict) else data
+        if source:
+            items = [s for s in items if s.get("source") == source]
+        return items
+
+    def info(self, name: Union[str, "DatasetName"]) -> dict:
+        """Return metadata for a single dataset."""
+        return self._get(f"/v1/datasets/{name}")
+
+    # ------------------------------------------------------------------
+    # Integrations (Enterprise plan only)
+    # ------------------------------------------------------------------
+
+    def integration(self, platform: str, datasets: list[str]) -> dict[str, str]:
+        """Generate connector config files for a third-party data-pipeline tool.
+
+        Enterprise plan only. Other plans receive an
+        :class:`AuthenticationError` with the upgrade message in the detail.
+
+        Args:
+            platform: One of ``"meltano"``, ``"fivetran"``, ``"azure-data-factory"``.
+            datasets: Dataset names to include in the generated config.
+
+        Returns:
+            ``{filename: file_contents}`` ready to write to disk.
+
+        Examples::
+
+            files = client.integration("meltano", ["nz_cpi", "nz_gdp"])
+            for filename, content in files.items():
+                Path("./tap-eolas") / filename).write_text(content)
+        """
+        if not datasets:
+            raise ValueError("datasets cannot be empty")
+        resp = self._get(
+            f"/v1/integrations/{platform}",
+            params={"datasets": ",".join(datasets)},
+        )
+        return resp.get("files", {})
+
+    # ------------------------------------------------------------------
+    # Source-specific helpers
+    # ------------------------------------------------------------------
+
+    def statsnz(self, name, **kwargs) -> Dataset:
+        """Fetch a Stats NZ dataset."""
+        return self._get_source(name, "Stats NZ", **kwargs)
+
+    def oecd(self, name, **kwargs) -> Dataset:
+        """Fetch an OECD dataset."""
+        return self._get_source(name, "OECD", **kwargs)
+
+    def rbnz(self, name, **kwargs) -> Dataset:
+        """Fetch an RBNZ dataset."""
+        return self._get_source(name, "RBNZ", **kwargs)
+
+    def treasury(self, name, **kwargs) -> Dataset:
+        """Fetch an NZ Treasury dataset."""
+        return self._get_source(name, "NZ Treasury", **kwargs)
+
+    def linz(self, name, **kwargs) -> Dataset:
+        """Fetch a LINZ dataset."""
+        return self._get_source(name, "LINZ", **kwargs)
+
+    def statsnz_geo(self, name, **kwargs) -> Dataset:
+        """Fetch a Stats NZ Geospatial dataset."""
+        return self._get_source(name, "Stats NZ Geospatial", **kwargs)
+
+    def mbie(self, name, **kwargs) -> Dataset:
+        """Fetch an MBIE dataset."""
+        return self._get_source(name, "MBIE", **kwargs)
+
+    def nzta(self, name, **kwargs) -> Dataset:
+        """Fetch a Waka Kotahi (NZTA) dataset."""
+        return self._get_source(name, "Waka Kotahi", **kwargs)
+
+    def msd(self, name, **kwargs) -> Dataset:
+        """Fetch an MSD dataset."""
+        return self._get_source(name, "MSD", **kwargs)
+
+    def police(self, name, **kwargs) -> Dataset:
+        """Fetch an NZ Police / MoJ dataset."""
+        return self._get_source(name, "NZ Police / MoJ", **kwargs)
+
+    def acc(self, name, **kwargs) -> Dataset:
+        """Fetch an ACC dataset."""
+        return self._get_source(name, "ACC", **kwargs)
+
+    def edcounts(self, name, **kwargs) -> Dataset:
+        """Fetch an Education Counts dataset."""
+        return self._get_source(name, "Education Counts", **kwargs)
+
+    def worksafe(self, name, **kwargs) -> Dataset:
+        """Fetch a WorkSafe NZ dataset."""
+        return self._get_source(name, "WorkSafe NZ", **kwargs)
+
+    def _get_source(self, name, source: str, **kwargs) -> Dataset:
+        df = self.get(name, **kwargs)
+        df.eolas_source = source
+        return df
+
+    # ------------------------------------------------------------------
+    # Core data fetch
+    # ------------------------------------------------------------------
+
+    def get(
+        self,
+        name: Union[str, "DatasetName"],
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        format: str = "json",
+        engine: str = "pandas",
+        limit: Optional[int] = None,
+        as_geo: Optional[bool] = None,
+    ) -> Dataset:
+        """Fetch dataset rows as a pandas (or polars / geopandas) DataFrame.
+
+        Args:
+            name:   Dataset identifier, e.g. ``"nz_cpi"``. Type-checked against
+                    the ``DatasetName`` Literal at static-analysis time so
+                    IDEs autocomplete the catalog.
+            start:  ISO date lower bound, e.g. ``"2020-01-01"``.
+            end:    ISO date upper bound, e.g. ``"2024-12-31"``.
+            format: ``"json"`` (default) or ``"csv"``.
+            engine: ``"pandas"`` (default) or ``"polars"``.
+            limit:  Max rows to return. Default ``None`` requests the full dataset
+                    (server enforces a 50,000-row cap on Free/Starter plans; Pro is
+                    unlimited). Pass an explicit integer to request fewer rows.
+            as_geo: Convert geospatial datasets to a ``GeoDataFrame``.
+                    ``None`` (default) auto-converts when the dataset has a
+                    ``geometry_wkt`` column AND ``geopandas`` is importable.
+                    ``True`` forces the conversion (raises if geopandas missing).
+                    ``False`` keeps the raw WKT string column.
+                    Install with ``pip install eolas-data[geo]``.
+
+        Returns:
+            A :class:`Dataset` (pandas DataFrame subclass), a polars DataFrame
+            when ``engine="polars"``, or a ``geopandas.GeoDataFrame`` when
+            geometry is present and conversion is enabled.
+        """
+        params: dict = {}
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        # Server-side: limit=0 means "as much as the plan allows" (full dataset for Pro,
+        # 50K cap for Free/Starter). limit=None on the client maps to limit=0.
+        params["limit"] = 0 if limit is None else int(limit)
+
+        cache_key = f"{name}:{start}:{end}:{format}:{params['limit']}:{as_geo}"
+        if self._cache is not None and cache_key in self._cache:
+            return self._cache[cache_key]
+
+        if format == "csv":
+            from io import StringIO
+            resp = self._raw_get(f"/v1/datasets/{name}/data", params={"format": "csv", **params})
+            df   = pd.read_csv(StringIO(resp.text))
+        else:
+            data    = self._get(f"/v1/datasets/{name}/data", params=params)
+            records = data.get("data", data) if isinstance(data, dict) else data
+            df      = pd.DataFrame(records)
+            if "date" in df.columns:
+                df["date"] = pd.to_datetime(df["date"])
+
+        result = Dataset(df)
+        result.eolas_name   = name
+        result.eolas_source = ""
+
+        if engine == "polars":
+            try:
+                import polars as pl
+                return pl.from_pandas(result)
+            except ImportError:
+                raise ImportError(
+                    "polars is required for engine='polars'. "
+                    "Install with: pip install eolas-data[polars]"
+                )
+
+        # Optional geopandas conversion. When as_geo=None we auto-convert if both
+        # (a) the dataset has a geometry_wkt column AND (b) geopandas is importable.
+        if as_geo is not False and "geometry_wkt" in result.columns:
+            converted = _to_geodataframe(result, force=as_geo is True)
+            if converted is not None:
+                result = converted
+
+        if self._cache is not None:
+            self._cache[cache_key] = result
+
+        return result
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        return self._raw_get(path, params=params).json()
+
+    def _raw_get(self, path: str, params: Optional[dict] = None) -> requests.Response:
+        url  = f"{self._base}{path}"
+        resp = self._session.get(url, params=params)
+        self._raise_for_status(resp)
+        return resp
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response) -> None:
+        if resp.status_code == 200:
+            return
+        if resp.status_code == 401:
+            raise AuthenticationError("Invalid or missing API key.")
+        if resp.status_code == 403:
+            try:
+                detail = resp.json().get("detail", "API key is inactive.")
+            except Exception:
+                detail = "API key is inactive."
+            raise AuthenticationError(detail)
+        if resp.status_code == 429:
+            raise RateLimitError(
+                "Monthly request limit reached. Upgrade for higher limits."
+            )
+        if resp.status_code == 404:
+            try:
+                detail = resp.json().get("detail", "Not found.")
+            except Exception:
+                detail = "Not found."
+            raise NotFoundError(detail)
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+        raise APIError(resp.status_code, detail)

eolas_data/dataset.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import pandas as pd
+
+
+class Dataset(pd.DataFrame):
+    """A pandas DataFrame with eolas dataset metadata.
+
+    Behaves exactly like a DataFrame — all pandas operations work normally.
+    Extra attributes:
+        eolas_name:   Dataset identifier (e.g. ``"nz_cpi"``).
+        eolas_source: Data source label (e.g. ``"Stats NZ"``).
+    """
+
+    _metadata = ["eolas_name", "eolas_source"]
+
+    @property
+    def _constructor(self):
+        return Dataset
+
+    def __repr__(self) -> str:
+        name   = getattr(self, "eolas_name",   "") or ""
+        source = getattr(self, "eolas_source", "") or ""
+        if name:
+            header = f"# Dataset: {name}"
+            if source:
+                header += f" [{source}]"
+            header += f"\n# {len(self)} rows\n"
+            return header + pd.DataFrame.__repr__(self)
+        return pd.DataFrame.__repr__(self)
+
+    def plot_dataset(self, ax=None, **kwargs):
+        """Quick line chart using matplotlib.
+
+        Returns the matplotlib Axes object so you can customise further.
+        Requires matplotlib: ``pip install eolas-data[plot]``.
+        """
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError:
+            raise ImportError(
+                "matplotlib is required for plot_dataset(). "
+                "Install with: pip install eolas-data[plot]"
+            )
+
+        date_col  = "date"  if "date"  in self.columns else self.columns[0]
+        value_col = "value" if "value" in self.columns else self.columns[1]
+
+        if ax is None:
+            _, ax = plt.subplots(figsize=(10, 4))
+
+        ax.plot(self[date_col], self[value_col], color="#2563eb", linewidth=1.5, **kwargs)
+
+        name   = getattr(self, "eolas_name",   "") or ""
+        source = getattr(self, "eolas_source", "") or ""
+
+        if name:
+            ax.set_title(name, fontweight="bold", fontsize=13)
+        ax.set_xlabel("")
+        ax.spines[["top", "right"]].set_visible(False)
+
+        caption = f"Source: {source} · eolas.fyi" if source else "eolas.fyi"
+        ax.figure.text(0.99, 0.01, caption, ha="right", fontsize=8, color="#9ca3af")
+
+        plt.tight_layout()
+        return ax

eolas_data/exceptions.py

@@ -0,0 +1,20 @@
+class EolasError(Exception):
+    """Base exception for the eolas-data client."""
+
+
+class AuthenticationError(EolasError):
+    pass
+
+
+class RateLimitError(EolasError):
+    pass
+
+
+class NotFoundError(EolasError):
+    pass
+
+
+class APIError(EolasError):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"HTTP {status_code}: {message}")

eolas_data/schedule.py

@@ -0,0 +1,258 @@
+"""Cross-platform scheduling backend for `eolas schedule add|list|remove`.
+
+POSIX (Linux/macOS): edits the user's crontab via `crontab -l` / `crontab -`.
+Windows:             uses `schtasks` to create per-user scheduled tasks.
+
+Both backends only manage entries tagged with a sentinel so the user's other
+cron jobs / scheduled tasks are never touched.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Optional
+
+SENTINEL  = "# eolas-schedule:"
+TASK_PREFIX = "eolas-"  # Windows task name prefix
+
+# Interval shortcut → cron expression (minute hour dom month dow). Daily/weekly/
+# monthly all default to 6am because datasets typically refresh in the early
+# hours; running at 6am gets the freshest data without competing for resources.
+INTERVALS = {
+    "hourly":  "0 * * * *",
+    "daily":   "0 6 * * *",
+    "weekly":  "0 6 * * 1",   # Monday 6am
+    "monthly": "0 6 1 * *",   # 1st of month, 6am
+}
+
+# Windows schtasks /sc value per interval. Custom cron exprs not supported on
+# Windows backend — see _windows_add for the fallback message.
+WIN_SCHED = {
+    "hourly":  ("HOURLY",  None),
+    "daily":   ("DAILY",   "06:00"),
+    "weekly":  ("WEEKLY",  "06:00"),    # default day = today's weekday; we override below
+    "monthly": ("MONTHLY", "06:00"),
+}
+
+CRON_EXPR_RE = re.compile(r"^\s*\S+\s+\S+\s+\S+\s+\S+\s+\S+\s*$")
+
+
+@dataclass
+class ScheduleEntry:
+    name: str
+    schedule: str   # cron expr (POSIX) or human description (Windows)
+    command: str
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Public API — dispatches per OS
+# ────────────────────────────────────────────────────────────────────────────
+
+def is_windows() -> bool:
+    return platform.system() == "Windows"
+
+
+def add(name: str, schedule_expr: str, command: str) -> None:
+    """Register a scheduled task. `schedule_expr` is a cron expression on POSIX
+    or one of {'hourly','daily','weekly','monthly'} on Windows."""
+    if is_windows():
+        _windows_add(name, schedule_expr, command)
+    else:
+        _cron_add(name, schedule_expr, command)
+
+
+def remove(name: str) -> bool:
+    """Remove a managed task. Returns True if removed, False if not found."""
+    if is_windows():
+        return _windows_remove(name)
+    return _cron_remove(name)
+
+
+def list_entries() -> list[ScheduleEntry]:
+    """Return all managed eolas-schedule entries."""
+    if is_windows():
+        return _windows_list()
+    return _cron_list()
+
+
+def interval_to_cron(interval: str) -> str:
+    """Return the cron expression for an interval shortcut. Raises on unknown."""
+    if interval not in INTERVALS:
+        raise ValueError(f"unknown interval {interval!r}; expected one of {list(INTERVALS)}")
+    return INTERVALS[interval]
+
+
+def validate_cron_expr(expr: str) -> None:
+    """Basic shape check on a 5-field cron expression. Raises on invalid."""
+    if not CRON_EXPR_RE.match(expr):
+        raise ValueError(
+            f"invalid cron expression {expr!r}; expected 5 fields "
+            "(minute hour day-of-month month day-of-week)"
+        )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# POSIX cron backend
+# ────────────────────────────────────────────────────────────────────────────
+
+def _crontab_available() -> bool:
+    return shutil.which("crontab") is not None
+
+
+def _cron_read() -> list[str]:
+    """Read the user's crontab. Returns [] when no crontab is set."""
+    if not _crontab_available():
+        raise RuntimeError(
+            "crontab is not installed on this system. "
+            "On Debian/Ubuntu: sudo apt-get install cron. On Alpine: apk add busybox-suid."
+        )
+    proc = subprocess.run(
+        ["crontab", "-l"], capture_output=True, text=True
+    )
+    if proc.returncode == 0:
+        return proc.stdout.splitlines()
+    # Some implementations exit 1 with "no crontab" — treat as empty.
+    if "no crontab" in (proc.stderr or "").lower():
+        return []
+    raise RuntimeError(f"crontab -l failed: {proc.stderr.strip() or proc.stdout.strip()}")
+
+
+def _cron_write(lines: list[str]) -> None:
+    payload = "\n".join(lines).rstrip() + "\n"
+    proc = subprocess.run(
+        ["crontab", "-"], input=payload, text=True, capture_output=True
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"crontab - failed: {proc.stderr.strip()}")
+
+
+def _cron_format_line(name: str, cron_expr: str, command: str) -> str:
+    return f"{cron_expr} {command}  {SENTINEL} {name}"
+
+
+def _cron_match_name(line: str, name: str) -> bool:
+    return SENTINEL in line and line.rstrip().endswith(name)
+
+
+def _cron_add(name: str, cron_expr: str, command: str) -> None:
+    validate_cron_expr(cron_expr)
+    lines = [l for l in _cron_read() if not _cron_match_name(l, name)]  # idempotent
+    lines.append(_cron_format_line(name, cron_expr, command))
+    _cron_write(lines)
+
+
+def _cron_remove(name: str) -> bool:
+    lines = _cron_read()
+    kept  = [l for l in lines if not _cron_match_name(l, name)]
+    if len(kept) == len(lines):
+        return False
+    _cron_write(kept)
+    return True
+
+
+def _cron_list() -> list[ScheduleEntry]:
+    out: list[ScheduleEntry] = []
+    for line in _cron_read():
+        if SENTINEL not in line:
+            continue
+        head, _, tail = line.partition(SENTINEL)
+        name  = tail.strip()
+        parts = head.strip().split(maxsplit=5)
+        if len(parts) < 6:
+            continue   # malformed; skip silently
+        cron_expr = " ".join(parts[:5])
+        command   = parts[5]
+        out.append(ScheduleEntry(name=name, schedule=cron_expr, command=command))
+    return out
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Windows schtasks backend
+# ────────────────────────────────────────────────────────────────────────────
+
+def _schtasks_available() -> bool:
+    return shutil.which("schtasks") is not None
+
+
+def _windows_add(name: str, interval: str, command: str) -> None:
+    if not _schtasks_available():
+        raise RuntimeError("schtasks not found — required on Windows for scheduling")
+    if interval not in WIN_SCHED:
+        raise ValueError(
+            f"Windows backend supports interval shortcuts only "
+            f"({list(WIN_SCHED)}); got {interval!r}. "
+            "Custom cron expressions aren't translatable; use schtasks GUI for advanced cases."
+        )
+    sc, st = WIN_SCHED[interval]
+    args = [
+        "schtasks", "/create",
+        "/tn", f"{TASK_PREFIX}{name}",
+        "/tr", command,
+        "/sc", sc,
+        "/f",  # overwrite if exists (idempotent add)
+    ]
+    if st:
+        args += ["/st", st]
+    if interval == "weekly":
+        args += ["/d", "MON"]
+    proc = subprocess.run(args, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError(f"schtasks /create failed: {proc.stderr.strip()}")
+
+
+def _windows_remove(name: str) -> bool:
+    proc = subprocess.run(
+        ["schtasks", "/delete", "/tn", f"{TASK_PREFIX}{name}", "/f"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode == 0:
+        return True
+    # schtasks returns non-zero if the task doesn't exist
+    if "cannot find" in (proc.stderr + proc.stdout).lower():
+        return False
+    raise RuntimeError(f"schtasks /delete failed: {proc.stderr.strip()}")
+
+
+def _windows_list() -> list[ScheduleEntry]:
+    proc = subprocess.run(
+        ["schtasks", "/query", "/fo", "CSV", "/v"],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"schtasks /query failed: {proc.stderr.strip()}")
+    out: list[ScheduleEntry] = []
+    reader = csv.DictReader(io.StringIO(proc.stdout))
+    for row in reader:
+        task_name = (row.get("TaskName") or "").lstrip("\\").strip()
+        if not task_name.startswith(TASK_PREFIX):
+            continue
+        out.append(ScheduleEntry(
+            name=task_name[len(TASK_PREFIX):],
+            schedule=row.get("Schedule Type") or "",
+            command=row.get("Task To Run") or "",
+        ))
+    return out
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Helpers used by cli.py
+# ────────────────────────────────────────────────────────────────────────────
+
+def build_command(eolas_path: str, dataset: str, out_path: str,
+                  start: Optional[str] = None, end: Optional[str] = None,
+                  fmt: str = "csv") -> str:
+    """Construct the shell command line to put inside the cron entry."""
+    parts = [shlex.quote(eolas_path), "get", shlex.quote(dataset),
+             "--format", shlex.quote(fmt),
+             "--out", shlex.quote(str(out_path))]
+    if start:
+        parts += ["--start", shlex.quote(start)]
+    if end:
+        parts += ["--end", shlex.quote(end)]
+    return " ".join(parts)