mobs-ws 0.16.1__py3-none-any.whl

mobs_ws/__init__.py

@@ -0,0 +1,41 @@
+"""Official client for MOBS /v1/ws/metar (protocol 4)."""
+
+from mobs_ws.client import (
+    BACKOFF_CAP_S,
+    BACKOFF_START_S,
+    DEFAULT_URL,
+    PING_EVERY_S,
+    PONG_TIMEOUT_S,
+    QUIET_OPEN_S,
+    MetarClient,
+    MetarExample,
+    apply_awc_confirmed,
+    fetch_latest,
+    handshake_url,
+    latest_url,
+    merge_record,
+    next_backoff,
+    resolve_token,
+    should_retry,
+)
+
+__all__ = [
+    "BACKOFF_CAP_S",
+    "BACKOFF_START_S",
+    "DEFAULT_URL",
+    "PING_EVERY_S",
+    "PONG_TIMEOUT_S",
+    "QUIET_OPEN_S",
+    "MetarClient",
+    "MetarExample",
+    "apply_awc_confirmed",
+    "fetch_latest",
+    "handshake_url",
+    "latest_url",
+    "merge_record",
+    "next_backoff",
+    "resolve_token",
+    "should_retry",
+]
+
+__version__ = "0.16.1"

mobs_ws/__main__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+from mobs_ws.client import DEFAULT_URL, MetarClient, resolve_token
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="MOBS /v1/ws/metar official client")
+    parser.add_argument("--url", default=os.environ.get("MOBS_WS_URL", DEFAULT_URL))
+    parser.add_argument("--airports", default="KNYC,KLGA")
+    parser.add_argument("--token", default=None)
+    args = parser.parse_args()
+    try:
+        token = resolve_token(args.token)
+    except ValueError:
+        sys.exit("set MOBS_TOKEN or pass --token; use the placeholder YOUR_API_KEY in examples only")
+    airports = [part.strip() for part in args.airports.split(",") if part.strip()]
+    client = MetarClient(airports, token=token, url=args.url)
+    asyncio.run(client.run_forever())
+
+
+if __name__ == "__main__":
+    main()

mobs_ws/client.py

@@ -0,0 +1,368 @@
+"""Official client for MOBS /v1/ws/metar (protocol 4).
+
+Promoted from examples/ws_client.py. Uses the ``websockets`` package
+only. HTTP backfill uses urllib from the standard library.
+
+Features: JSON ping every 20 s, 15 s pong timeout, exponential backoff
+with jitter (reset after the first message or about 10 s of an open
+socket; the 10 s timer starts when the socket opens), opt-in snapshot
+and resume with since_seq and boot_id, GET /v1/metar/latest on a resume
+fallback (boot_id change, partial, or none), dedupe on icao+versions
+plus icao+obs_time+raw_metar, awc_confirmed last-wins per
+(icao, versions), station_late / station_recovered / usage
+handled (seq advances; usage is a point-in-time read), and
+unknown frame types ignored. Filter and delta are opt-in on a
+mid-session subscribe, not on the handshake query.
+
+The token comes only from the caller or the MOBS_TOKEN environment
+variable. It is never embedded.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed, InvalidStatus
+
+DEFAULT_URL = "wss://mobs.ws/v1/ws/metar"
+PING_EVERY_S = 20.0
+PONG_TIMEOUT_S = 15.0
+BACKOFF_START_S = 1.0
+BACKOFF_CAP_S = 30.0
+QUIET_OPEN_S = 10.0
+
+
+def resolve_token(token: str | None = None) -> str:
+    """Return the caller-supplied token, or MOBS_TOKEN from the environment."""
+    value = token if token not in (None, "") else os.environ.get("MOBS_TOKEN") or ""
+    if not value:
+        raise ValueError("pass a token or set MOBS_TOKEN")
+    return value
+
+
+def next_backoff(delay: float, *, rand: Callable[[], float] = random.random) -> float:
+    """Double, cap at about 30 s, then apply jitter (about 15-45 s at the cap)."""
+    grown = min(delay * 2.0, BACKOFF_CAP_S)
+    return grown * (0.5 + rand())
+
+
+def should_retry(code: int | None) -> bool:
+    return code != 4403
+
+
+def _invalid_status_code(exc: InvalidStatus) -> int | None:
+    response = getattr(exc, "response", None)
+    return getattr(response, "status_code", None)
+
+
+def connect_failure_code(exc: BaseException) -> int:
+    """Map a failed connect to a close code: 401/403 -> 4403 (stop), else 1006."""
+    if isinstance(exc, InvalidStatus) and _invalid_status_code(exc) in {401, 403}:
+        return 4403
+    return 1006
+
+
+def newer_than(incoming: dict, held: dict) -> bool:
+    """Live (or any newer versions / later body) wins over a cached or older record."""
+    if incoming.get("versions") != held.get("versions"):
+        return True
+    if (incoming.get("icao"), incoming.get("obs_time"), incoming.get("raw_metar")) != (
+        held.get("icao"),
+        held.get("obs_time"),
+        held.get("raw_metar"),
+    ):
+        return True
+    return incoming.get("_live", False) and not held.get("_live", False)
+
+
+def merge_record(latest: dict[str, dict], record: dict, *, live: bool = False) -> dict:
+    """Dedupe on icao+versions; icao+obs_time+raw_metar is the body identity."""
+    item = dict(record)
+    item["_live"] = live
+    icao = item.get("icao")
+    if not icao:
+        return latest
+    held = latest.get(icao)
+    if held is None or newer_than(item, held):
+        latest[icao] = item
+    return latest
+
+
+def apply_awc_confirmed(latest: dict[str, dict], message: dict) -> dict:
+    """Last-wins per (icao, versions). Ignore a versions the client never saw."""
+    icao = message.get("icao")
+    versions = message.get("versions")
+    if not icao or versions is None:
+        return latest
+    held = latest.get(icao)
+    if held is None or held.get("versions") != versions:
+        return latest
+    held["awc_confirmed"] = True
+    held["awc_confirmed_at"] = message.get("awc_confirmed_at")
+    return latest
+
+
+def handshake_url(
+    base: str,
+    airports: list[str],
+    *,
+    snapshot: bool = True,
+    since_seq: int | None = None,
+    boot_id: str | None = None,
+) -> str:
+    parsed = urllib.parse.urlsplit(base)
+    params = dict(urllib.parse.parse_qsl(parsed.query, keep_blank_values=True))
+    params["airports"] = ",".join(airports)
+    if snapshot:
+        params["snapshot"] = "true"
+    if since_seq is not None and boot_id:
+        params["since_seq"] = str(since_seq)
+        params["boot_id"] = boot_id
+    query = urllib.parse.urlencode(params)
+    return urllib.parse.urlunsplit((parsed.scheme, parsed.netloc, parsed.path or "/v1/ws/metar", query, ""))
+
+
+def latest_url(base: str, airports: list[str]) -> str:
+    parsed = urllib.parse.urlsplit(base)
+    scheme = "https" if parsed.scheme in {"wss", "https"} else "http"
+    netloc = parsed.netloc
+    path = "/v1/metar/latest"
+    query = urllib.parse.urlencode({"airports": ",".join(airports)})
+    return urllib.parse.urlunsplit((scheme, netloc, path, query, ""))
+
+
+def fetch_latest(url: str, token: str, airports: list[str]) -> list[dict]:
+    target = latest_url(url, airports)
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+    request = urllib.request.Request(target, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            body = json.loads(response.read().decode())
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError):
+        return []
+    return list(body.get("data") or [])
+
+
+
+def _outage_key(message: dict) -> str:
+    return str(message.get("outage_id") or message.get("icao") or "")
+
+
+class MetarClient:
+    """Reconnecting client for /v1/ws/metar."""
+
+    fetch_latest = staticmethod(fetch_latest)
+
+    def __init__(
+        self,
+        airports: list[str],
+        *,
+        token: str | None = None,
+        url: str = DEFAULT_URL,
+        snapshot: bool = True,
+        resume: bool = True,
+        on_record: Callable[[dict], Any] | None = None,
+        on_frame: Callable[[dict], Any] | None = None,
+    ) -> None:
+        self.url = url
+        self.token = resolve_token(token)
+        self.airports = [name.upper() for name in airports]
+        self.snapshot = snapshot
+        self.resume = resume
+        self.on_record = on_record
+        self.on_frame = on_frame
+        self.latest: dict[str, dict] = {}
+        self.boot_id: str | None = None
+        self.seq: int | None = None
+        self._delay = BACKOFF_START_S
+        self._stop = asyncio.Event()
+        self._ws: Any = None
+        self.last_usage: dict | None = None
+        self.last_late: dict | None = None
+        self.last_recovered: dict | None = None
+        self.lates: dict[str, dict] = {}  # latest station_late per outage_id
+
+    def handshake_url(self) -> str:
+        return handshake_url(
+            self.url,
+            self.airports,
+            snapshot=self.snapshot,
+            since_seq=self.seq if self.resume else None,
+            boot_id=self.boot_id if self.resume else None,
+        )
+
+    def handle_frame(self, message: dict) -> None:
+        kind = message.get("type")
+        if kind == "subscription_updated":
+            if message.get("boot_id"):
+                self.boot_id = message["boot_id"]
+            # Do not take seq from subscription_updated: it is the server's
+            # current seq, and would skip replay frames not yet received.
+        elif kind == "resume":
+            self._apply_resume(self.fetch_latest(self.url, self.token, self.airports))
+        elif kind == "new_metar_arrived":
+            live = message.get("cached") is False and message.get("replay") is False
+            replayed = message.get("replay") is True
+            for rec in message.get("data") or []:
+                before = self.latest.get(rec.get("icao") or "")
+                merge_record(self.latest, rec, live=live)
+                self._emit(rec.get("icao"), before)
+            if (live or replayed) and message.get("seq") is not None:
+                self._advance_seq(message["seq"])
+        elif kind == "awc_confirmed":
+            if message.get("seq") is not None:
+                self._advance_seq(message["seq"])
+            icao = message.get("icao")
+            before = dict(self.latest[icao]) if icao and icao in self.latest else None
+            apply_awc_confirmed(self.latest, message)
+            self._emit(icao, before)
+        elif kind in {"station_late", "station_recovered", "usage"}:
+            if message.get("seq") is not None:
+                self._advance_seq(message["seq"])
+            if kind == "usage":
+                self.last_usage = message
+            elif kind == "station_late":
+                self.last_late = message
+                self.lates[_outage_key(message)] = message
+            else:
+                self.last_recovered = message
+                key = _outage_key(message)
+                self.lates.pop(key, None)
+                held = self.last_late
+                if held is not None and _outage_key(held) == key:
+                    self.last_late = None
+        # Unknown types (pong, server_notice, error, and any later type) are ignored.
+        if self.on_frame is not None:
+            self.on_frame(message)
+
+    def _advance_seq(self, seq: int) -> None:
+        if self.seq is None or seq > self.seq:
+            self.seq = seq
+
+    def _apply_resume(self, rows: list[dict]) -> None:
+        for rec in rows:
+            before = self.latest.get(rec.get("icao") or "")
+            merge_record(self.latest, rec, live=False)
+            self._emit(rec.get("icao"), before)
+
+    async def _handle_message(self, message: dict) -> None:
+        if message.get("type") == "resume":
+            rows = await asyncio.to_thread(self.fetch_latest, self.url, self.token, self.airports)
+            self._apply_resume(rows)
+            if self.on_frame is not None:
+                self.on_frame(message)
+            return
+        self.handle_frame(message)
+
+    def _emit(self, icao: str | None, before: dict | None) -> None:
+        if not icao or self.on_record is None:
+            return
+        held = self.latest.get(icao)
+        if held is not None and held is not before and held != before:
+            self.on_record(held)
+
+    async def request_usage(self) -> None:
+        """Send {"action":"usage"} on the open socket, if any."""
+        ws = self._ws
+        if ws is not None:
+            await ws.send(json.dumps({"action": "usage"}))
+
+    async def subscribe(self, icaos: list[str] | None = None, **fields: Any) -> None:
+        """Send a mid-session subscribe. Pass filter= or delta= to opt in."""
+        ws = self._ws
+        if ws is None:
+            return
+        body: dict[str, Any] = {"action": "subscribe", "icaos": list(icaos or [])}
+        body.update(fields)
+        await ws.send(json.dumps(body))
+
+    def stop(self) -> None:
+        self._stop.set()
+        ws = self._ws
+        if ws is not None:
+            try:
+                asyncio.get_running_loop().create_task(ws.close())
+            except RuntimeError:
+                pass
+
+    async def _session(self) -> str | int | None:
+        headers = {"Authorization": f"Bearer {self.token}"}
+        opened: float | None = None
+        saw_message = False
+        ping_task: asyncio.Task | None = None
+        try:
+            async with connect(self.handshake_url(), additional_headers=headers) as ws:
+                opened = time.monotonic()
+                self._ws = ws
+
+                async def heartbeat() -> None:
+                    while True:
+                        await asyncio.sleep(PING_EVERY_S)
+                        if self._stop.is_set():
+                            return
+                        await ws.send(json.dumps({"action": "ping"}))
+                        try:
+                            await asyncio.wait_for(pong.wait(), timeout=PONG_TIMEOUT_S)
+                        except asyncio.TimeoutError:
+                            await ws.close(code=1001, reason="pong timeout")
+                            return
+                        finally:
+                            pong.clear()
+
+                pong = asyncio.Event()
+                ping_task = asyncio.create_task(heartbeat())
+                async for text in ws:
+                    if self._stop.is_set():
+                        break
+                    if not saw_message:
+                        saw_message = True
+                        self._delay = BACKOFF_START_S
+                    message = json.loads(text)
+                    if message.get("type") == "pong":
+                        pong.set()
+                    await self._handle_message(message)
+        except ConnectionClosed as exc:
+            if saw_message or (opened is not None and time.monotonic() - opened >= QUIET_OPEN_S):
+                self._delay = BACKOFF_START_S
+            return exc.rcvd.code if exc.rcvd is not None else exc.sent.code if exc.sent is not None else 1006
+        except (InvalidStatus, OSError, TimeoutError, asyncio.TimeoutError) as exc:
+            return connect_failure_code(exc)
+        finally:
+            self._ws = None
+            if ping_task is not None:
+                ping_task.cancel()
+        if opened is not None and (saw_message or time.monotonic() - opened >= QUIET_OPEN_S):
+            self._delay = BACKOFF_START_S
+        return None
+
+    async def run_forever(self) -> None:
+        self._stop = asyncio.Event()
+        while not self._stop.is_set():
+            code = await self._session()
+            if self._stop.is_set():
+                return
+            if not should_retry(code if isinstance(code, int) else None):
+                return
+            wait = self._delay * (0.5 + random.random())
+            self._delay = min(self._delay * 2.0, BACKOFF_CAP_S)
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=wait)
+                return
+            except asyncio.TimeoutError:
+                pass
+
+
+class MetarExample(MetarClient):
+    """Backward-compatible constructor: (url, token, airports)."""
+
+    def __init__(self, url: str, token: str, airports: list[str], **kwargs) -> None:
+        super().__init__(airports, token=token, url=url, **kwargs)

mobs_ws-0.16.1.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: mobs-ws
+Version: 0.16.1
+Summary: Official client for the MOBS /v1/ws/metar WebSocket (protocol 4).
+Author-email: MOBS <admin@mobs.ws>
+License-Expression: MIT
+Project-URL: Homepage, https://mobs.ws
+Project-URL: Documentation, https://docs.mobs.ws/websocket
+Project-URL: Repository, https://github.com/mobs-ws/mobs-sdks
+Project-URL: Issues, https://github.com/mobs-ws/mobs-sdks/issues
+Keywords: mobs,metar,websocket
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=17.3
+Dynamic: license-file
+
+# mobs-ws
+
+Official Python client for the MOBS `/v1/ws/metar` WebSocket (protocol 4).
+
+The only runtime dependency is `websockets`. HTTP backfill uses urllib from
+the standard library. Snapshot and resume are opt-in. The client applies
+`awc_confirmed` frames last-wins per (`icao`, `versions`), handles
+`station_late`, `station_recovered`, and `usage` (use `request_usage()`),
+and ignores unknown frame types. Late alerts are kept as the latest frame per `outage_id` and cleared on `station_recovered`. More than one `station_late` can arrive in the same outage. A change-only `filter` and parsed
+`delta` are opt-in on a mid-session `subscribe`, not on the handshake.
+
+The API key is never embedded. Pass it to the constructor, or set
+`MOBS_TOKEN`.
+
+```bash
+pip install mobs-ws
+export MOBS_TOKEN=$MOBS_TOKEN
+```
+
+```python
+import asyncio
+import os
+
+from mobs_ws import MetarClient
+
+async def main():
+    client = MetarClient(
+        airports=["KNYC", "KLGA"],
+        token=os.environ["MOBS_TOKEN"],  # or token="YOUR_API_KEY"
+        snapshot=True,
+        resume=True,
+        on_record=lambda rec: print(rec["icao"], rec["raw_metar"], rec.get("awc_confirmed")),
+    )
+    await client.run_forever()
+
+asyncio.run(main())
+```
+
+```bash
+python -m mobs_ws --airports KNYC,KLGA
+```
+
+MIT licensed. See [LICENSE](https://github.com/mobs-ws/mobs-sdks/blob/main/LICENSE).

mobs_ws-0.16.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+mobs_ws/__init__.py,sha256=7yYKkgFVvARmyQQtG9u7kttzwUce2URcZhAgFRNvfN0,759
+mobs_ws/__main__.py,sha256=Xt7lsR-7i-ZSN_ItPXuy7P2hgVoBAmekmlD1r_PWzCo,887
+mobs_ws/client.py,sha256=LQk_qqMiAuXRTbezl0eYoNFuQpLuNTehzFDwNk4I5PM,14126
+mobs_ws-0.16.1.dist-info/licenses/LICENSE,sha256=dw8JDhF6WUev5XCo8VXWjhIoWrKnhggaf8uGqlFVxjU,1061
+mobs_ws-0.16.1.dist-info/METADATA,sha256=gOYIQbeJiX90w2j3K0jrkD2QPbf97vQ9pLtRkrS54kk,2180
+mobs_ws-0.16.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mobs_ws-0.16.1.dist-info/entry_points.txt,sha256=R1cAdC_WXpxwzRsEqyNFKozBcuOJbetN1yIqsX647eA,50
+mobs_ws-0.16.1.dist-info/top_level.txt,sha256=vh74LSgCI8r4NLZ85fXiV3tdqyJu_Q3zLtKPyjEC3T8,8
+mobs_ws-0.16.1.dist-info/RECORD,,

mobs_ws-0.16.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mobs_ws-0.16.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mobs-ws = mobs_ws.__main__:main

mobs_ws-0.16.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MOBS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mobs_ws-0.16.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mobs_ws