pfau-occupancy 0.1.0__tar.gz

pfau_occupancy-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pfau-occupancy
+Version: 0.1.0
+Summary: Async client for Planet Fitness AU (PerfectGym) club occupancy
+Author: Dan Morgan
+License: MIT
+Project-URL: Homepage, https://github.com/dancmorgan/pfau-occupancy
+Project-URL: Issues, https://github.com/dancmorgan/pfau-occupancy/issues
+Keywords: planet fitness,perfectgym,home assistant,occupancy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+
+# pfau-occupancy
+
+Async Python client for Planet Fitness Australia club occupancy, backing a Home
+Assistant integration. Data comes from the member portal (PerfectGym
+ClientPortal2), which exposes a live "members currently in club" count for every
+club in a single authenticated call.
+
+This library deliberately does only the API layer: login, session handling, and
+fetching occupancy. All Home Assistant concerns (entities, config flow,
+coordinator) live in the [pfau-occupancy-ha](https://github.com/dancmorgan/pfau-occupancy-ha)
+integration that depends on this package.
+
+## Install
+
+```bash
+pip install pfau-occupancy
+```
+
+## Usage
+
+```python
+import asyncio
+from pfau_occupancy import PlanetFitnessClient
+
+async def main():
+    async with PlanetFitnessClient("you@example.com", "password") as client:
+        clubs = await client.async_get_clubs()
+        for club in clubs:
+            print(club.name, club.occupancy)
+
+asyncio.run(main())
+```
+
+The client logs in automatically on first fetch and re-authenticates once if the
+session expires, so a long-running poller keeps working without intervention.
+
+## Data notes
+
+The occupancy endpoint returns every club in one response. Each club carries a
+name, address, a currently-in-club count, and a capacity limit (often null). The
+response has no club ID, so the (slugified) club name is the stable identity used
+for entity `unique_id`s. A club being renamed therefore looks like one club
+disappearing and another appearing.
+
+## Disclaimer
+
+This uses the member portal's internal endpoints, which are undocumented and may
+change or break without notice. It requires your own valid membership
+credentials. Use it with your own account and keep polling gentle.

pfau_occupancy-0.1.0/README.md

@@ -0,0 +1,49 @@
+# pfau-occupancy
+
+Async Python client for Planet Fitness Australia club occupancy, backing a Home
+Assistant integration. Data comes from the member portal (PerfectGym
+ClientPortal2), which exposes a live "members currently in club" count for every
+club in a single authenticated call.
+
+This library deliberately does only the API layer: login, session handling, and
+fetching occupancy. All Home Assistant concerns (entities, config flow,
+coordinator) live in the [pfau-occupancy-ha](https://github.com/dancmorgan/pfau-occupancy-ha)
+integration that depends on this package.
+
+## Install
+
+```bash
+pip install pfau-occupancy
+```
+
+## Usage
+
+```python
+import asyncio
+from pfau_occupancy import PlanetFitnessClient
+
+async def main():
+    async with PlanetFitnessClient("you@example.com", "password") as client:
+        clubs = await client.async_get_clubs()
+        for club in clubs:
+            print(club.name, club.occupancy)
+
+asyncio.run(main())
+```
+
+The client logs in automatically on first fetch and re-authenticates once if the
+session expires, so a long-running poller keeps working without intervention.
+
+## Data notes
+
+The occupancy endpoint returns every club in one response. Each club carries a
+name, address, a currently-in-club count, and a capacity limit (often null). The
+response has no club ID, so the (slugified) club name is the stable identity used
+for entity `unique_id`s. A club being renamed therefore looks like one club
+disappearing and another appearing.
+
+## Disclaimer
+
+This uses the member portal's internal endpoints, which are undocumented and may
+change or break without notice. It requires your own valid membership
+credentials. Use it with your own account and keep polling gentle.

pfau_occupancy-0.1.0/pfau_occupancy/__init__.py

@@ -0,0 +1,20 @@
+"""pfau_occupancy: async client for Planet Fitness AU club occupancy."""
+from .client import PlanetFitnessClient, DEFAULT_BASE_URL
+from .exceptions import (
+    PlanetFitnessError,
+    PlanetFitnessAuthError,
+    PlanetFitnessConnectionError,
+)
+from .models import Club, slugify_club
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PlanetFitnessClient",
+    "DEFAULT_BASE_URL",
+    "PlanetFitnessError",
+    "PlanetFitnessAuthError",
+    "PlanetFitnessConnectionError",
+    "Club",
+    "slugify_club",
+]

pfau_occupancy-0.1.0/pfau_occupancy/client.py

@@ -0,0 +1,167 @@
+"""Async client for the Planet Fitness AU (PerfectGym ClientPortal2) portal."""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from .exceptions import (
+    PlanetFitnessAuthError,
+    PlanetFitnessConnectionError,
+)
+from .models import Club
+
+_LOGGER = logging.getLogger(__name__)
+
+DEFAULT_BASE_URL = "https://planetfitness.perfectgym.com.au/clientportal2"
+
+# Sent on every XHR by the browser. The backend checks x-requested-with;
+# cp-lang / cp-mode are constants the portal expects.
+_BASE_HEADERS = {
+    "x-requested-with": "XMLHttpRequest",
+    "cp-lang": "en",
+    "cp-mode": "desktop",
+    "accept": "application/json, text/plain, */*",
+}
+
+
+class PlanetFitnessClient:
+    """Talks to the member portal: login, then fetch club occupancy.
+
+    Holds one aiohttp session so the auth cookie persists across calls. Credentials
+    are kept so the client can transparently re-login when the session expires,
+    which for a long-running poller it eventually will.
+
+    The caller owns the aiohttp session lifecycle by passing one in (this is what
+    Home Assistant wants: it supplies its shared session). If none is given, one is
+    created and closed by `async with` / `close()`.
+    """
+
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        session: aiohttp.ClientSession | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        self._email = email
+        self._password = password
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = session is None
+        self._authenticated = False
+
+    async def __aenter__(self) -> "PlanetFitnessClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            # cookie_jar persists the session cookie across requests.
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            **_BASE_HEADERS,
+            "origin": "https://planetfitness.perfectgym.com.au",
+            "referer": self._base_url + "/",
+        }
+
+    async def async_login(self) -> dict[str, Any]:
+        """Authenticate and return the member record.
+
+        Raises PlanetFitnessAuthError on bad credentials, PlanetFitnessConnectionError
+        on transport problems.
+        """
+        session = self._get_session()
+        payload = {"RememberMe": True, "Login": self._email, "Password": self._password}
+        try:
+            async with session.post(
+                f"{self._base_url}/Auth/Login",
+                json=payload,
+                headers=self._headers(),
+                timeout=aiohttp.ClientTimeout(total=20),
+            ) as resp:
+                if resp.status in (400, 401, 403):
+                    raise PlanetFitnessAuthError(
+                        f"Login rejected (HTTP {resp.status}); check credentials."
+                    )
+                if resp.status != 200:
+                    raise PlanetFitnessConnectionError(
+                        f"Unexpected login status HTTP {resp.status}."
+                    )
+                data = await resp.json()
+        except aiohttp.ClientError as err:
+            raise PlanetFitnessConnectionError(f"Login request failed: {err}") from err
+
+        member = _extract_member(data)
+        if not member:
+            # 200 but no member usually means the session cookie was not set.
+            raise PlanetFitnessAuthError("Login succeeded but no member returned.")
+        self._authenticated = True
+        _LOGGER.debug("Authenticated as member %s", member.get("Id"))
+        return member
+
+    async def async_get_clubs(self) -> list[Club]:
+        """Fetch occupancy for all clubs.
+
+        Logs in automatically if not yet authenticated, and re-logs-in once if the
+        session has expired (detected as an auth failure mid-fetch).
+        """
+        if not self._authenticated:
+            await self.async_login()
+        try:
+            return await self._fetch_clubs()
+        except PlanetFitnessAuthError:
+            # Session likely expired. Re-login once, then retry.
+            _LOGGER.debug("Session expired; re-authenticating.")
+            self._authenticated = False
+            await self.async_login()
+            return await self._fetch_clubs()
+
+    async def _fetch_clubs(self) -> list[Club]:
+        session = self._get_session()
+        try:
+            async with session.post(
+                f"{self._base_url}/Clubs/Clubs/GetMembersInClubs",
+                headers=self._headers(),
+                timeout=aiohttp.ClientTimeout(total=20),
+            ) as resp:
+                if resp.status in (401, 403):
+                    raise PlanetFitnessAuthError("Not authenticated for club fetch.")
+                if resp.status != 200:
+                    raise PlanetFitnessConnectionError(
+                        f"Club fetch failed HTTP {resp.status}."
+                    )
+                # An expired session can also return the login page (HTML) with a
+                # 200. Guard against that so we don't parse HTML as JSON.
+                ctype = resp.headers.get("content-type", "")
+                if "application/json" not in ctype:
+                    raise PlanetFitnessAuthError(
+                        "Club fetch returned non-JSON; session likely expired."
+                    )
+                data = await resp.json()
+        except aiohttp.ClientError as err:
+            raise PlanetFitnessConnectionError(f"Club fetch failed: {err}") from err
+
+        raw_list = data.get("UsersInClubList") or []
+        return [Club.from_api(item) for item in raw_list]
+
+
+def _extract_member(data: dict) -> dict:
+    """Login returns {"User": {"Member": {...}}}; Identity returns {"Member": {...}}.
+
+    Handle both so either response shape confirms authentication.
+    """
+    user = data.get("User")
+    if isinstance(user, dict) and user.get("Member"):
+        return user["Member"]
+    return data.get("Member") or {}

pfau_occupancy-0.1.0/pfau_occupancy/exceptions.py

@@ -0,0 +1,18 @@
+"""Exceptions for pfau_occupancy."""
+
+
+class PlanetFitnessError(Exception):
+    """Base error for all pfau_occupancy failures."""
+
+
+class PlanetFitnessAuthError(PlanetFitnessError):
+    """Raised when login fails or the session is no longer authenticated.
+
+    The Home Assistant coordinator treats this specially: it triggers a
+    re-login (and, if that fails, a reauth flow) rather than marking sensors
+    unavailable, so a dropped session is never confused with an empty club.
+    """
+
+
+class PlanetFitnessConnectionError(PlanetFitnessError):
+    """Raised on network/transport problems talking to the portal."""

pfau_occupancy-0.1.0/pfau_occupancy/models.py

@@ -0,0 +1,51 @@
+"""Data models for pfau_occupancy."""
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+
+
+def slugify_club(name: str) -> str:
+    """Produce a stable, filesystem/entity-safe key from a club name.
+
+    Used to build entity unique_ids. Since the occupancy endpoint exposes no
+    club ID, the (slugified) name is the only stable identity we have. Two
+    different clubs must not collide here, so we keep it close to the original:
+    lowercased, accents stripped, non-alphanumerics collapsed to underscores.
+    """
+    normalized = unicodedata.normalize("NFKD", name)
+    ascii_name = normalized.encode("ascii", "ignore").decode("ascii")
+    slug = re.sub(r"[^a-z0-9]+", "_", ascii_name.lower()).strip("_")
+    return slug or "club"
+
+
+@dataclass(frozen=True)
+class Club:
+    """A single club's occupancy snapshot."""
+
+    name: str
+    address: str | None
+    occupancy: int | None
+    limit: int | None
+
+    @property
+    def key(self) -> str:
+        """Stable identity for this club (used for the entity unique_id)."""
+        return slugify_club(self.name)
+
+    @property
+    def percent_full(self) -> float | None:
+        """Occupancy as a percentage of the club's stated limit, if known."""
+        if not self.limit or self.occupancy is None:
+            return None
+        return round(self.occupancy / self.limit * 100, 1)
+
+    @classmethod
+    def from_api(cls, raw: dict) -> "Club":
+        return cls(
+            name=raw["ClubName"],
+            address=raw.get("ClubAddress"),
+            occupancy=raw.get("UsersCountCurrentlyInClub"),
+            limit=raw.get("UsersLimit"),
+        )

pfau_occupancy-0.1.0/pfau_occupancy.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pfau-occupancy
+Version: 0.1.0
+Summary: Async client for Planet Fitness AU (PerfectGym) club occupancy
+Author: Dan Morgan
+License: MIT
+Project-URL: Homepage, https://github.com/dancmorgan/pfau-occupancy
+Project-URL: Issues, https://github.com/dancmorgan/pfau-occupancy/issues
+Keywords: planet fitness,perfectgym,home assistant,occupancy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+
+# pfau-occupancy
+
+Async Python client for Planet Fitness Australia club occupancy, backing a Home
+Assistant integration. Data comes from the member portal (PerfectGym
+ClientPortal2), which exposes a live "members currently in club" count for every
+club in a single authenticated call.
+
+This library deliberately does only the API layer: login, session handling, and
+fetching occupancy. All Home Assistant concerns (entities, config flow,
+coordinator) live in the [pfau-occupancy-ha](https://github.com/dancmorgan/pfau-occupancy-ha)
+integration that depends on this package.
+
+## Install
+
+```bash
+pip install pfau-occupancy
+```
+
+## Usage
+
+```python
+import asyncio
+from pfau_occupancy import PlanetFitnessClient
+
+async def main():
+    async with PlanetFitnessClient("you@example.com", "password") as client:
+        clubs = await client.async_get_clubs()
+        for club in clubs:
+            print(club.name, club.occupancy)
+
+asyncio.run(main())
+```
+
+The client logs in automatically on first fetch and re-authenticates once if the
+session expires, so a long-running poller keeps working without intervention.
+
+## Data notes
+
+The occupancy endpoint returns every club in one response. Each club carries a
+name, address, a currently-in-club count, and a capacity limit (often null). The
+response has no club ID, so the (slugified) club name is the stable identity used
+for entity `unique_id`s. A club being renamed therefore looks like one club
+disappearing and another appearing.
+
+## Disclaimer
+
+This uses the member portal's internal endpoints, which are undocumented and may
+change or break without notice. It requires your own valid membership
+credentials. Use it with your own account and keep polling gentle.

pfau_occupancy-0.1.0/pfau_occupancy.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+pfau_occupancy/__init__.py
+pfau_occupancy/client.py
+pfau_occupancy/exceptions.py
+pfau_occupancy/models.py
+pfau_occupancy.egg-info/PKG-INFO
+pfau_occupancy.egg-info/SOURCES.txt
+pfau_occupancy.egg-info/dependency_links.txt
+pfau_occupancy.egg-info/requires.txt
+pfau_occupancy.egg-info/top_level.txt

pfau_occupancy-0.1.0/pfau_occupancy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pfau_occupancy-0.1.0/pfau_occupancy.egg-info/requires.txt

@@ -0,0 +1 @@
+aiohttp>=3.9

pfau_occupancy-0.1.0/pfau_occupancy.egg-info/top_level.txt

@@ -0,0 +1 @@
+pfau_occupancy

pfau_occupancy-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pfau-occupancy"
+version = "0.1.0"
+description = "Async client for Planet Fitness AU (PerfectGym) club occupancy"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Dan Morgan" }]
+keywords = ["planet fitness", "perfectgym", "home assistant", "occupancy"]
+dependencies = ["aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://github.com/dancmorgan/pfau-occupancy"
+Issues = "https://github.com/dancmorgan/pfau-occupancy/issues"
+
+[tool.setuptools.packages.find]
+include = ["pfau_occupancy*"]

pfau_occupancy-0.1.0/setup.cfg

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