MouseTools 5.0.0__tar.gz → 6.0.0__tar.gz

{mousetools-5.0.0 → mousetools-6.0.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018-2025 Scott Caratozzolo
+Copyright (c) 2018-2026 Scott Caratozzolo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mousetools-6.0.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: mousetools
+Version: 6.0.0
+Summary: An unofficial Python wrapper for Disney's API
+Author: Scott Caratozzolo
+License-Expression: MIT
+Project-URL: repository, https://gitlab.com/caratozzoloxyz/public/MouseTools
+Project-URL: documentation, https://caratozzoloxyz.gitlab.io/public/MouseTools/
+Project-URL: issues, https://gitlab.com/caratozzoloxyz/public/MouseTools/-/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: more-itertools>=10.7.0
+Requires-Dist: pycryptodome>=3.22.0
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: niquests[http3,utls]>=3.20.0
+Requires-Dist: tzdata>=2025.2
+Requires-Dist: websockets>=13.0
+Dynamic: license-file
+
+# MouseTools
+
+![PyPI - Version](https://img.shields.io/pypi/v/mousetools?style=flat-square&logo=python&color=00C106&link=https%3A%2F%2Fpypi.org%2Fproject%2Fmousetools%2F) ![PyPI - Downloads](https://img.shields.io/pypi/dm/mousetools?style=flat-square&color=blue&link=https%3A%2F%2Fpypi.org%2Fproject%2Fmousetools%2F)
+
+
+An unofficial, **async** Python wrapper for Disney's undocumented API. Data is pulled directly from Disney, and this package makes no attempt to access data that would require individual user authentication — public data only. Supports Walt Disney World and Disneyland Resort.
+
+## Install
+You can install using pip:
+```bash
+pip install mousetools
+```
+You can also install directly from this repo in case of any changes not uploaded to Pypi.
+```bash
+pip install git+https://gitlab.com/caratozzoloxyz/public/MouseTools
+```
+
+## Quick example
+
+```python
+import asyncio
+import mousetools
+from mousetools import WALT_DISNEY_WORLD
+
+async def main() -> None:
+    # Build an unloaded handle via the destination front-door (no I/O yet).
+    attraction = WALT_DISNEY_WORLD.get_attraction("80010177")  # Pirates of the Caribbean
+
+    # Loading is EXPLICIT — attribute access does NOT auto-load.
+    await attraction.load()
+
+    print(attraction.name)                    # str
+    wait = attraction.wait_time               # WaitTime | None
+    if wait is not None:
+        print("Standby (min):", wait.standby_minutes)
+        print("Status:", wait.status)
+
+    park = await attraction.theme_park()      # ThemePark | None
+    if park is not None:
+        print("In park:", park.name)
+
+    await mousetools.aclose()                 # close the shared default client(s)
+
+asyncio.run(main())
+```
+
+📖 **[Full documentation](https://caratozzoloxyz.gitlab.io/public/MouseTools/)**
+
+### License
+This project is distributed under the MIT license. For more information see [LICENSE](https://gitlab.com/caratozzoloxyz/public/MouseTools/-/blob/master/LICENSE?ref_type=heads)
+
+### Disclaimer
+This project is in no way affiliated with The Walt Disney Company and all use of Disney Services is subject to the [Disney Terms of Use](https://disneytermsofuse.com/).
+
+
+### About Project
+
+<a href='https://ko-fi.com/scaratozzolo' target='_blank'>
+<img src='https://img.shields.io/badge/sponsor-30363D?style=for-the-badge&logo=kofi&logoColor=white&link=https%3A%2F%2Fko-fi.com%2Fscaratozzolo border='0' alt='Support my projects' />
+</a>
+
+MouseTools is a passion project I've been working on since 2018 when I was first learning Python. The package has evolved and been rewritten multiple times as I've become a better developer and as the Disney API has changed. There is a lot of time exploring Disney's API and figuring out how all the pieces work before any code is even written. I work on this project when I have time or when I have an idea for another project that could use this data.

mousetools-6.0.0/README.md

@@ -0,0 +1,62 @@
+# MouseTools
+
+![PyPI - Version](https://img.shields.io/pypi/v/mousetools?style=flat-square&logo=python&color=00C106&link=https%3A%2F%2Fpypi.org%2Fproject%2Fmousetools%2F) ![PyPI - Downloads](https://img.shields.io/pypi/dm/mousetools?style=flat-square&color=blue&link=https%3A%2F%2Fpypi.org%2Fproject%2Fmousetools%2F)
+
+
+An unofficial, **async** Python wrapper for Disney's undocumented API. Data is pulled directly from Disney, and this package makes no attempt to access data that would require individual user authentication — public data only. Supports Walt Disney World and Disneyland Resort.
+
+## Install
+You can install using pip:
+```bash
+pip install mousetools
+```
+You can also install directly from this repo in case of any changes not uploaded to Pypi.
+```bash
+pip install git+https://gitlab.com/caratozzoloxyz/public/MouseTools
+```
+
+## Quick example
+
+```python
+import asyncio
+import mousetools
+from mousetools import WALT_DISNEY_WORLD
+
+async def main() -> None:
+    # Build an unloaded handle via the destination front-door (no I/O yet).
+    attraction = WALT_DISNEY_WORLD.get_attraction("80010177")  # Pirates of the Caribbean
+
+    # Loading is EXPLICIT — attribute access does NOT auto-load.
+    await attraction.load()
+
+    print(attraction.name)                    # str
+    wait = attraction.wait_time               # WaitTime | None
+    if wait is not None:
+        print("Standby (min):", wait.standby_minutes)
+        print("Status:", wait.status)
+
+    park = await attraction.theme_park()      # ThemePark | None
+    if park is not None:
+        print("In park:", park.name)
+
+    await mousetools.aclose()                 # close the shared default client(s)
+
+asyncio.run(main())
+```
+
+📖 **[Full documentation](https://caratozzoloxyz.gitlab.io/public/MouseTools/)**
+
+### License
+This project is distributed under the MIT license. For more information see [LICENSE](https://gitlab.com/caratozzoloxyz/public/MouseTools/-/blob/master/LICENSE?ref_type=heads)
+
+### Disclaimer
+This project is in no way affiliated with The Walt Disney Company and all use of Disney Services is subject to the [Disney Terms of Use](https://disneytermsofuse.com/).
+
+
+### About Project
+
+<a href='https://ko-fi.com/scaratozzolo' target='_blank'>
+<img src='https://img.shields.io/badge/sponsor-30363D?style=for-the-badge&logo=kofi&logoColor=white&link=https%3A%2F%2Fko-fi.com%2Fscaratozzolo border='0' alt='Support my projects' />
+</a>
+
+MouseTools is a passion project I've been working on since 2018 when I was first learning Python. The package has evolved and been rewritten multiple times as I've become a better developer and as the Disney API has changed. There is a lot of time exploring Disney's API and figuring out how all the pieces work before any code is even written. I work on this project when I have time or when I have an idea for another project that could use this data.

mousetools-6.0.0/mousetools/__init__.py

@@ -0,0 +1,132 @@
+"""MouseTools — an async, domain-first Python wrapper for Disney's API (v6)."""
+
+import logging
+
+from mousetools import errors
+from mousetools.client import Client, aclose
+from mousetools.entities import (
+    DISNEYLAND_RESORT,
+    WALT_DISNEY_WORLD,
+    Appearance,
+    Attraction,
+    AudioTour,
+    Avatar,
+    BusStop,
+    CalendarSchedule,
+    Character,
+    ContainerEntity,
+    Coordinates,
+    DailySchedule,
+    Destination,
+    DiningEvent,
+    DinnerShow,
+    Entertainment,
+    EntertainmentVenue,
+    Entity,
+    Event,
+    FacilityEntity,
+    Forecast,
+    ForecastPoint,
+    GuestService,
+    Land,
+    Menu,
+    MenuCollection,
+    MenuGroup,
+    MenuItem,
+    MenuPrice,
+    MerchandiseFacility,
+    PartySizeStatus,
+    PhotoPass,
+    PointOfInterest,
+    PriceRange,
+    Recreation,
+    RecreationActivity,
+    Resort,
+    ResortArea,
+    Restaurant,
+    ScheduleSegment,
+    SearchMode,
+    SearchResponse,
+    SearchResult,
+    Spa,
+    ThemePark,
+    Tour,
+    Transportation,
+    WaitTime,
+    WalkUpAvailability,
+    WaterPark,
+    entity_for,
+    load_many,
+)
+from mousetools.enums import ChannelSource, DestinationShort, EntityType, ScheduleSource
+from mousetools.stream import CalendarEvent, ChangeEvent, FacilityStatusEvent, ForecastEvent, RawChange
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+__all__ = [
+    "DISNEYLAND_RESORT",
+    "WALT_DISNEY_WORLD",
+    "Appearance",
+    "Attraction",
+    "AudioTour",
+    "Avatar",
+    "BusStop",
+    "CalendarEvent",
+    "CalendarSchedule",
+    "ChangeEvent",
+    "ChannelSource",
+    "Character",
+    "Client",
+    "ContainerEntity",
+    "Coordinates",
+    "DailySchedule",
+    "Destination",
+    "DestinationShort",
+    "DiningEvent",
+    "DinnerShow",
+    "Entertainment",
+    "EntertainmentVenue",
+    "Entity",
+    "EntityType",
+    "Event",
+    "FacilityEntity",
+    "FacilityStatusEvent",
+    "Forecast",
+    "ForecastEvent",
+    "ForecastPoint",
+    "GuestService",
+    "Land",
+    "Menu",
+    "MenuCollection",
+    "MenuGroup",
+    "MenuItem",
+    "MenuPrice",
+    "MerchandiseFacility",
+    "PartySizeStatus",
+    "PhotoPass",
+    "PointOfInterest",
+    "PriceRange",
+    "RawChange",
+    "Recreation",
+    "RecreationActivity",
+    "Resort",
+    "ResortArea",
+    "Restaurant",
+    "ScheduleSegment",
+    "ScheduleSource",
+    "SearchMode",
+    "SearchResponse",
+    "SearchResult",
+    "Spa",
+    "ThemePark",
+    "Tour",
+    "Transportation",
+    "WaitTime",
+    "WalkUpAvailability",
+    "WaterPark",
+    "aclose",
+    "entity_for",
+    "errors",
+    "load_many",
+]

mousetools-6.0.0/mousetools/_internal/auth/__init__.py

@@ -0,0 +1,5 @@
+from mousetools._internal.auth.base import Auth
+from mousetools._internal.auth.public import PublicAuth
+from mousetools._internal.auth.syncgateway import SyncGatewayAuth
+
+__all__ = ["Auth", "PublicAuth", "SyncGatewayAuth"]

mousetools-6.0.0/mousetools/_internal/auth/base.py

@@ -0,0 +1,39 @@
+import time
+from typing import Protocol, runtime_checkable
+
+from mousetools._internal.transport import Transport
+
+LEEWAY_SECONDS = 10  # refresh this many seconds before actual expiry
+
+
+@runtime_checkable
+class Auth(Protocol):
+    def bind(self, transport: Transport) -> None:
+        """Wire the shared `Transport` in, for implementations that need it to
+        fetch/refresh tokens.
+
+        Args:
+            transport: The Client's shared transport.
+        """
+        ...
+
+    async def headers(self) -> dict[str, str]:
+        """Return the auth headers to send on the next request, refreshing first if needed.
+
+        Returns:
+            The headers to merge into the outgoing request.
+        """
+        ...
+
+    async def refresh(self) -> None:
+        """Force-refresh the credential, discarding any cached one."""
+        ...
+
+
+def epoch_now() -> float:
+    """Return the current time in epoch seconds (the default auth clock).
+
+    Returns:
+        The current epoch time.
+    """
+    return time.time()

mousetools-6.0.0/mousetools/_internal/auth/public.py

@@ -0,0 +1,104 @@
+import asyncio
+from collections.abc import Callable
+
+from mousetools._internal.auth.base import LEEWAY_SECONDS, epoch_now
+from mousetools._internal.config import load_config
+from mousetools._internal.transport import Transport
+from mousetools.errors import AuthError
+
+
+class PublicAuth:
+    """Zero-config guest-token auth (assertion/public grant). The Client binds the
+    shared Transport in; token_url/client_id default to the decrypted config."""
+
+    def __init__(
+        self,
+        *,
+        now: Callable[[], float] = epoch_now,
+        token_url: str | None = None,
+        client_id: str | None = None,
+    ) -> None:
+        """Create a guest-token auth, defaulting the token endpoint/client id from config.
+
+        Args:
+            now: The clock used for expiry checks; overridable for tests.
+            token_url: The assertion-grant token endpoint. Falls back to the
+                decrypted config's `token_url`.
+            client_id: The OAuth client id to grant against. Falls back to
+                the decrypted config's `client_id`.
+        """
+        self._now = now
+        if token_url is None or client_id is None:
+            cfg = load_config()
+            token_url = token_url or cfg.token_url
+            client_id = client_id or cfg.client_id
+        self._token_url = token_url
+        self._client_id = client_id
+        self._transport: Transport | None = None
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+        # Serialises the grant so N concurrent callers on a cold/just-expired token
+        # issue ONE request instead of each firing their own at Disney's endpoint.
+        self._grant_lock = asyncio.Lock()
+
+    def bind(self, transport: Transport) -> None:
+        """Wire the shared `Transport` in; must be called before any token grant.
+
+        Args:
+            transport: The Client's shared transport, used for the token POST.
+        """
+        self._transport = transport
+
+    async def _token_value(self) -> str:
+        """Return a valid access token, granting/re-granting one if needed.
+
+        Returns:
+            The current (possibly freshly-granted) access token.
+
+        Raises:
+            AuthError: `bind(transport)` has not been called yet, or the
+                token grant request failed (no response, or status >= 400).
+        """
+        if self._transport is None:
+            raise AuthError("PublicAuth used before bind(transport)")
+        if self._token is not None and self._now() < self._expires_at - LEEWAY_SECONDS:
+            return self._token
+        async with self._grant_lock:
+            # Re-check inside the lock: a concurrent caller may have granted while
+            # we were waiting, in which case we reuse its token rather than minting
+            # a redundant one.
+            if self._token is None or self._now() >= self._expires_at - LEEWAY_SECONDS:
+                resp = await self._transport.request(
+                    "POST",
+                    self._token_url,
+                    data={"grant_type": "assertion", "assertion_type": "public", "client_id": self._client_id},
+                    headers={"Content-Type": "application/x-www-form-urlencoded"},
+                )
+                if resp.status_code is None or resp.status_code >= 400:
+                    raise AuthError(f"public token grant failed: {resp.status_code} from {self._token_url}")
+                body = resp.json()
+                self._token = body["access_token"]
+                self._expires_at = self._now() + int(body["expires_in"])
+            return self._token
+
+    async def headers(self) -> dict[str, str]:
+        """Return the bearer-auth header, granting a token first if needed.
+
+        Returns:
+            The `Authorization` header to send.
+
+        Raises:
+            AuthError: `bind(transport)` has not been called yet, or the
+                token grant request failed.
+        """
+        return {"Authorization": f"BEARER {await self._token_value()}"}
+
+    async def refresh(self) -> None:
+        """Discard the cached token and grant a fresh one immediately.
+
+        Raises:
+            AuthError: `bind(transport)` has not been called yet, or the
+                token grant request failed.
+        """
+        self._token = None
+        await self._token_value()

mousetools-6.0.0/mousetools/_internal/auth/syncgateway.py

@@ -0,0 +1,55 @@
+import base64
+
+from mousetools._internal.config import load_config
+from mousetools._internal.transport import Transport
+
+
+class SyncGatewayAuth:
+    """Static HTTP Basic auth for the Couchbase sync gateway (public couchbase data).
+    No token dance, no swid; creds come from the decrypted config."""
+
+    def __init__(self, *, sync_user: str | None = None, sync_pass: str | None = None) -> None:
+        """Create a Basic auth, defaulting the credentials from config.
+
+        Args:
+            sync_user: The sync-gateway Basic-auth username. Falls back to
+                the decrypted config's `sync_user`.
+            sync_pass: The sync-gateway Basic-auth password. Falls back to
+                the decrypted config's `sync_pass`.
+        """
+        if sync_user is None or sync_pass is None:
+            cfg = load_config()
+            sync_user = sync_user or cfg.sync_user
+            sync_pass = sync_pass or cfg.sync_pass
+        token = base64.b64encode(f"{sync_user}:{sync_pass}".encode()).decode("ascii")
+        self._auth_header = f"Basic {token}"
+
+    def bind(self, transport: Transport) -> None:  # noqa: ARG002 -- static creds need no transport
+        """No-op: static Basic creds need no transport to fetch/refresh anything.
+
+        Args:
+            transport: Unused; accepted only to satisfy the `Auth` protocol.
+        """
+        return
+
+    async def headers(self) -> dict[str, str]:
+        """Return the static Basic-auth header.
+
+        Returns:
+            The `Authorization` and `Accept` headers to send.
+        """
+        return {"Authorization": self._auth_header, "Accept": "multipart/related"}
+
+    @property
+    def auth_header(self) -> str:
+        """The prebuilt `Authorization: Basic ...` header value.
+
+        Returns:
+            The `Basic <token>` header value, for callers (e.g. the WebSocket
+            stream connection) that need the raw value rather than a header dict.
+        """
+        return self._auth_header
+
+    async def refresh(self) -> None:
+        """No-op: the static Basic credential never expires."""
+        return

mousetools-6.0.0/mousetools/_internal/client_registry.py

@@ -0,0 +1,59 @@
+"""Indirection that lets `mousetools.entities` resolve a default `Client`
+without importing `mousetools.client` at module level.
+
+`mousetools.client` needs to import `mousetools.entities.search` (for
+`Client.search()`'s `SearchResponse`/`build_search_response`), and
+`mousetools.entities.base`/`mousetools.entities.destination` already need a
+default `Client` when none is passed explicitly. A direct top-level
+`entities -> client` import would make that a genuine circular import
+(`client -> entities -> client`), which `tach check` forbids outright
+(`forbid_circular_dependencies = true`) -- this is not a layering nuance to
+suppress, it's a real cycle Python's import system can't resolve.
+
+`mousetools.client` calls `register()` with `get_default_client` once, at the
+bottom of its own module body (still a top-level statement, not a
+function-local import -- PLC0415 is about deferred *imports*, not about when
+a plain function call happens to run). Entities call `resolve()` at runtime,
+never importing `mousetools.client` themselves.
+"""
+
+from typing import TYPE_CHECKING
+
+from mousetools.enums import DestinationShort
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from mousetools.client import Client
+
+# A single-entry dict, not a module-level `Callable | None` + `global`: item
+# assignment mutates in place, so `register()` needs no `global` statement.
+_state: dict[str, "Callable[[DestinationShort], Client]"] = {}
+
+
+def register(provider: "Callable[[DestinationShort], Client]") -> None:
+    """Called once by `mousetools.client`, at the bottom of its module body.
+
+    Args:
+        provider: Returns the shared default `Client` for a given destination.
+    """
+    _state["provider"] = provider
+
+
+def resolve(destination: DestinationShort = DestinationShort.WALT_DISNEY_WORLD) -> "Client":
+    """Return the shared default `Client` for `destination` (one per resort).
+
+    Args:
+        destination: The resort to resolve the default client for.
+
+    Returns:
+        The shared default `Client` for `destination`.
+
+    Raises:
+        RuntimeError: `mousetools.client` has not been imported yet, so no
+            provider has been registered.
+    """
+    provider = _state.get("provider")
+    if provider is None:
+        raise RuntimeError("default client provider not registered -- import mousetools.client first")
+    return provider(destination)

mousetools-6.0.0/mousetools/_internal/config.py

@@ -0,0 +1,93 @@
+"""Decrypts the bundled `resources/environments.bin` app config.
+
+INTENTIONALLY OBFUSCATED, NOT SECRET. `environments.bin` holds Disney's own
+client-side config -- the sync-gateway Basic-auth pair for its PUBLIC read-only
+Couchbase channels, plus the OneID token endpoint and client id -- obfuscated
+the same way the official Android app ships them. The key below is derived from
+constants in this file, so anyone can reproduce it; that is by design and
+mirrors the app, not an attempt at protection. These are NOT user credentials
+and grant no access beyond what any APK teardown already exposes. The file
+predates v6 (it ships in v5 on master too). Do not mistake it for an
+accidentally-committed secret -- and do not put a real secret here.
+"""
+
+import json
+import math
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.resources import files
+
+from Crypto.Cipher import AES
+
+# AES-GCM appends a 16-byte authentication tag to the ciphertext.
+_GCM_TAG_BYTES = 16
+
+
+@dataclass(frozen=True)
+class Config:
+    token_url: str
+    client_id: str
+    sync_gateway_url: str
+    sync_user: str
+    sync_pass: str
+    menu_url: str
+    search_url: str
+
+
+def _key() -> bytes:
+    """Derive the AES-GCM key used to decrypt the bundled `environments.bin`.
+
+    Returns:
+        The 16-byte key.
+    """
+    s = ""
+    for i in range(1, 17):
+        s += chr(i + 65) if (i % 2 != 0 or i >= 16) else str(math.pi)[i]
+    return s.encode("utf-8")
+
+
+def _nonce() -> bytes:
+    """Derive the AES-GCM nonce (the key's bytes, reversed).
+
+    Returns:
+        The 16-byte nonce.
+    """
+    return bytes(reversed(_key()))
+
+
+def _decrypt_environments() -> dict:
+    """Decrypt the bundled `resources/environments.bin` and return its `production` block.
+
+    Returns:
+        The production environment's config values (token/sync-gateway/menu/
+        search URLs and sync-gateway creds).
+    """
+    cipher = AES.new(_key(), AES.MODE_GCM, nonce=_nonce())
+    raw = (files("mousetools") / "resources/environments.bin").read_bytes()
+    # Verify the GCM tag instead of decrypting blind and slicing the trailing 16
+    # bytes off the decoded string. The old form only worked because cp1252 is a
+    # single-byte codec that never raises, so a corrupted resource (bit rot, a bad
+    # merge, a packaging error) surfaced as a confusing KeyError/JSONDecodeError
+    # further down rather than a clear integrity failure here.
+    ciphertext, tag = raw[:-_GCM_TAG_BYTES], raw[-_GCM_TAG_BYTES:]
+    decrypted = cipher.decrypt_and_verify(ciphertext, tag)
+    return json.loads(decrypted.decode("Windows-1252"))["production"]
+
+
+@lru_cache(maxsize=1)
+def load_config() -> Config:
+    """Return the decrypted app config, decrypting once and caching the result.
+
+    Returns:
+        The parsed, process-lifetime-cached `Config`.
+    """
+    env = _decrypt_environments()
+    return Config(
+        token_url=f"{env['authzServiceUrl'].rstrip('/')}/token",
+        client_id=env["authzClientId"],
+        sync_gateway_url="https://" + env["syncGatewayUrl"].split("//")[1].rstrip("/"),
+        sync_user=env["syncGatewayUser"],
+        sync_pass=env["syncGatewayPass"],
+        menu_url=env["serviceMenuUrl"].rstrip("/"),
+        search_url=env["searchServiceUrl"].rstrip("/"),
+    )