chickensmoothie 0.1.0__tar.gz

chickensmoothie-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Haru ハル
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

chickensmoothie-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include RELEASING.md

chickensmoothie-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: chickensmoothie
+Version: 0.1.0
+Summary: Unofficial async Python client for Chicken Smoothie
+Author: Haru
+License-Expression: ISC
+Project-URL: Repository, https://github.com/haruyuki/chickensmoothie
+Project-URL: Issues, https://github.com/haruyuki/chickensmoothie/issues
+Keywords: chickensmoothie,pets,archive,asyncio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.13.5
+Requires-Dist: lxml>=6.0.4
+Requires-Dist: cssselect>=1.4.0
+Dynamic: license-file
+
+# chickensmoothie
+
+Unofficial standalone asynchronous client for Chicken Smoothie. Requires Python 3.11+.
+Not affiliated with or endorsed by Chicken Smoothie.
+No Discord, database, environment variables, or bot startup dependencies.
+
+## Installation
+
+From a local checkout:
+
+```powershell
+uv sync
+```
+
+Or install with pip: `python -m pip install .`.
+After the first PyPI release, users can install with `python -m pip install chickensmoothie`.
+
+## Usage
+
+```python
+import asyncio
+import chickensmoothie
+
+async def main():
+    pet = await chickensmoothie.get_pet("IMAGE_K_ID", years=[2026])
+    matches = await chickensmoothie.get_archive("IMAGE_K_ID", years=[2026])
+    async with chickensmoothie.Client() as client:
+        # Login is needed for account-dependent opening information.
+        await client.login("username", "password")
+        status = await client.get_opening_status()
+        events = await client.get_archive_events(2026, "pets")
+        page = await client.get_archive_event(events[0], "pets", 2026)
+        for entry in page.entries:
+            print(entry)
+
+asyncio.run(main())
+```
+
+All network methods are async. `get_pet` returns the first matching `Pet` or
+`None`; `get_archive` returns all matching `Pet` archive records. IDs refer to
+image URL `k` values, as used by the bot's identification database, not numeric
+IDs for individually owned pets. Individual pet profiles are not supported.
+Without `years`, lookups scan archives from 2008 through the current UTC year;
+this can make many requests. Restrict years when possible. The bot retains its
+SQLite index for fast identification instead of scanning on every command.
+
+`get_archive_events(year, "items")` and `get_archive_event(event, "items", year)`
+return item records, including both image IDs, name, year, event and URLs.
+Archive extraction retains the bot's known duplicate-pet exclusions and
+`pageSize=3000` behavior. Events beyond that server response limit are not paged.
+
+Use one `Client` context for repeated calls. `Client(session)` accepts an
+existing aiohttp session and never closes it. Credentials are explicit.
+HTTP failures propagate as aiohttp exceptions; failed login raises
+`AuthenticationError`. Missing archive matches return empty results, while
+HTTP errors are never treated as missing pets.
+
+The bot owns SQLite/MongoDB storage, RSS feed caching, reminder scheduling,
+Discord formatting and image uploads. `NEWS_FEED_URL` exposes the news source
+for other applications to use with their preferred RSS reader.
+
+## Development
+
+Run offline regression tests: `uv run python -m unittest discover -s tests -v`.
+Build release files: `uv build --no-sources`.
+See [RELEASING.md](RELEASING.md) for validation and PyPI upload instructions.
+
+## License
+
+ISC. See [LICENSE](LICENSE). This license applies to the package code, not to
+Chicken Smoothie's images, content, or branding.

chickensmoothie-0.1.0/README.md

@@ -0,0 +1,71 @@
+# chickensmoothie
+
+Unofficial standalone asynchronous client for Chicken Smoothie. Requires Python 3.11+.
+Not affiliated with or endorsed by Chicken Smoothie.
+No Discord, database, environment variables, or bot startup dependencies.
+
+## Installation
+
+From a local checkout:
+
+```powershell
+uv sync
+```
+
+Or install with pip: `python -m pip install .`.
+After the first PyPI release, users can install with `python -m pip install chickensmoothie`.
+
+## Usage
+
+```python
+import asyncio
+import chickensmoothie
+
+async def main():
+    pet = await chickensmoothie.get_pet("IMAGE_K_ID", years=[2026])
+    matches = await chickensmoothie.get_archive("IMAGE_K_ID", years=[2026])
+    async with chickensmoothie.Client() as client:
+        # Login is needed for account-dependent opening information.
+        await client.login("username", "password")
+        status = await client.get_opening_status()
+        events = await client.get_archive_events(2026, "pets")
+        page = await client.get_archive_event(events[0], "pets", 2026)
+        for entry in page.entries:
+            print(entry)
+
+asyncio.run(main())
+```
+
+All network methods are async. `get_pet` returns the first matching `Pet` or
+`None`; `get_archive` returns all matching `Pet` archive records. IDs refer to
+image URL `k` values, as used by the bot's identification database, not numeric
+IDs for individually owned pets. Individual pet profiles are not supported.
+Without `years`, lookups scan archives from 2008 through the current UTC year;
+this can make many requests. Restrict years when possible. The bot retains its
+SQLite index for fast identification instead of scanning on every command.
+
+`get_archive_events(year, "items")` and `get_archive_event(event, "items", year)`
+return item records, including both image IDs, name, year, event and URLs.
+Archive extraction retains the bot's known duplicate-pet exclusions and
+`pageSize=3000` behavior. Events beyond that server response limit are not paged.
+
+Use one `Client` context for repeated calls. `Client(session)` accepts an
+existing aiohttp session and never closes it. Credentials are explicit.
+HTTP failures propagate as aiohttp exceptions; failed login raises
+`AuthenticationError`. Missing archive matches return empty results, while
+HTTP errors are never treated as missing pets.
+
+The bot owns SQLite/MongoDB storage, RSS feed caching, reminder scheduling,
+Discord formatting and image uploads. `NEWS_FEED_URL` exposes the news source
+for other applications to use with their preferred RSS reader.
+
+## Development
+
+Run offline regression tests: `uv run python -m unittest discover -s tests -v`.
+Build release files: `uv build --no-sources`.
+See [RELEASING.md](RELEASING.md) for validation and PyPI upload instructions.
+
+## License
+
+ISC. See [LICENSE](LICENSE). This license applies to the package code, not to
+Chicken Smoothie's images, content, or branding.

chickensmoothie-0.1.0/RELEASING.md

@@ -0,0 +1,88 @@
+# Publishing with GitHub Trusted Publishing
+
+The workflow `.github/workflows/publish.yml` builds and tests the wheel, checks
+both distributions with Twine, then uploads through PyPI Trusted Publishing.
+No PyPI API tokens or GitHub repository secrets are needed. Twine remains a
+local validation tool, not the authentication mechanism.
+
+## One-time setup
+
+1. Commit and push the workflow, tests, and packaging files to `main` in
+   `haruyuki/chickensmoothie`. The workflow must exist on the default branch
+   before GitHub shows its manual Run workflow button.
+2. In GitHub repository Settings > Environments, create `testpypi` and `pypi`.
+   Configure a required reviewer for `pypi` where supported. For a solo project,
+   allow self-review so you can approve your own releases.
+3. Create/verify your accounts and enable two-factor authentication on PyPI and
+   TestPyPI. They are separate accounts.
+4. At https://test.pypi.org/manage/account/publishing/, add a pending GitHub publisher:
+   - PyPI project name: `chickensmoothie`
+   - Owner: `haruyuki`
+   - Repository name: `chickensmoothie`
+   - Workflow name: `publish.yml` (filename only)
+   - Environment name: `testpypi`
+5. At https://pypi.org/manage/account/publishing/, enter the same values, except
+   environment name must be `pypi`.
+
+If the project already exists under your account, add the publisher from that
+project's Manage > Publishing page instead. A pending publisher creates the
+project on first upload; it does not reserve the package name.
+
+## Test a release
+
+1. Commit the intended version in `pyproject.toml`; run `uv lock` after changing it.
+2. Push the commit. Open GitHub Actions > Publish package > Run workflow.
+3. Select your branch or tag, choose target `testpypi`, and run it.
+4. Review the successful run and https://test.pypi.org/project/chickensmoothie/.
+5. Verify installation in a separate local environment:
+
+```powershell
+uv venv .venv-testpypi
+uv pip install --python .venv-testpypi/Scripts/python.exe "aiohttp>=3.13.5" "lxml>=6.0.4" "cssselect>=1.4.0"
+uv pip install --python .venv-testpypi/Scripts/python.exe --index-url https://test.pypi.org/simple/ --no-deps chickensmoothie==0.1.0
+.venv-testpypi/Scripts/python.exe -I -m unittest discover -s tests -v
+```
+
+Dependencies come from real PyPI; only this package comes from TestPyPI.
+Replace `0.1.0` with your release version. Repeating a successful upload of the
+same filenames fails; use a new version for changed releases.
+
+## Publish to PyPI
+
+For version `0.1.0`, tag the exact tested commit and push the tag:
+
+```powershell
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+In GitHub Actions > Publish package > Run workflow, select tag `v0.1.0` under
+Use workflow from, choose target `pypi`, and run. Approve the `pypi` environment
+when prompted. The workflow rejects production runs unless the selected tag
+matches `v` plus the version in `pyproject.toml`.
+
+The workflow rebuilds the selected commit for each run; TestPyPI and PyPI runs
+are not guaranteed to produce byte-identical archives. Neither ordinary pushes
+nor creating a tag alone publishes anything: publication requires a manual run.
+
+After success, users can run `python -m pip install chickensmoothie`.
+For later releases, increase the version, test, create a matching tag, and repeat.
+Already published distribution filenames cannot be reused, even after deletion.
+
+## Local checks (no upload)
+
+```powershell
+uv sync --locked
+uv run python -m unittest discover -s tests -v
+uv build --no-sources
+uvx twine check --strict dist/chickensmoothie-0.1.0-py3-none-any.whl dist/chickensmoothie-0.1.0.tar.gz
+```
+
+Use only the files for the intended release when checking locally.
+GitHub builds start in a fresh checkout and upload only that run's artifacts.
+
+## References
+
+- https://docs.pypi.org/trusted-publishers/
+- https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
+- https://docs.pypi.org/trusted-publishers/using-a-publisher/

chickensmoothie-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chickensmoothie"
+version = "0.1.0"
+description = "Unofficial async Python client for Chicken Smoothie"
+readme = "README.md"
+license = "ISC"
+license-files = ["LICENSE"]
+authors = [{ name = "Haru" }]
+keywords = ["chickensmoothie", "pets", "archive", "asyncio"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.11"
+dependencies = ["aiohttp>=3.13.5", "lxml>=6.0.4", "cssselect>=1.4.0"]
+
+[project.urls]
+Repository = "https://github.com/haruyuki/chickensmoothie"
+Issues = "https://github.com/haruyuki/chickensmoothie/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

chickensmoothie-0.1.0/setup.cfg

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

chickensmoothie-0.1.0/src/chickensmoothie/__init__.py

@@ -0,0 +1,40 @@
+"""Reusable asynchronous Chicken Smoothie access."""
+
+from .archive import ArchiveEvent, ArchivePage, Item, Pet
+from .client import AuthenticationError, Client, NEWS_FEED_URL
+from .pound import OpeningClosed, OpeningOpen, OpeningStatus
+from .links import is_valid_chickensmoothie_link, parse_item_ids
+
+
+async def get_pet(pet_id: str, *, years=None) -> Pet | None:
+    async with Client() as client:
+        return await client.get_pet(pet_id, years=years)
+
+
+async def get_archive(pet_id: str, *, years=None) -> list[Pet]:
+    async with Client() as client:
+        return await client.get_archive(pet_id, years=years)
+
+
+async def get_opening_status() -> OpeningStatus:
+    async with Client() as client:
+        return await client.get_opening_status()
+
+
+__all__ = [
+    "Client",
+    "AuthenticationError",
+    "ArchiveEvent",
+    "ArchivePage",
+    "Pet",
+    "Item",
+    "OpeningClosed",
+    "OpeningOpen",
+    "OpeningStatus",
+    "NEWS_FEED_URL",
+    "get_pet",
+    "get_archive",
+    "get_opening_status",
+    "is_valid_chickensmoothie_link",
+    "parse_item_ids",
+]

chickensmoothie-0.1.0/src/chickensmoothie/archive.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+from urllib.parse import parse_qs, unquote, urlparse
+
+import lxml.html
+
+MONTHS = {
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+}
+
+CSS_PET_GROUP = ".archive-pet-tree-container"
+CSS_ITEM_GROUP = ".archive-item-group"
+
+EXCEPTIONS = {
+    "3B46301A6C8B850D87A730DA365B0960",
+    "E5FEFE44A3070BC9FC176503EC1A603F",
+    "0C1AFF9AEAA0953F1B1F9B818C2771C9",
+    "7C912BA5616D2E24E9F700D90E4BA2B6",
+    "905BB7DE4BC4E29D7FD2D1969667B568",
+    "773B14EEB416FA762C443D909FFED344",
+    "1C0DB4785FC78DF4395263D40261C614",
+    "5066110701B0AE95948A158F0B262EBB",
+    "5651A6C10C4D375A1901142C49C5C70C",
+    "8BED72498D055E55ABCA7AD29B180BF4",
+}
+
+Category = Literal["monthly", "special"]
+TableType = Literal["pets", "items"]
+
+
+@dataclass(slots=True)
+class ArchiveEvent:
+    title: str
+    link: str
+
+
+def get_event_title(link: str) -> str:
+    pattern = re.compile(r"^/archive/\d{4}/(?P<event>[^/]+)(?:/Items)?/?$")
+    match = pattern.match(link)
+    if not match:
+        return "Unknown Event"
+    return unquote(match.group("event"))
+
+
+def get_category(event_title: str) -> Category:
+    return "monthly" if event_title in MONTHS else "special"
+
+
+def parse_item_ids(image_link: str) -> tuple[int | None, int | None]:
+    parsed = urlparse(image_link)
+    pattern = re.compile(r"/item/(\d+)&p=(\d+)")
+    match = pattern.search(parsed.path)
+    if match:
+        return int(match.group(1)), int(match.group(2))
+
+    query = parse_qs(parsed.query)
+    left = query.get("lid", [None])[0] or query.get("l", [None])[0]
+    right = query.get("rid", [None])[0] or query.get("p", [None])[0]
+    if left and right:
+        return int(left), int(right)
+
+    return None, None
+
+
+@dataclass(frozen=True, slots=True)
+class Pet:
+    id: str
+    year: int
+    event: str
+    archive_url: str
+    image_url: str
+
+
+@dataclass(frozen=True, slots=True)
+class Item:
+    left_id: int
+    right_id: int
+    name: str
+    year: int
+    event: str
+    archive_url: str
+    image_url: str
+
+
+@dataclass(slots=True)
+class ArchivePage:
+    group_count: int
+    entries: list[Pet | Item]
+
+
+def parse_archive(
+    text: str, event: ArchiveEvent, table: TableType, year: int
+) -> ArchivePage:
+    from urllib.parse import urljoin
+
+    if table not in ("pets", "items"):
+        raise ValueError("table must be 'pets' or 'items'")
+    dom = lxml.html.fromstring(text)
+    groups = dom.cssselect(CSS_PET_GROUP if table == "pets" else CSS_ITEM_GROUP)
+    entries = []
+    groups_per_page = 7 if table == "pets" else 10
+    base = event.link.split("?")[0]
+    for index, group in enumerate(groups):
+        offset = (index // groups_per_page) * groups_per_page
+        page = f"{base}?pageStart={offset}" if offset else base
+        if table == "pets":
+            for image in group.cssselect('img[alt="Pet"][src]'):
+                image_url = urljoin(event.link, image.get("src"))
+                pet_id = parse_qs(urlparse(image_url).query).get("k", [None])[0]
+                if pet_id and pet_id not in EXCEPTIONS:
+                    entries.append(Pet(pet_id, year, event.title, page, image_url))
+        else:
+            for item in group.cssselect("li.item"):
+                images = item.cssselect("img[src]")
+                names = item.cssselect("div.item-name")
+                if not images or not names:
+                    continue
+                image_url = urljoin(event.link, images[0].get("src"))
+                try:
+                    left, right = parse_item_ids(image_url)
+                except ValueError:
+                    continue
+                if left is not None and right is not None:
+                    entries.append(
+                        Item(
+                            left,
+                            right,
+                            names[0].text_content().strip(),
+                            year,
+                            event.title,
+                            page,
+                            image_url,
+                        )
+                    )
+    return ArchivePage(len(groups), entries)

chickensmoothie-0.1.0/src/chickensmoothie/client.py

@@ -0,0 +1,132 @@
+"""HTTP access, with explicit session ownership and no application configuration."""
+
+from datetime import datetime, timezone
+from collections.abc import Iterable
+from urllib.parse import urljoin, urlparse
+
+import aiohttp
+import lxml.html
+
+from .archive import ArchiveEvent, Pet, TableType, get_event_title, parse_archive
+from .pound import parse_opening_status
+
+BASE_URL = "https://www.chickensmoothie.com"
+NEWS_FEED_URL = "https://chickensmoothie.com/rss.php?feed=news"
+
+
+class AuthenticationError(Exception):
+    """Chicken Smoothie did not accept the supplied credentials."""
+
+
+class Client:
+    """Use as an async context manager; an injected session remains caller-owned."""
+
+    def __init__(self, session: aiohttp.ClientSession | None = None):
+        self._session = session
+        self._owns_session = session is None
+        self.username = None
+
+    async def __aenter__(self):
+        if self._session is None:
+            self._session = aiohttp.ClientSession(
+                headers={"User-Agent": "chickensmoothie-python/0.1.0"},
+                timeout=aiohttp.ClientTimeout(total=60),
+            )
+        if self._session.closed:
+            raise RuntimeError("Client session is closed")
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def close(self):
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    def _require_session(self):
+        if self._session is None or self._session.closed:
+            raise RuntimeError("Use Client inside 'async with Client()'")
+        return self._session
+
+    async def _text(self, path):
+        url = urljoin(BASE_URL, path)
+        if urlparse(url).netloc != urlparse(BASE_URL).netloc:
+            raise ValueError("Expected a Chicken Smoothie URL")
+        async with self._require_session().get(url) as response:
+            response.raise_for_status()
+            return await response.text()
+
+    async def login(self, username: str, password: str) -> None:
+        if not username or not password:
+            raise ValueError("username and password are required")
+        payload = {
+            "username": username,
+            "password": password,
+            "redirect": "index.php",
+            "autologin": "on",
+            "login": "Login",
+        }
+        async with self._require_session().post(
+            BASE_URL + "/Forum/ucp.php?mode=login", data=payload
+        ) as response:
+            response.raise_for_status()
+            dom = lxml.html.fromstring(await response.text())
+        messages = dom.xpath('//div[@id="message"]//p/text()')
+        if not messages or messages[0] != "You have been successfully logged in.":
+            raise AuthenticationError("ChickenSmoothie login failed.")
+        self.username = username
+
+    async def is_logged_in(self, username: str | None = None) -> bool:
+        dom = lxml.html.fromstring(await self._text("/"))
+        labels = dom.xpath('//li[@class="icon-logout"]/a/text()')
+        expected = username or self.username
+        return bool(labels and (expected is None or expected in labels[0]))
+
+    async def get_opening_status(self):
+        return parse_opening_status(await self._text("/poundandlostandfound.php"))
+
+    async def get_archive_events(self, year: int, table: TableType = "pets"):
+        if table not in ("pets", "items"):
+            raise ValueError("table must be 'pets' or 'items'")
+        if not isinstance(year, int) or year < 2008:
+            raise ValueError("year must be an integer from 2008 onward")
+        path = f"/archive/{year}/" + ("Items/" if table == "items" else "")
+        dom = lxml.html.fromstring(await self._text(path))
+        return [
+            ArchiveEvent(
+                get_event_title(urlparse(a.get("href")).path),
+                urljoin(BASE_URL, a.get("href")),
+            )
+            for a in dom.cssselect("li.event > a[href]")
+        ]
+
+    async def get_archive_event(self, event: ArchiveEvent, table: TableType, year: int):
+        text = await self._text(event.link.split("?")[0] + "?pageSize=3000")
+        return parse_archive(text, event, table, year)
+
+    async def get_archive(
+        self, pet_id: str, *, years: Iterable[int] | None = None
+    ) -> list[Pet]:
+        """Find all archive records for an image's k ID."""
+        return [entry async for entry in self._iter_pet_matches(pet_id, years)]
+
+    async def _iter_pet_matches(self, pet_id: str, years: Iterable[int] | None):
+        if not isinstance(pet_id, str) or not pet_id.strip():
+            raise ValueError("pet_id must be a nonempty image k ID")
+        if years is None:
+            years = range(2008, datetime.now(timezone.utc).year + 1)
+        for year in dict.fromkeys(years):
+            for event in await self.get_archive_events(year):
+                page = await self.get_archive_event(event, "pets", year)
+                for entry in page.entries:
+                    if isinstance(entry, Pet) and entry.id == pet_id:
+                        yield entry
+
+    async def get_pet(
+        self, pet_id: str, *, years: Iterable[int] | None = None
+    ) -> Pet | None:
+        """Return the first archive record for an image k ID, or None."""
+        async for entry in self._iter_pet_matches(pet_id, years):
+            return entry
+        return None

chickensmoothie-0.1.0/src/chickensmoothie/links.py

@@ -0,0 +1,12 @@
+from urllib.parse import urlparse
+from .archive import parse_item_ids
+
+
+def is_valid_chickensmoothie_link(link: str) -> bool:
+    parsed = urlparse(link)
+    return parsed.scheme in {"http", "https"} and parsed.hostname in {
+        "www.chickensmoothie.com",
+        "chickensmoothie.com",
+        "chickencdn.com",
+        "static.chickensmoothie.com",
+    }

chickensmoothie-0.1.0/src/chickensmoothie/pound.py

@@ -0,0 +1,79 @@
+import re
+import math
+from dataclasses import dataclass
+
+import lxml.html
+
+
+@dataclass
+class OpeningClosed:
+    is_open: bool = False
+    event_type: str | None = None
+    remaining_minutes: int | None = None
+
+
+@dataclass
+class OpeningOpen:
+    is_open: bool = True
+    event_type: str | None = ""
+    remaining_count: int = 0
+
+
+OpeningStatus = OpeningClosed | OpeningOpen
+
+
+def parse_opening_status(text: str) -> OpeningStatus:
+    dom = lxml.html.fromstring(text)
+
+    event_type = get_event_type(
+        normalise(get_first_text(dom, '//div[@id="csbody"]//h2[1]/text()'))
+    )
+    has_pick_countdown = bool(dom.xpath('//*[@id="pound-pick-countdown"]'))
+
+    if has_pick_countdown:
+        remaining_count = extract_remaining_count(dom, event_type)
+        return OpeningOpen(
+            is_open=True, event_type=event_type, remaining_count=remaining_count
+        )
+
+    if match := re.search(r'"timeTillOpen_ms"\s*:\s*(\d+)', text):
+        remaining_ms = int(match.group(1))
+        return OpeningClosed(
+            is_open=False,
+            event_type=event_type,
+            remaining_minutes=max(0, math.floor(remaining_ms / 60000)),
+        )
+
+    return OpeningClosed(
+        is_open=False, event_type=None, remaining_minutes=None
+    )  # If both are closed
+
+
+def normalise(value: str) -> str:
+    return " ".join(value.split())
+
+
+def get_first_text(dom: lxml.html.HtmlElement, xpath: str) -> str:
+    values = dom.xpath(xpath)
+    return str(values[0]) if values else ""
+
+
+def get_event_type(text: str) -> str | None:
+    lowered = text.lower()
+    if "lost and found" in lowered:
+        return "Lost and Found"
+    if "pound" in lowered:
+        return "Pound"
+    return None
+
+
+def extract_remaining_count(dom: lxml.html.HtmlElement, event: str | None) -> int:
+    if event == "Pound":
+        remaining_text = normalise(dom.xpath('string(//*[@id="pets-remaining"])'))
+    else:  # Lost and Found
+        remaining_text = normalise(dom.xpath('string(//*[@id="items-remaining"])'))
+
+    match = re.search(r"\d[\d,]*", remaining_text)
+    if match:
+        return int(match.group().replace(",", ""))
+    return 0

chickensmoothie-0.1.0/src/chickensmoothie.egg-info/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: chickensmoothie
+Version: 0.1.0
+Summary: Unofficial async Python client for Chicken Smoothie
+Author: Haru
+License-Expression: ISC
+Project-URL: Repository, https://github.com/haruyuki/chickensmoothie
+Project-URL: Issues, https://github.com/haruyuki/chickensmoothie/issues
+Keywords: chickensmoothie,pets,archive,asyncio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.13.5
+Requires-Dist: lxml>=6.0.4
+Requires-Dist: cssselect>=1.4.0
+Dynamic: license-file
+
+# chickensmoothie
+
+Unofficial standalone asynchronous client for Chicken Smoothie. Requires Python 3.11+.
+Not affiliated with or endorsed by Chicken Smoothie.
+No Discord, database, environment variables, or bot startup dependencies.
+
+## Installation
+
+From a local checkout:
+
+```powershell
+uv sync
+```
+
+Or install with pip: `python -m pip install .`.
+After the first PyPI release, users can install with `python -m pip install chickensmoothie`.
+
+## Usage
+
+```python
+import asyncio
+import chickensmoothie
+
+async def main():
+    pet = await chickensmoothie.get_pet("IMAGE_K_ID", years=[2026])
+    matches = await chickensmoothie.get_archive("IMAGE_K_ID", years=[2026])
+    async with chickensmoothie.Client() as client:
+        # Login is needed for account-dependent opening information.
+        await client.login("username", "password")
+        status = await client.get_opening_status()
+        events = await client.get_archive_events(2026, "pets")
+        page = await client.get_archive_event(events[0], "pets", 2026)
+        for entry in page.entries:
+            print(entry)
+
+asyncio.run(main())
+```
+
+All network methods are async. `get_pet` returns the first matching `Pet` or
+`None`; `get_archive` returns all matching `Pet` archive records. IDs refer to
+image URL `k` values, as used by the bot's identification database, not numeric
+IDs for individually owned pets. Individual pet profiles are not supported.
+Without `years`, lookups scan archives from 2008 through the current UTC year;
+this can make many requests. Restrict years when possible. The bot retains its
+SQLite index for fast identification instead of scanning on every command.
+
+`get_archive_events(year, "items")` and `get_archive_event(event, "items", year)`
+return item records, including both image IDs, name, year, event and URLs.
+Archive extraction retains the bot's known duplicate-pet exclusions and
+`pageSize=3000` behavior. Events beyond that server response limit are not paged.
+
+Use one `Client` context for repeated calls. `Client(session)` accepts an
+existing aiohttp session and never closes it. Credentials are explicit.
+HTTP failures propagate as aiohttp exceptions; failed login raises
+`AuthenticationError`. Missing archive matches return empty results, while
+HTTP errors are never treated as missing pets.
+
+The bot owns SQLite/MongoDB storage, RSS feed caching, reminder scheduling,
+Discord formatting and image uploads. `NEWS_FEED_URL` exposes the news source
+for other applications to use with their preferred RSS reader.
+
+## Development
+
+Run offline regression tests: `uv run python -m unittest discover -s tests -v`.
+Build release files: `uv build --no-sources`.
+See [RELEASING.md](RELEASING.md) for validation and PyPI upload instructions.
+
+## License
+
+ISC. See [LICENSE](LICENSE). This license applies to the package code, not to
+Chicken Smoothie's images, content, or branding.

chickensmoothie-0.1.0/src/chickensmoothie.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+RELEASING.md
+pyproject.toml
+src/chickensmoothie/__init__.py
+src/chickensmoothie/archive.py
+src/chickensmoothie/client.py
+src/chickensmoothie/links.py
+src/chickensmoothie/pound.py
+src/chickensmoothie.egg-info/PKG-INFO
+src/chickensmoothie.egg-info/SOURCES.txt
+src/chickensmoothie.egg-info/dependency_links.txt
+src/chickensmoothie.egg-info/requires.txt
+src/chickensmoothie.egg-info/top_level.txt
+tests/test_chickensmoothie.py

chickensmoothie-0.1.0/src/chickensmoothie.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chickensmoothie-0.1.0/src/chickensmoothie.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiohttp>=3.13.5
+lxml>=6.0.4
+cssselect>=1.4.0

chickensmoothie-0.1.0/src/chickensmoothie.egg-info/top_level.txt

@@ -0,0 +1 @@
+chickensmoothie

chickensmoothie-0.1.0/tests/test_chickensmoothie.py

@@ -0,0 +1,105 @@
+import unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import aiohttp
+from chickensmoothie import Client, AuthenticationError, Pet
+from chickensmoothie.archive import ArchiveEvent, parse_archive, parse_item_ids
+from chickensmoothie.pound import parse_opening_status
+
+
+class ParsingTests(unittest.TestCase):
+    def test_opening_states(self):
+        open_state = parse_opening_status(
+            '<div id="csbody"><h2>Pound</h2></div><span id="pound-pick-countdown"></span><b id="pets-remaining">1,234 pets</b>'
+        )
+        self.assertTrue(open_state.is_open)
+        self.assertEqual(open_state.remaining_count, 1234)
+        closed = parse_opening_status(
+            '<div id="csbody"><h2>Lost and Found</h2></div><script>{"timeTillOpen_ms": 119999}</script>'
+        )
+        self.assertFalse(closed.is_open)
+        self.assertEqual(closed.remaining_minutes, 1)
+        self.assertIsNone(parse_opening_status("<html>Closed</html>").event_type)
+
+    def test_pet_page_links_and_missing_ids(self):
+        group = '<div class="archive-pet-tree-container"><img alt="Pet" src="/pet.php?k=ABC"><img alt="Pet" src="/invalid"></div>'
+        page = parse_archive(
+            group * 8,
+            ArchiveEvent(
+                "January", "https://www.chickensmoothie.com/archive/2026/January/"
+            ),
+            "pets",
+            2026,
+        )
+        self.assertEqual(page.group_count, 8)
+        self.assertEqual(len(page.entries), 8)
+        self.assertTrue(page.entries[-1].archive_url.endswith("?pageStart=7"))
+        self.assertEqual(page.entries[0].id, "ABC")
+
+    def test_items(self):
+        html = '<div class="archive-item-group"><li class="item"><img src="https://chickencdn.com/item/12&amp;p=34"><div class="item-name"> Hat </div></li><li class="item"></li></div>'
+        page = parse_archive(
+            html,
+            ArchiveEvent(
+                "January", "https://www.chickensmoothie.com/archive/2026/January/Items/"
+            ),
+            "items",
+            2026,
+        )
+        self.assertEqual(len(page.entries), 1)
+        self.assertEqual(
+            (page.entries[0].left_id, page.entries[0].right_id, page.entries[0].name),
+            (12, 34, "Hat"),
+        )
+        self.assertEqual(
+            parse_item_ids("https://example.com/item.php?lid=12&rid=34"), (12, 34)
+        )
+
+
+class ClientTests(unittest.IsolatedAsyncioTestCase):
+    async def test_session_ownership(self):
+        session = MagicMock(closed=False)
+        session.close = AsyncMock()
+        async with Client(session):
+            pass
+        session.close.assert_not_awaited()
+        with patch(
+            "chickensmoothie.client.aiohttp.ClientSession", return_value=session
+        ):
+            async with Client():
+                pass
+        session.close.assert_awaited_once()
+
+    async def test_http_failure_propagates(self):
+        session = MagicMock(closed=False)
+        response = MagicMock()
+        response.raise_for_status.side_effect = aiohttp.ClientError("failure")
+        session.get.return_value.__aenter__ = AsyncMock(return_value=response)
+        with self.assertRaises(aiohttp.ClientError):
+            await Client(session).get_archive_events(2026)
+
+    async def test_login_failure(self):
+        session = MagicMock(closed=False)
+        response = MagicMock()
+        response.text = AsyncMock(
+            return_value='<div id="message"><p>Wrong password</p></div>'
+        )
+        session.post.return_value.__aenter__ = AsyncMock(return_value=response)
+        with self.assertRaises(AuthenticationError):
+            await Client(session).login("user", "password")
+
+    async def test_archive_lookup(self):
+        client = Client()
+        event = ArchiveEvent(
+            "January", "https://www.chickensmoothie.com/archive/2026/January/"
+        )
+        page = parse_archive(
+            '<div class="archive-pet-tree-container"><img alt="Pet" src="/pet.php?k=ABC"></div>',
+            event,
+            "pets",
+            2026,
+        )
+        client.get_archive_events = AsyncMock(return_value=[event])
+        client.get_archive_event = AsyncMock(return_value=page)
+        self.assertIsInstance(await client.get_pet("ABC", years=[2026]), Pet)
+        self.assertIsNone(await client.get_pet("missing", years=[2026]))