"""MobilityTwin.Brussels client: one file, needs only `requests`.

Get it with

    curl -O https://mobilitytwin.brussels/client/mobilitytwin.py

and put your API token (https://mobilitytwin.brussels/account/) in the
MOBILITYTWIN_TOKEN environment variable or in a `.env` file next to your code.

Python
    from mobilitytwin import MobilityTwin
    mt = MobilityTwin()
    when, data = mt.latest("stib/vehicle-trip")
    when, data = mt.at("stib/vehicle-trip", "2026-09-01T08:00:00Z")
    paths = mt.download("stib/vehicle-trip", "2026-09-01", "2026-09-02",
                        every=60, out="data")
    for snapshot, data in mt.iter_snapshots("villo/stations", "-6h"):
        ...

Command line
    python mobilitytwin.py download stib/vehicle-trip \\
        --start 2026-09-01T06:00Z --end 2026-09-01T10:00Z --every 60 --out data
    python mobilitytwin.py latest villo/stations -o villo.json
    python mobilitytwin.py index sncb/gtfs-parquet --start 2026-09-01 --end 2026-09-08

History works the same for every endpoint: `index` lists each snapshot in a
range (one API request per 10,000 snapshots), and the snapshots are then
downloaded straight from public blob storage, in parallel. `download` keeps
what it already has, so an interrupted run resumes where it stopped. Daily
archives (GTFS, punctuality) are just endpoints with one snapshot a day: list
the days you want instead of guessing which timestamp files them.

Times accept Unix seconds, ISO 8601 (`2026-09-01T08:00:00Z`, naive = UTC), a
date (`2026-09-01` = midnight UTC), a datetime, `now`, or an offset from now
(`-30m`, `-6h`, `-2d`). Brussels is UTC+1 in winter and UTC+2 in summer.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import shutil
import sys
import time
from concurrent.futures import ThreadPoolExecutor
from datetime import date, datetime, timedelta, timezone
from pathlib import Path
from typing import Iterator, List, NamedTuple, Optional, Tuple, Union

import requests

__version__ = "1.0.0"

API_URL = os.environ.get("MOBILITYTWIN_API_URL", "https://api.mobilitytwin.brussels")
ACCOUNT_URL = "https://mobilitytwin.brussels/account/"
TOKEN_ENV = "MOBILITYTWIN_TOKEN"

TEXT_FORMATS = {"json", "geojson", "mf-json"}
EXTENSIONS = {
    "json": ".json",
    "geojson": ".geojson",
    "mf-json": ".json",
    "gtfs": ".zip",
    "gtfs-parquet": ".zip",
    "gtfs-rt": ".pb",
    "parquet": ".parquet",
}

When = Union[int, float, str, date, datetime, None]


class Snapshot(NamedTuple):
    timestamp: int  # Unix seconds, UTC
    date: str  # ISO 8601, UTC
    url: str  # public blob URL


class MobilityTwinError(RuntimeError):
    pass


def load_token() -> str:
    """MOBILITYTWIN_TOKEN from the environment, else from the nearest `.env` upwards."""
    token = os.environ.get(TOKEN_ENV)
    if token:
        return token.strip()
    for folder in [Path.cwd(), *Path.cwd().parents]:
        env_file = folder / ".env"
        if env_file.is_file():
            for line in env_file.read_text().splitlines():
                key, _, value = line.partition("=")
                if key.strip().removeprefix("export ").strip() == TOKEN_ENV and value.strip():
                    return value.strip().strip("'\"")
    raise MobilityTwinError(
        f"No API token: set {TOKEN_ENV} or add it to a .env file. Create one at {ACCOUNT_URL}"
    )


def to_epoch(value: When) -> int:
    """Unix seconds (UTC) from the time formats listed in the module docstring."""
    if value is None or value == "now":
        return int(time.time())
    if isinstance(value, (int, float)):
        return int(value)
    if isinstance(value, datetime):
        return int((value if value.tzinfo else value.replace(tzinfo=timezone.utc)).timestamp())
    if isinstance(value, date):
        return int(datetime(value.year, value.month, value.day, tzinfo=timezone.utc).timestamp())
    text = str(value).strip()
    relative = re.fullmatch(r"-(\d+(?:\.\d+)?)([smhd])", text)
    if relative:
        seconds = float(relative.group(1)) * {"s": 1, "m": 60, "h": 3600, "d": 86400}[relative.group(2)]
        return int(time.time() - seconds)
    if re.fullmatch(r"-?\d+(\.\d+)?", text):
        return int(float(text))
    parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
    return to_epoch(parsed)


def _iso(timestamp: int) -> str:
    return datetime.fromtimestamp(timestamp, tz=timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")


class MobilityTwin:
    def __init__(self, token: Optional[str] = None, api_url: str = API_URL,
                 timeout: float = 300, retries: int = 4):
        self.token = token or load_token()
        self.api_url = api_url.rstrip("/")
        self.timeout = timeout
        self.retries = retries
        self.session = requests.Session()
        self._formats = {}

    # ------------------------------------------------------------------ HTTP
    def _request(self, url: str, params: Optional[dict] = None, auth: bool = True) -> requests.Response:
        headers = {"Authorization": f"Bearer {self.token}"} if auth else {}
        for attempt in range(self.retries + 1):
            try:
                response = self.session.get(url, params=params, headers=headers, timeout=self.timeout)
            except requests.RequestException:
                if attempt == self.retries:
                    raise
            else:
                if response.status_code < 400:
                    return response
                if response.status_code not in (429, 500, 502, 503, 504) or attempt == self.retries:
                    raise MobilityTwinError(f"{response.status_code} for {response.url}: {response.text[:300]}")
            time.sleep(2 ** attempt)
        raise AssertionError("unreachable")

    @staticmethod
    def _path(endpoint: str) -> str:
        endpoint = endpoint.strip("/")
        if endpoint.count("/") != 1:
            raise ValueError(f"Endpoint must look like 'group/endpoint', got {endpoint!r}")
        return endpoint

    def _decode(self, endpoint: str, content: bytes, content_type: str = ""):
        fmt = self._formats.get(endpoint)
        if fmt in TEXT_FORMATS or (fmt is None and "json" in content_type):
            return json.loads(content)
        return content

    # ------------------------------------------------------------ snapshots
    def latest(self, endpoint: str) -> Tuple[Optional[str], object]:
        """(snapshot date, data) of the most recent snapshot."""
        return self.at(endpoint, None)

    def at(self, endpoint: str, when: When) -> Tuple[Optional[str], object]:
        """(snapshot date, data) of the snapshot at or just before `when`."""
        endpoint = self._path(endpoint)
        params = {"timestamp": to_epoch(when)} if when is not None else None
        response = self._request(f"{self.api_url}/{endpoint}", params)
        return (response.headers.get("X-Data-Timestamp"),
                self._decode(endpoint, response.content, response.headers.get("Content-Type", "")))

    def index(self, endpoint: str, start: When, end: When = None) -> List[Snapshot]:
        """Every snapshot between `start` and `end` (default: now), oldest first."""
        endpoint = self._path(endpoint)
        start_ts, end_ts = to_epoch(start), to_epoch(end)
        snapshots, seen = [], set()
        while True:
            page = self._request(f"{self.api_url}/{endpoint}/index",
                                 {"start_timestamp": start_ts, "end_timestamp": end_ts}).json()
            self._formats[endpoint] = page.get("format")
            for row in page["results"]:
                if row["date"] not in seen:
                    seen.add(row["date"])
                    snapshots.append(Snapshot(row["timestamp"], row["date"], row["url"]))
            if not page.get("next_start_timestamp"):
                return snapshots
            start_ts = page["next_start_timestamp"]

    def parquet_files(self, endpoint: str, start: When, end: When = None) -> List[str]:
        """URLs of the ready-made Parquet files of a range, for the endpoints that have them."""
        endpoint = self._path(endpoint)
        return self._request(f"{self.api_url}/{endpoint}/parquet",
                             {"start_timestamp": to_epoch(start), "end_timestamp": to_epoch(end)}).json()["results"]

    @staticmethod
    def sample(snapshots: List[Snapshot], every: Optional[float]) -> List[Snapshot]:
        """Keep the first snapshot of each `every`-second bucket (all of them if `every` is None)."""
        if not every or not snapshots:
            return list(snapshots)
        origin, kept, last_bucket = snapshots[0].timestamp, [], None
        for snapshot in snapshots:
            bucket = int((snapshot.timestamp - origin) // every)
            if bucket != last_bucket:
                kept.append(snapshot)
                last_bucket = bucket
        return kept

    def fetch(self, snapshot: Snapshot) -> bytes:
        """Raw bytes of one snapshot, straight from blob storage (no token needed)."""
        return self._request(snapshot.url, auth=False).content

    def iter_snapshots(self, endpoint: str, start: When, end: When = None, every: Optional[float] = None,
                       workers: int = 8) -> Iterator[Tuple[Snapshot, object]]:
        """Yield (snapshot, data) in time order without writing files."""
        endpoint = self._path(endpoint)
        snapshots = self.sample(self.index(endpoint, start, end), every)
        with ThreadPoolExecutor(max_workers=workers) as pool:
            # map() keeps order and runs up to `workers` downloads ahead.
            for snapshot, content in zip(snapshots, pool.map(self.fetch, snapshots)):
                yield snapshot, self._decode(endpoint, content)

    def download(self, endpoint: str, start: When, end: When = None, out: Union[str, Path] = "data",
                 every: Optional[float] = None, workers: int = 8, progress: bool = True) -> List[Path]:
        """Save each snapshot as out/<group>/<endpoint>/<UTC time><ext>; returns the paths in time order.

        Files already there are kept, so re-running resumes. Writes go through a
        `.part` file, so an interrupted download never leaves a truncated file.
        """
        endpoint = self._path(endpoint)
        snapshots = self.sample(self.index(endpoint, start, end), every)
        folder = Path(out) / endpoint
        folder.mkdir(parents=True, exist_ok=True)
        extension = EXTENSIONS.get(self._formats.get(endpoint), ".bin")
        targets = [folder / f"{_iso(s.timestamp)}{extension}" for s in snapshots]

        # A snapshot identical to an earlier one points at the same blob: fetch it once.
        first_path_for_url = {}
        for snapshot, target in zip(snapshots, targets):
            first_path_for_url.setdefault(snapshot.url, target)
        todo = [(s, t) for s, t in zip(snapshots, targets)
                if not t.exists() and first_path_for_url[s.url] == t]

        done, total_bytes, started = 0, 0, time.time()

        def save(item):
            snapshot, target = item
            content = self.fetch(snapshot)
            part = target.with_suffix(target.suffix + ".part")
            part.write_bytes(content)
            os.replace(part, target)
            return len(content)

        with ThreadPoolExecutor(max_workers=workers) as pool:
            for size in pool.map(save, todo):
                done += 1
                total_bytes += size
                if progress and (done % 25 == 0 or done == len(todo)):
                    print(f"\r{endpoint}: {done}/{len(todo)} downloaded, {total_bytes / 1e6:.1f} MB, "
                          f"{time.time() - started:.0f}s", end="", file=sys.stderr, flush=True)
        if progress:
            skipped = len(snapshots) - len(todo)
            print(f"\n{endpoint}: {len(snapshots)} snapshots in {folder}"
                  + (f" ({skipped} already there or identical)" if skipped else ""), file=sys.stderr)

        for snapshot, target in zip(snapshots, targets):
            source = first_path_for_url[snapshot.url]
            if not target.exists() and source.exists():
                shutil.copyfile(source, target)
        return targets

    # -------------------------------------------------------------- helpers
    @staticmethod
    def to_geodataframe(data: dict):
        """GeoJSON FeatureCollection -> GeoDataFrame (needs geopandas)."""
        import geopandas as gpd

        return gpd.GeoDataFrame.from_features(data.get("features", []), crs="EPSG:4326")


def _main(argv=None):
    parser = argparse.ArgumentParser(prog="mobilitytwin", description="MobilityTwin.Brussels data client")
    sub = parser.add_subparsers(dest="command", required=True)

    for name in ("latest", "at"):
        cmd = sub.add_parser(name, help=f"save the {'latest' if name == 'latest' else 'at-or-before'} snapshot")
        cmd.add_argument("endpoint")
        if name == "at":
            cmd.add_argument("when")
        cmd.add_argument("-o", "--output", help="file to write (default: stdout)")

    cmd = sub.add_parser("index", help="list snapshots in a range as JSON lines")
    cmd.add_argument("endpoint")
    cmd.add_argument("--start", required=True)
    cmd.add_argument("--end")

    cmd = sub.add_parser("download", help="download every snapshot in a range")
    cmd.add_argument("endpoint")
    cmd.add_argument("--start", required=True)
    cmd.add_argument("--end")
    cmd.add_argument("--every", type=float, help="keep one snapshot per N seconds")
    cmd.add_argument("--out", default="data")
    cmd.add_argument("--workers", type=int, default=8)

    # "--start -6h" would read as an unknown flag: glue relative times to their option.
    argv = list(sys.argv[1:] if argv is None else argv)
    for i, arg in enumerate(argv[:-1]):
        if arg in ("--start", "--end") and re.fullmatch(r"-\d+(\.\d+)?[smhd]", argv[i + 1]):
            argv[i:i + 2] = [f"{arg}={argv[i + 1]}", ""]
    args = parser.parse_args([a for a in argv if a != ""])
    client = MobilityTwin()

    if args.command in ("latest", "at"):
        when, data = client.at(args.endpoint, getattr(args, "when", None))
        content = data if isinstance(data, bytes) else json.dumps(data).encode()
        print(f"snapshot: {when}", file=sys.stderr)
        if args.output:
            Path(args.output).write_bytes(content)
        else:
            sys.stdout.buffer.write(content)
    elif args.command == "index":
        for snapshot in client.index(args.endpoint, args.start, args.end):
            print(json.dumps(snapshot._asdict()))
    else:
        client.download(args.endpoint, args.start, args.end, out=args.out, every=args.every, workers=args.workers)


if __name__ == "__main__":
    try:
        _main()
    except MobilityTwinError as exc:
        sys.exit(f"error: {exc}")
