mobs-ws 0.16.1__tar.gz

mobs_ws-0.16.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,43 @@
+# 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/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "mobs-ws"
+version = "0.16.1"
+description = "Official client for the MOBS /v1/ws/metar WebSocket (protocol 4)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{name = "MOBS", email = "admin@mobs.ws"}]
+dependencies = [
+    "websockets>=17.3",
+]
+keywords = ["mobs", "metar", "websocket"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet",
+]
+
+[project.urls]
+Homepage = "https://mobs.ws"
+Documentation = "https://docs.mobs.ws/websocket"
+Repository = "https://github.com/mobs-ws/mobs-sdks"
+Issues = "https://github.com/mobs-ws/mobs-sdks/issues"
+
+[project.scripts]
+mobs-ws = "mobs_ws.__main__:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mobs_ws-0.16.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mobs_ws-0.16.1/src/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-0.16.1/src/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-0.16.1/src/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/src/mobs_ws.egg-info/PKG-INFO

@@ -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/src/mobs_ws.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/mobs_ws/__init__.py
+src/mobs_ws/__main__.py
+src/mobs_ws/client.py
+src/mobs_ws.egg-info/PKG-INFO
+src/mobs_ws.egg-info/SOURCES.txt
+src/mobs_ws.egg-info/dependency_links.txt
+src/mobs_ws.egg-info/entry_points.txt
+src/mobs_ws.egg-info/requires.txt
+src/mobs_ws.egg-info/top_level.txt
+tests/test_client.py

mobs_ws-0.16.1/src/mobs_ws.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mobs_ws-0.16.1/src/mobs_ws.egg-info/entry_points.txt

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

mobs_ws-0.16.1/src/mobs_ws.egg-info/requires.txt

@@ -0,0 +1 @@
+websockets>=17.3

mobs_ws-0.16.1/src/mobs_ws.egg-info/top_level.txt

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

mobs_ws-0.16.1/tests/test_client.py

@@ -0,0 +1,173 @@
+"""Self-contained unit tests for the mobs-ws Python client (no MOBS server needed)."""
+from __future__ import annotations
+
+import asyncio
+import socket
+import tomllib
+from pathlib import Path
+
+import pytest
+
+import mobs_ws
+from mobs_ws import (
+    MetarClient,
+    apply_awc_confirmed,
+    handshake_url,
+    latest_url,
+    merge_record,
+    resolve_token,
+    should_retry,
+)
+
+PKG = Path(__file__).resolve().parent.parent
+
+
+def test_metadata_is_publish_ready():
+    data = tomllib.loads((PKG / "pyproject.toml").read_text())
+    project = data["project"]
+    assert project["name"] == "mobs-ws"
+    assert project["version"] == mobs_ws.__version__
+    assert project["dependencies"] == ["websockets>=17.3"]
+    assert project["license"] == "MIT"
+    assert project["urls"]["Repository"] == "https://github.com/mobs-ws/mobs-sdks"
+    assert (PKG / "LICENSE").is_file()
+
+
+def test_token_comes_from_caller_or_env(monkeypatch):
+    monkeypatch.delenv("MOBS_TOKEN", raising=False)
+    with pytest.raises(ValueError, match="MOBS_TOKEN"):
+        resolve_token(None)
+    with pytest.raises(ValueError, match="MOBS_TOKEN"):
+        resolve_token("")
+    monkeypatch.setenv("MOBS_TOKEN", "from-env")
+    assert resolve_token(None) == "from-env"
+    assert resolve_token("from-caller") == "from-caller"
+
+
+def test_merge_confirm_and_unknown_types():
+    latest = {}
+    merge_record(latest, {"icao": "KNYC", "versions": "v0", "obs_time": "t", "raw_metar": "A"}, live=False)
+    assert latest["KNYC"]["raw_metar"] == "A"
+    merge_record(latest, {"icao": "KNYC", "versions": "v1", "obs_time": "t", "raw_metar": "B"}, live=True)
+    assert latest["KNYC"]["raw_metar"] == "B"
+    apply_awc_confirmed(latest, {"icao": "KNYC", "versions": "v1", "awc_confirmed_at": "t1"})
+    assert latest["KNYC"]["awc_confirmed"] is True and latest["KNYC"]["awc_confirmed_at"] == "t1"
+    apply_awc_confirmed(latest, {"icao": "KNYC", "versions": "v1", "awc_confirmed_at": "t2"})
+    assert latest["KNYC"]["awc_confirmed_at"] == "t2"
+    apply_awc_confirmed(latest, {"icao": "KNYC", "versions": "v9", "awc_confirmed_at": "nope"})
+    assert latest["KNYC"]["awc_confirmed_at"] == "t2"
+    client = MetarClient(["KNYC"], token="YOUR_API_KEY", url="ws://127.0.0.1:9/v1/ws/metar")
+    client.latest = latest
+    client.handle_frame({"type": "not_a_real_type", "seq": 99})
+    assert latest["KNYC"]["awc_confirmed_at"] == "t2"
+    assert should_retry(4008) and not should_retry(4403)
+    url = handshake_url("wss://mobs.ws/v1/ws/metar", ["KNYC"], snapshot=True, since_seq=4, boot_id="abcd")
+    assert "snapshot=true" in url and "since_seq=4" in url and "boot_id=abcd" in url
+    assert latest_url("wss://mobs.ws/v1/ws/metar", ["KNYC"]).startswith("https://mobs.ws/v1/metar/latest")
+
+
+def test_seq_advances_only_from_received_replay_or_live():
+    client = MetarClient(["KNYC"], token="YOUR_API_KEY", url="ws://127.0.0.1:9/v1/ws/metar")
+    client.seq = 2
+    client.handle_frame(
+        {"type": "subscription_updated", "icaos": ["KNYC"], "boot_id": "boot", "seq": 80, "resume": "full", "replayed": 80}
+    )
+    assert client.boot_id == "boot"
+    assert client.seq == 2
+    rec = {"icao": "KNYC", "versions": "v1", "obs_time": "t", "raw_metar": "A"}
+    client.handle_frame({"type": "new_metar_arrived", "cached": False, "replay": True, "seq": 5, "data": [rec]})
+    assert client.seq == 5
+    client.handle_frame({"type": "new_metar_arrived", "cached": True, "replay": False, "seq": 80, "data": [rec]})
+    assert client.seq == 5
+    client.handle_frame({"type": "new_metar_arrived", "cached": False, "replay": False, "seq": 6, "data": [rec]})
+    assert client.seq == 6
+    client.handle_frame({"type": "awc_confirmed", "icao": "KNYC", "versions": "v1", "awc_confirmed_at": "t", "seq": 7})
+    assert client.seq == 7
+
+
+def _closed_port() -> int:
+    sock = socket.socket()
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+    return port
+
+
+async def _http_status_server(status: int):
+    async def handler(reader, writer):
+        try:
+            await asyncio.wait_for(reader.read(4096), timeout=1)
+        except Exception:
+            pass
+        try:
+            writer.write(f"HTTP/1.1 {status} test\r\nConnection: close\r\n\r\n".encode())
+            await writer.drain()
+            writer.close()
+            await writer.wait_closed()
+        except Exception:
+            pass
+
+    server = await asyncio.start_server(handler, "127.0.0.1", 0)
+    return server, server.sockets[0].getsockname()[1]
+
+
+async def _run_counted(client: MetarClient, n: int, timeout: float = 5) -> list[int | None]:
+    codes: list[int | None] = []
+    original = MetarClient._session
+
+    async def wrapped(_self=client):
+        code = await original(_self)
+        codes.append(code)
+        if len(codes) >= n:
+            _self.stop()
+        return code
+
+    client._session = wrapped  # type: ignore[method-assign]
+    client._delay = 0.01
+    await asyncio.wait_for(client.run_forever(), timeout=timeout)
+    return codes
+
+
+def _client(url: str) -> MetarClient:
+    return MetarClient(["KNYC"], token="local-test-token", url=url, snapshot=False, resume=False)
+
+
+def test_connect_refused_502_and_401_do_not_escape_run_forever():
+    async def run():
+        codes = await _run_counted(_client(f"ws://127.0.0.1:{_closed_port()}/v1/ws/metar"), 2)
+        assert codes[0] == 1006 and len(codes) >= 2
+
+        server, port = await _http_status_server(502)
+        try:
+            codes = await _run_counted(_client(f"ws://127.0.0.1:{port}/v1/ws/metar"), 2)
+            assert codes[0] == 1006 and len(codes) >= 2
+        finally:
+            server.close()
+            await server.wait_closed()
+
+        server, port = await _http_status_server(401)
+        try:
+            codes = await _run_counted(_client(f"ws://127.0.0.1:{port}/v1/ws/metar"), 2)
+            assert codes == [4403]
+        finally:
+            server.close()
+            await server.wait_closed()
+
+    asyncio.run(run())
+
+
+def test_connect_asyncio_timeout_backs_off(monkeypatch):
+    class _Boom:
+        async def __aenter__(self):
+            raise asyncio.TimeoutError()
+
+        async def __aexit__(self, *_exc):
+            return None
+
+    monkeypatch.setattr("mobs_ws.client.connect", lambda *_a, **_k: _Boom())
+
+    async def run():
+        codes = await _run_counted(_client("ws://127.0.0.1:9/v1/ws/metar"), 2)
+        assert codes[0] == 1006 and len(codes) >= 2
+
+    asyncio.run(run())