MouseTools 6.1.0__tar.gz → 6.2.0__tar.gz

{mousetools-6.1.0 → mousetools-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mousetools
-Version: 6.1.0
+Version: 6.2.0
 Summary: An unofficial Python wrapper for Disney's API
 Author: Scott Caratozzolo
 License-Expression: MIT
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Operating System :: OS Independent
 Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.11

{mousetools-6.1.0 → mousetools-6.2.0}/mousetools/__init__.py

@@ -44,6 +44,9 @@ from mousetools.entities import (
     PriceRange,
     Recreation,
     RecreationActivity,
+    RelatedAncestor,
+    RelatedCoordinate,
+    RelatedLocation,
     Resort,
     ResortArea,
     Restaurant,
@@ -137,6 +140,9 @@ __all__ = [
     "RawChange",
     "Recreation",
     "RecreationActivity",
+    "RelatedAncestor",
+    "RelatedCoordinate",
+    "RelatedLocation",
     "Resort",
     "ResortArea",
     "Restaurant",

{mousetools-6.1.0 → mousetools-6.2.0}/mousetools/_internal/services/ids.py

@@ -1,8 +1,14 @@
-"""Couchbase channel-id construction and entity-id parsing (pure string ops)."""
+"""Couchbase channel-id construction, and entity-id and doc-id parsing."""
+
+import logging
+import re
+from dataclasses import dataclass
 
 from mousetools.enums import ChannelSource
 from mousetools.errors import InvalidFilterError
 
+logger = logging.getLogger("mousetools.stream.ids")
+
 DOCS_URL = "https://caratozzoloxyz.gitlab.io/public/MouseTools/guides/streaming/"
 
 _VERSION = "1_0"
@@ -266,3 +272,142 @@ def parent_keyed_channel_id(dest: str, source: ChannelSource, parent_id: str, pa
     else:
         composed = f"{parent_id}{_TYPE_CLAUSE}{parent_type}"
     return f"{dest}.{source}.{composed}.{_VERSION}"
+
+
+_VERSION_SEGMENT = re.compile(r"^\d+_\d+$")
+# Matched by shape, not a per-source table, so new versions need no table update.
+# Case-insensitive because wire ids have been seen with inconsistent casing (#32).
+_LANG_SEGMENT = re.compile(r"^[a-z]{2}_[a-z]{2}$", re.IGNORECASE)
+
+
+@dataclass(frozen=True, slots=True)
+class DocId:
+    """The parsed components of a sync-gateway document id.
+
+    Every field is the raw wire string, never a coerced enum -- `build_event` does
+    that conversion. A doc id is `{destination}.{source}.{version}[.{lang}][.{type-slug}].{entity}[{suffix}]`,
+    where the language may appear EITHER as a leading segment (`en_us`) or as a
+    trailing suffix (`.en.us`), depending on the source's schema version. A
+    parent-keyed source inserts a composed `{parent}` segment before `{version}`,
+    reported as `parent_id` with extra clauses dropped. `parent_id` is None for
+    every other source, and for a parent segment that isn't a complete
+    `<id>;entityType=<type>` clause or isn't followed by a `<major>_<minor>`
+    version (`version` itself is reported as found).
+    """
+
+    destination: str | None
+    source: str
+    version: str | None
+    language: str | None
+    entity_id: str | None
+    entity_type: str | None
+    parent_id: str | None = None
+
+    @classmethod
+    def parse(cls, doc_id: str) -> "DocId":
+        """Parse a sync-gateway document id into its components.
+
+        Compound ids (`A;entityType=X:B;entityType=Y`) describe the PRIMARY half
+        only; extra clauses such as `;destination=wdw` are ignored. A parent-keyed
+        source (`SOURCE_PARENT_KEYED`, e.g. `arrivals`) embeds a composed parent
+        id before the version token, shifting every later segment by one; it is
+        reported as `parent_id` (e.g. `"80010388;entityType=resort"`).
+
+        Args:
+            doc_id: e.g. `wdw.facilities.1_0.en_us.attraction.80010177;entityType=Attraction`.
+
+        Returns:
+            The parsed `DocId`; every component is `None` when absent.
+        """
+        parts = doc_id.split(".")
+        source = parts[1] if len(parts) > 1 else ""
+        parent_keyed = SOURCE_PARENT_KEYED.get(source, False)
+        version_idx = 3 if parent_keyed else 2
+        parent_id = _parent_id(parts) if parent_keyed else None
+        version = parts[version_idx] if len(parts) > version_idx else None
+        idx = version_idx + 1
+
+        language: str | None = None
+        if idx < len(parts) and _LANG_SEGMENT.match(parts[idx]):
+            language = parts[idx].casefold()
+            idx += 1
+        if SOURCE_HAS_TYPE_SLUG.get(source, False):
+            idx += 1
+
+        tail = ".".join(parts[idx:]) if len(parts) > idx else ""
+        suffix = SOURCE_ID_SUFFIX.get(source, "")
+        if suffix and tail.casefold().endswith(suffix.casefold()):
+            tail = strip_id_suffix(tail, suffix)
+            language = language or suffix.lstrip(".").replace(".", "_").casefold()
+
+        primary, _ = split_compound(tail)
+        segments = primary.split(";")
+        entity_type = _type_clause(primary)
+        return cls(
+            # `"".split(".")` is `[""]`, so parts[0] is always present but may be empty.
+            destination=parts[0] or None,
+            source=source,
+            version=version or None,
+            language=language,
+            entity_id=segments[0] or None,
+            entity_type=entity_type,
+            parent_id=parent_id,
+        )
+
+
+def parent_from_channel_id(channel: str) -> str | None:
+    """Extract the composed parent id from a parent-keyed channel id.
+
+    The inverse of `parent_keyed_channel_id`:
+    `"wdw.arrivals.80010388;entityType=resort.1_0"` -> `"80010388;entityType=resort"`.
+    Also accepts a full parent-keyed doc id, which shares the channel's prefix.
+
+    Args:
+        channel: A sync-gateway channel id.
+
+    Returns:
+        The composed parent id, or None if `channel` is not a parent-keyed
+        channel, has no `<major>_<minor>` version segment, or its parent is not a complete
+        `<id>;entityType=<type>` clause.
+    """
+    return DocId.parse(channel).parent_id
+
+
+def _parent_id(parts: list[str]) -> str | None:
+    """The composed parent id from a parent-keyed id's dot-split segments, or None.
+
+    Args:
+        parts: The id split on `.`: `[dest, source, parent, version, ...]`.
+
+    Returns:
+        `<id>;entityType=<type>` from the parent segment, with any extra clauses or
+        compound half dropped, when it is followed by a `<major>_<minor>` version
+        segment; else None, logged at DEBUG.
+    """
+    if len(parts) < 4 or not _VERSION_SEGMENT.match(parts[3]):
+        logger.debug("parent-keyed id %r has no version segment after its parent", ".".join(parts))
+        return None
+    primary, _ = split_compound(parts[2])
+    numeric = primary.split(";", 1)[0]
+    entity_type = _type_clause(primary)
+    if not numeric or not entity_type:
+        logger.debug("parent-keyed id %r has an incomplete parent %r", ".".join(parts), parts[2])
+        return None
+    return f"{numeric}{_TYPE_CLAUSE}{entity_type}"
+
+
+def _type_clause(primary: str) -> str | None:
+    """The value of the `entityType=` clause in a simple id, wherever it appears.
+
+    Args:
+        primary: A simple (non-compound) id such as `"1;destination=wdw;entityType=resort"`.
+
+    Returns:
+        The last `entityType=` value among the id's clauses, or None if it has none
+        or it is empty.
+    """
+    entity_type: str | None = None
+    for segment in primary.split(";")[1:]:
+        if segment.startswith("entityType="):
+            entity_type = segment.split("=", 1)[1]
+    return entity_type or None

{mousetools-6.1.0 → mousetools-6.2.0}/mousetools/_internal/stream/protocol.py

@@ -101,7 +101,6 @@ class BlipProtocol:
         self._out_no = 0
         self._my_reqs: dict[int, str] = {}
         self._caught_up = False
-        self.last_seq = since
         self._recv_bytes: dict[tuple[bool, int], int] = {}
         self._acked: dict[tuple[bool, int], int] = {}
 
@@ -210,9 +209,6 @@ class BlipProtocol:
     def _on_rev(self, msg: codec.Message, out: ProtocolOutput) -> None:
         if not msg.noreply:
             out.frames.append(self._enc.frame(codec.RPY, msg.msg_no, {}, b""))
-        seq = msg.props.get("sequence", "")
-        if seq:
-            self.last_seq = seq
         try:
             body = json.loads(msg.body) if msg.body else {}
         except ValueError:
@@ -221,7 +217,7 @@ class BlipProtocol:
             RawChange(
                 doc_id=msg.props.get("id", ""),
                 rev=msg.props.get("rev", ""),
-                sequence=seq,
+                sequence=msg.props.get("sequence", ""),
                 deleted=msg.props.get("deleted") == "1",
                 body=body if isinstance(body, dict) else {},
             )

{mousetools-6.1.0 → mousetools-6.2.0}/mousetools/client.py

@@ -553,20 +553,17 @@ class Client:
             inflight.pop(key, None)
         return await fut
 
-    async def _changes_feed(self, source: ChannelSource, *, refresh: bool = False) -> dict:
+    async def _changes_feed(self, source: ChannelSource) -> dict:
         """The `_changes` feed for this destination's `source` parent channel, cached.
 
         The feed is identical for every parent/type query in a destination
         (filtering is client-side), so it is cached per parent channel id with
         a `SOURCE_CADENCE[source]`-derived TTL and single-flighted through
         `_coalesce`: concurrent callers share one pull instead of each
-        re-enumerating the full feed. `refresh=True` evicts the cached entry and
-        falls through to that same shared pull -- so a refresh racing an in-flight
-        pull joins it rather than starting a redundant second enumeration.
+        re-enumerating the full feed.
 
         Args:
             source: The `ChannelSource` whose parent-channel feed to fetch.
-            refresh: Force a re-fetch even if the cached feed is still fresh.
 
         Returns:
             The parsed `_changes` feed (`{"results": [...], "last_seq": ...}`).
@@ -578,15 +575,9 @@ class Client:
         """
         parent_cid = ids.parent_channel_id(self.destination.value, source, multi_language=ids.SOURCE_MULTI_LANG[source])
         now = time.time()
-        if refresh:
-            # Drop the cached entry and fall through to the shared single-flight,
-            # mirroring _evict_if_stale -> _fetch_shard. Deliberately NOT a second
-            # pull: if one is already in flight it IS a fresh read, so join it.
-            self._feed_cache.pop(parent_cid, None)
-        else:
-            cached = self._feed_cache.get(parent_cid)
-            if cached is not None and cached[0] > now:
-                return cached[1]
+        cached = self._feed_cache.get(parent_cid)
+        if cached is not None and cached[0] > now:
+            return cached[1]
 
         async def _pull() -> dict:
             headers = await self._sync_headers()

{mousetools-6.1.0 → mousetools-6.2.0}/mousetools/entities/__init__.py

@@ -1,5 +1,6 @@
 """Domain entities and value objects."""
 
+from mousetools.entities.arrivals import ArrivalPrediction, DestinationArrival, TransportArrivals, TransportService
 from mousetools.entities.attraction import Attraction
 from mousetools.entities.base import Entity, entity_for, load_many
 from mousetools.entities.basic import EntertainmentVenue, Land, Resort, ResortArea, WaterPark
@@ -11,6 +12,7 @@ from mousetools.entities.facility import FacilityEntity
 from mousetools.entities.menu import Menu, MenuCollection, MenuGroup, MenuItem, MenuPrice, PriceRange
 from mousetools.entities.names import NameParts
 from mousetools.entities.poi import PointOfInterest
+from mousetools.entities.related import RelatedAncestor, RelatedCoordinate, RelatedLocation
 from mousetools.entities.restaurant import Restaurant
 from mousetools.entities.search import SearchResponse, SearchResult
 from mousetools.entities.themepark import ThemePark
@@ -33,17 +35,13 @@ from mousetools.entities.types import (
 )
 from mousetools.entities.values import (
     Appearance,
-    ArrivalPrediction,
     CalendarSchedule,
     Coordinates,
     DailySchedule,
-    DestinationArrival,
     Forecast,
     ForecastPoint,
     PartySizeStatus,
     ScheduleSegment,
-    TransportArrivals,
-    TransportService,
     WaitTime,
     WalkUpAvailability,
 )
@@ -90,6 +88,9 @@ __all__ = [
     "PriceRange",
     "Recreation",
     "RecreationActivity",
+    "RelatedAncestor",
+    "RelatedCoordinate",
+    "RelatedLocation",
     "Resort",
     "ResortArea",
     "Restaurant",

mousetools-6.2.0/mousetools/entities/_parse.py

@@ -0,0 +1,177 @@
+"""Lenient coercers shared by the value objects: bad input degrades (to None, or [] for lists), never raises.
+
+Present-but-unusable input logs at DEBUG; absent input (None) stays silent.
+"""
+
+import logging
+import re
+import reprlib
+from datetime import datetime, time
+from zoneinfo import ZoneInfo
+
+from dateutil.parser import isoparse
+
+# Kept under the name these coercers logged as before moving out of values.py.
+logger = logging.getLogger("mousetools.entities.values")
+
+_PLAIN_INT = re.compile(r"^-?[0-9]+$")
+_REPR = reprlib.Repr()  # constructor keywords are 3.12+; attributes work on 3.11
+_REPR.maxstring = _REPR.maxother = 80
+_REPR.maxlist = _REPR.maxdict = 5
+
+
+def clip(value: object) -> str:
+    """A length-capped repr of `value` for DEBUG lines about bad input.
+
+    Args:
+        value: The value to describe.
+
+    Returns:
+        `repr(value)`, shortened with `...` when long.
+    """
+    return _REPR.repr(value)
+
+
+def parse_dt(value: object, tz: ZoneInfo) -> datetime | None:
+    """Parse an ISO-8601 string to a tz-aware datetime in `tz`.
+
+    Converts (astimezone), never relabels — fixes v5's `.replace(tzinfo=...)` bug.
+    Empty/invalid -> None.
+
+    Args:
+        value: The raw ISO-8601 string from a couchbase doc, or None/empty.
+        tz: Timezone the parsed datetime is converted into.
+
+    Returns:
+        The tz-aware datetime, or None if `value` is absent or unparseable.
+    """
+    if not value:
+        return None
+    if not isinstance(value, str):
+        logger.debug("unparseable datetime %r (not a string)", value)
+        return None
+    try:
+        return isoparse(value).astimezone(tz)
+    except (ValueError, TypeError) as exc:
+        logger.debug("unparseable datetime %r (%s)", value, exc)
+        return None
+
+
+def parse_duration(value: object) -> time | None:
+    """Parse a facilities `duration` (`"HH:MM:SS"`) to a `time`, or None if absent/invalid.
+
+    Args:
+        value: The raw `"HH:MM:SS"` duration string, or None/empty.
+
+    Returns:
+        The parsed time, or None if `value` is absent or unparseable.
+    """
+    if not value:
+        return None
+    if not isinstance(value, str):
+        logger.debug("unparseable duration %r (not a string)", value)
+        return None
+    try:
+        return time.fromisoformat(value)
+    except (ValueError, TypeError) as exc:
+        logger.debug("unparseable duration %r (%s)", value, exc)
+        return None
+
+
+def parse_status(value: object) -> str | None:
+    """A facility-status doc's `status` string, or None if absent/non-string.
+
+    Plain type coercion, not a leak guard: `couchbase.bulk_get` already drops a
+    not-found error part (`{"error": "not_found", "status": 404, ...}`) at the
+    fetch boundary, so a genuinely-absent `facilitystatus` doc reaches here as
+    `None` (via `WaitTime.from_doc`'s / the `Field` transform's `not doc` short
+    circuit), never as that error body's numeric `status: 404`. This still
+    guards defensively against any doc whose `status` key is present but
+    non-string for some other reason -- a genuine status is always a string, so
+    anything else is treated as absent.
+
+    Args:
+        value: The raw `status` value from a couchbase doc.
+
+    Returns:
+        `value` unchanged if it's a string, else None.
+    """
+    return as_str(value)
+
+
+def as_float(value: object) -> float | None:
+    """Coerce a couchbase string/number to float, or None if absent/invalid.
+
+    Args:
+        value: The raw value to coerce.
+
+    Returns:
+        The coerced float, or None if `value` isn't an int/float/str or isn't
+        parseable as a float.
+    """
+    if value is None or value == "":  # noqa: PLC1901 -- `not value` would also swallow 0/0.0
+        return None
+    if not isinstance(value, int | float | str):
+        logger.debug("uncoercible float %r (unsupported type %s)", value, type(value).__name__)
+        return None
+    try:
+        return float(value)
+    except (ValueError, OverflowError) as exc:
+        logger.debug("uncoercible float %r (%s)", value, exc)
+        return None
+
+
+def as_int(value: object) -> int | None:
+    """Coerce a couchbase number or plain-digit string to int, or None if absent/invalid.
+
+    Args:
+        value: The raw value to coerce.
+
+    Returns:
+        The int, or None if `value` is a bool, a non-integral float, a string that
+        isn't plain ASCII digits (an optional leading `-`), or any other type.
+    """
+    if value is None or value == "":  # noqa: PLC1901 -- `not value` would also swallow 0
+        return None
+    if isinstance(value, bool):
+        logger.debug("uncoercible int %s", clip(value))
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str) and _PLAIN_INT.match(value):
+        return int(value)
+    logger.debug("uncoercible int %s", clip(value))
+    return None
+
+
+def as_str(value: object) -> str | None:
+    """`value` if it is a string, else None.
+
+    Args:
+        value: The raw value expected to be a string.
+
+    Returns:
+        `value` unchanged if it's a string, else None.
+    """
+    if value is None or isinstance(value, str):
+        return value
+    logger.debug("non-string value %s; treating as absent", clip(value))
+    return None
+
+
+def as_list(raw: object) -> list[object]:
+    """`raw` if it is a list, else an empty list, for iterating optional doc arrays.
+
+    Args:
+        raw: A raw couchbase value expected to be a list.
+
+    Returns:
+        `raw` unchanged if it is a list, else `[]`.
+    """
+    if isinstance(raw, list):
+        return raw
+    if raw is not None:
+        logger.debug("expected a list, got %s; treating as empty", clip(raw))
+    return []

mousetools-6.2.0/mousetools/entities/arrivals.py

@@ -0,0 +1,143 @@
+"""Live bus-stop arrivals from the `arrivals` source."""
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from mousetools._internal.services.ids import parent_from_channel_id, parse_entity_id
+from mousetools.entities._parse import as_int, as_list, as_str, clip, parse_dt
+from mousetools.enums import EntityType
+
+logger = logging.getLogger("mousetools.entities.arrivals")
+
+
+@dataclass(frozen=True)
+class ArrivalPrediction:
+    """One predicted transport arrival: pickup at the stop and drop-off at the destination."""
+
+    at_stop: datetime | None
+    at_destination: datetime | None
+
+
+@dataclass(frozen=True)
+class TransportService:
+    """A continuous transport mode serving a destination (e.g. Skyliner, Watercraft, Monorail)."""
+
+    type: str | None
+    status: str | None
+
+
+@dataclass(frozen=True)
+class DestinationArrival:
+    """Arrivals + services for one destination reachable from a bus stop."""
+
+    destination_id: str | None
+    frequency_seconds: int | None
+    arrivals: tuple[ArrivalPrediction, ...]
+    services: tuple[TransportService, ...]
+
+    @classmethod
+    def from_list(cls, raw: object, tz: ZoneInfo) -> "tuple[DestinationArrival, ...]":
+        """Build the per-destination tuple from a doc's `destinations[]`.
+
+        Args:
+            raw: The raw `destinations` value (expected a list; anything else -> `()`).
+            tz: Timezone the parsed arrival datetimes are converted into.
+
+        Returns:
+            One `DestinationArrival` per dict entry (non-dict entries skipped); `()` if `raw`
+            is not a list. `arrivals`/`services` degrade to `()` when absent or malformed.
+        """
+        out: list[DestinationArrival] = []
+        for d in as_list(raw):
+            if not isinstance(d, dict):
+                logger.debug("arrivals destination: expected a mapping, got %r", d)
+                continue
+            arrivals = tuple(
+                ArrivalPrediction(
+                    at_stop=parse_dt(a.get("atStop"), tz), at_destination=parse_dt(a.get("atDestination"), tz)
+                )
+                for a in as_list(d.get("arrivals"))
+                if isinstance(a, dict)
+            )
+            services = tuple(
+                TransportService(type=as_str(s.get("type")), status=as_str(s.get("status")))
+                for s in as_list(d.get("services"))
+                if isinstance(s, dict)
+            )
+            out.append(
+                cls(
+                    destination_id=as_str(d.get("id")),
+                    frequency_seconds=as_int(d.get("frequency")),
+                    arrivals=arrivals,
+                    services=services,
+                )
+            )
+        return tuple(out)
+
+
+@dataclass(frozen=True)
+class TransportArrivals:
+    """A bus stop's live transportation arrivals to every reachable destination.
+
+    A stop serving several resorts publishes a separate copy per resort, each
+    updated on its own. `resort_ids` names the resorts a copy was published for:
+    one in every captured doc, kept in order with duplicates preserved.
+    """
+
+    stop_id: str | None
+    last_updated: datetime | None
+    destinations: tuple[DestinationArrival, ...]
+    # Default keeps the constructor shape from before resort_ids; from_doc always sets it.
+    resort_ids: tuple[str, ...] = ()
+
+    @classmethod
+    def from_doc(cls, doc: dict | None, tz: ZoneInfo) -> "TransportArrivals | None":
+        """Build from an `arrivals` couchbase doc body, or None if `doc` is falsy/not a dict.
+
+        Note: `stop_id` is the composed `"<n>;entityType=bus-stop"` form; a streamed
+        `ChangeEvent.entity_id` for the same stop is the bare `"<n>"`. Dedup the per-resort
+        stream duplication on one form consistently, not a mix.
+
+        `resort_ids` are the composed resort ids (`"<n>;entityType=resort"`) parsed
+        from the doc's `channels`, in order. The type match is case-insensitive
+        (#32); channels not keyed by a resort are skipped and logged at DEBUG.
+
+        Args:
+            doc: The raw `arrivals` doc body, or None/falsy.
+            tz: Timezone the parsed datetimes are converted into.
+
+        Returns:
+            The built `TransportArrivals`, or None if `doc` is falsy or not a dict.
+        """
+        if not doc or not isinstance(doc, dict):
+            if doc:
+                logger.debug("arrivals doc: expected a mapping, got %s", clip(doc))
+            return None
+        return cls(
+            stop_id=as_str(doc.get("id")),
+            resort_ids=_resort_ids(doc.get("channels")),
+            last_updated=parse_dt(doc.get("lastUpdate"), tz),
+            destinations=DestinationArrival.from_list(doc.get("destinations"), tz),
+        )
+
+
+def _resort_ids(channels: object) -> tuple[str, ...]:
+    """The composed resort ids named by an arrivals doc's `channels`, in order.
+
+    Args:
+        channels: The raw `channels` value from an arrivals doc.
+
+    Returns:
+        One composed resort id per channel keyed by a resort; other entries are
+        skipped and logged at DEBUG.
+    """
+    out: list[str] = []
+    for channel in as_list(channels):
+        parent = parent_from_channel_id(channel) if isinstance(channel, str) else None
+        if parent and parse_entity_id(parent)[1].casefold() == EntityType.RESORT:
+            out.append(parent)
+        else:
+            logger.debug("arrivals channel %r names no resort; skipped", channel)
+    return tuple(out)