pyIntradel 0.0.6__tar.gz → 0.1.0__tar.gz

{pyintradel-0.0.6 → pyintradel-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyIntradel
-Version: 0.0.6
+Version: 0.1.0
 Summary: Python interface for Intradel
 Project-URL: Homepage, https://github.com/thomasgermain/pyintradel
 Author-email: Thomas Germain <12560542+thomasgermain@users.noreply.github.com>
@@ -9,17 +9,13 @@ License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
-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: Topic :: Home Automation
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Requires-Dist: aiohttp<4.0,>=3.11
 Requires-Dist: beautifulsoup4<5.0,>=4.15
-Provides-Extra: dev
-Requires-Dist: build>=1.5; extra == 'dev'
-Requires-Dist: mypy>=2.1; extra == 'dev'
-Requires-Dist: pytest>=9.0; extra == 'dev'
-Requires-Dist: ruff>=0.15; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # pyIntradel
@@ -104,7 +100,15 @@ Here is an example of json:
 
 ## Usage
 
-The `town` parameter is the name of the town, you can check it here: [towns](pyintradel/api/towns.py)
+The intradel.be login form is protected by an invisible reCAPTCHA, so this library
+cannot log in by itself. Authenticate once in a real browser, then pass the resulting
+session cookie (the raw `Cookie` header, e.g. `PHPSESSID=...`).
+
+Errors raised by `api.get_data`, all subclasses of `api.IntradelError` (itself a `ValueError`):
+- `api.AuthenticationError`: the cookie has expired or is invalid; log in again in the
+  browser and use the new cookie.
+- `api.ApiError`: unexpected HTTP status, available as `.status`.
+- `api.ParseError`: the page structure is not the expected one, likely after a website change.
 
 ### Python module
 
@@ -113,13 +117,40 @@ import aiohttp
 from pyintradel import api
 
 async with aiohttp.ClientSession() as sess:
-    await api.get_data(sess, login, password, town)
+    await api.get_data(sess, cookie)
 ```
 
 ### Command line
 ```bash
-python3 -m pyintradel.main user passw town
+python3 -m pyintradel.main --cookie "PHPSESSID=..."
+```
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync                  # create .venv with the dev tools from uv.lock
+uv run pytest
+uv run ruff check
+uv run ruff format
+uv run mypy
+uv build                 # sdist and wheel in dist/
 ```
 
+Install the git pre-commit hook once per clone; it runs ruff (lint with autofix, format) and
+checks that `uv.lock` matches `pyproject.toml` before each commit:
+
+```bash
+uv tool install pre-commit
+pre-commit install
+pre-commit run --all-files   # optional: run the hooks on the whole repository
+```
+
+CI runs the same checks plus mypy and the tests, so skipping the hook only delays the feedback.
+
+To release, publish a GitHub release whose tag is the new version (e.g. `0.1.0`): the
+version is derived from the tag, and CI publishes to PyPI once the checks pass.
+
 ---
 <a href="https://www.buymeacoffee.com/tgermain" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>

{pyintradel-0.0.6 → pyintradel-0.1.0}/README.md

@@ -80,7 +80,15 @@ Here is an example of json:
 
 ## Usage
 
-The `town` parameter is the name of the town, you can check it here: [towns](pyintradel/api/towns.py)
+The intradel.be login form is protected by an invisible reCAPTCHA, so this library
+cannot log in by itself. Authenticate once in a real browser, then pass the resulting
+session cookie (the raw `Cookie` header, e.g. `PHPSESSID=...`).
+
+Errors raised by `api.get_data`, all subclasses of `api.IntradelError` (itself a `ValueError`):
+- `api.AuthenticationError`: the cookie has expired or is invalid; log in again in the
+  browser and use the new cookie.
+- `api.ApiError`: unexpected HTTP status, available as `.status`.
+- `api.ParseError`: the page structure is not the expected one, likely after a website change.
 
 ### Python module
 
@@ -89,13 +97,40 @@ import aiohttp
 from pyintradel import api
 
 async with aiohttp.ClientSession() as sess:
-    await api.get_data(sess, login, password, town)
+    await api.get_data(sess, cookie)
 ```
 
 ### Command line
 ```bash
-python3 -m pyintradel.main user passw town
+python3 -m pyintradel.main --cookie "PHPSESSID=..."
+```
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync                  # create .venv with the dev tools from uv.lock
+uv run pytest
+uv run ruff check
+uv run ruff format
+uv run mypy
+uv build                 # sdist and wheel in dist/
 ```
 
+Install the git pre-commit hook once per clone; it runs ruff (lint with autofix, format) and
+checks that `uv.lock` matches `pyproject.toml` before each commit:
+
+```bash
+uv tool install pre-commit
+pre-commit install
+pre-commit run --all-files   # optional: run the hooks on the whole repository
+```
+
+CI runs the same checks plus mypy and the tests, so skipping the hook only delays the feedback.
+
+To release, publish a GitHub release whose tag is the new version (e.g. `0.1.0`): the
+version is derived from the tag, and CI publishes to PyPI once the checks pass.
+
 ---
 <a href="https://www.buymeacoffee.com/tgermain" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>

pyintradel-0.1.0/pyintradel/api/__init__.py

@@ -0,0 +1,56 @@
+"""pyIntradel"""
+
+import logging
+import re
+from typing import Any
+
+import aiohttp
+
+from . import parser
+from .exceptions import ApiError, AuthenticationError, IntradelError, ParseError
+
+_LOGGER = logging.getLogger(__name__)
+_DATA_URL = "https://www.intradel.be/particulier/data.php"
+# Registrable domain, so cookies set for the host or for the whole domain are both covered.
+_COOKIE_DOMAIN = "intradel.be"
+# Case-insensitive: HTTP/2 dev tools show the header name lowercased.
+_COOKIE_HEADER_PREFIX = re.compile(r"^\s*cookie\s*:", re.IGNORECASE)
+
+
+async def get_data(session: aiohttp.ClientSession, cookie: str) -> list[Any]:
+    """Fetch waste collection data.
+
+    `cookie` is the raw `Cookie` header captured from an already logged-in browser session.
+    The website gates its login form behind an invisible reCAPTCHA, so the library cannot
+    log in by itself.
+
+    Intradel cookies stored in the session's cookie jar are cleared before the request.
+    """
+    cookie = _normalize_cookie(cookie)
+    if not cookie:
+        raise AuthenticationError("No cookie found in the provided value")
+
+    _LOGGER.info("Will query data using a session cookie")
+    # Intradel sets an anonymous PHPSESSID on any request without a session, and aiohttp lets
+    # jar cookies override a hand-written Cookie header: a shared session would otherwise send
+    # that anonymous session instead of ours. The header itself is sent exactly as pasted.
+    session.cookie_jar.clear_domain(_COOKIE_DOMAIN)
+    async with session.get(_DATA_URL, headers={"Cookie": cookie}, allow_redirects=False) as resp:
+        # Intradel redirects to its login page when the session is not valid.
+        if resp.status == 302:
+            raise AuthenticationError()
+        if resp.status != 200:
+            if _LOGGER.isEnabledFor(logging.DEBUG):
+                # Lenient decoding: an error page in an odd charset must not mask the ApiError.
+                body = await resp.text(errors="replace")
+                _LOGGER.debug("HTTP %s body: %s", resp.status, body)
+            raise ApiError(resp.status)
+        return parser.parse(await resp.text())
+
+
+def _normalize_cookie(cookie: str) -> str:
+    """Accept the cookie as copied from browser dev tools, e.g. "Cookie: PHPSESSID=...\\n"."""
+    return _COOKIE_HEADER_PREFIX.sub("", cookie).strip()
+
+
+__all__ = ["ApiError", "AuthenticationError", "IntradelError", "ParseError", "get_data"]

pyintradel-0.1.0/pyintradel/api/exceptions.py

@@ -0,0 +1,31 @@
+class IntradelError(ValueError):
+    """Base class for all errors raised by this library.
+
+    Subclasses ValueError so callers catching the previous generic error keep working.
+    """
+
+
+class AuthenticationError(IntradelError):
+    """Intradel refused the session cookie and sent its login page instead of the data."""
+
+    def __init__(
+        self,
+        message: str = "Session cookie rejected by intradel, it is probably expired or invalid",
+    ) -> None:
+        super().__init__(message)
+
+
+class ApiError(IntradelError):
+    """Intradel answered with an unexpected HTTP status."""
+
+    def __init__(self, status: int) -> None:
+        # args must hold the constructor input, so copy/pickle rebuild the same error.
+        super().__init__(status)
+        self.status = status
+
+    def __str__(self) -> str:
+        return f"HTTP {self.status} from intradel"
+
+
+class ParseError(IntradelError):
+    """The page does not have the expected structure, likely after a website change."""

{pyintradel-0.0.6 → pyintradel-0.1.0}/pyintradel/api/parser.py

@@ -2,6 +2,10 @@ from typing import Any
 
 from bs4 import BeautifulSoup, Tag
 
+from .exceptions import AuthenticationError, ParseError
+
+_UNEXPECTED_STRUCTURE = "Unexpected response structure from intradel"
+
 
 def parse(response: str) -> list[Any]:
     """Parse response from intradel"""
@@ -9,16 +13,20 @@ def parse(response: str) -> list[Any]:
     soup = BeautifulSoup(response, features="html.parser")
 
     if soup.select_one('[name="pLogin"]') is not None:
-        raise ValueError("Wrong response received, login/password seems incorrect", response)
+        raise AuthenticationError()
 
     for data in soup.select(".grid .row .post__content"):
         result: dict[str, Any] = {}
         if data.find("h3") is not None:
-            name = _name(data)
-            start_date = _start_date(data)
-            chip_id = _chip_id(data) or name
-            details = _details(data)
-            total = _total(data) or str(len(details))
+            # The helpers index into the scraped markup; a website change surfaces as IndexError.
+            try:
+                name = _name(data)
+                start_date = _start_date(data)
+                chip_id = _chip_id(data) or name
+                details = _details(data)
+                total = _total(data) or str(len(details))
+            except IndexError as err:
+                raise ParseError(_UNEXPECTED_STRUCTURE) from err
 
             result.update({"name": name})
             result.update({"start_date": start_date})
@@ -33,7 +41,7 @@ def parse(response: str) -> list[Any]:
 def _require_tag(node: object) -> Tag:
     """Narrow a bs4 lookup result to a Tag, failing loudly on unexpected markup."""
     if not isinstance(node, Tag):
-        raise ValueError("Unexpected response structure from intradel")
+        raise ParseError(_UNEXPECTED_STRUCTURE)
     return node
 
 

pyintradel-0.1.0/pyintradel/main.py

@@ -0,0 +1,36 @@
+import argparse
+import asyncio
+import json
+import sys
+
+import aiohttp
+
+from pyintradel import api
+
+
+async def _run(cookie: str) -> None:
+    async with aiohttp.ClientSession() as sess:
+        data = await api.get_data(sess, cookie)
+        json.dump(data, sys.stdout, indent=2)
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="pyintradel")
+    parser.add_argument(
+        "--cookie",
+        required=True,
+        help="Session cookie captured from an already logged-in browser",
+    )
+    return parser.parse_args(argv)
+
+
+def main() -> None:
+    args = _parse_args(sys.argv[1:])
+    try:
+        asyncio.run(_run(args.cookie))
+    except api.IntradelError as err:
+        sys.exit(f"pyintradel: {err}")
+
+
+if __name__ == "__main__":
+    main()

{pyintradel-0.0.6 → pyintradel-0.1.0}/pyproject.toml

@@ -1,14 +1,14 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
 
 [project]
 name = "pyIntradel"
-version = "0.0.6"
+dynamic = ["version"]
 description = "Python interface for Intradel"
 readme = "README.md"
 license = { text = "MIT" }
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 authors = [
     { name = "Thomas Germain", email = "12560542+thomasgermain@users.noreply.github.com" },
 ]
@@ -20,33 +20,39 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Development Status :: 4 - Beta",
     "Programming Language :: Python",
-    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Home Automation",
 ]
 
 [project.urls]
 Homepage = "https://github.com/thomasgermain/pyintradel"
 
-[project.optional-dependencies]
+[dependency-groups]
 dev = [
     "ruff>=0.15",
     "mypy>=2.1",
     "pytest>=9.0",
-    "build>=1.5",
 ]
 
 [project.scripts]
 pyintradel = "pyintradel.main:main"
 
+[tool.hatch.version]
+# The version comes from the release tag (e.g. "0.1.0"), never from this file.
+source = "vcs"
+
 [tool.hatch.build.targets.wheel]
 packages = ["pyintradel"]
 
+# Explicit list, so local untracked files (editor or tool settings) never end up in the sdist.
+[tool.hatch.build.targets.sdist]
+include = ["pyintradel", "tests", "README.md", "LICENSE", "uv.lock"]
+
 [tool.ruff]
 line-length = 100
-target-version = "py312"
-# Large scraped HTML fixture, kept verbatim for parser tests.
-extend-exclude = ["tests/mock.py"]
+target-version = "py313"
 
 [tool.ruff.lint]
 select = [
@@ -61,6 +67,7 @@ select = [
 ]
 
 [tool.mypy]
+files = ["pyintradel", "tests"]
 strict = true
 ignore_missing_imports = true
 show_error_context = true

pyintradel-0.1.0/tests/api_get_data_test.py

@@ -0,0 +1,168 @@
+import pickle
+import unittest
+from typing import Any
+from unittest import mock
+
+import aiohttp
+from aiohttp import web
+from aiohttp.test_utils import TestServer
+from yarl import URL
+
+from pyintradel import api
+from tests.mock import CORRECT_RESPONSE, INCORRECT_LOGIN
+
+
+class _FakeResponse:
+    def __init__(self, status: int, body: str | bytes) -> None:
+        self.status = status
+        self._body = body.encode() if isinstance(body, str) else body
+
+    async def text(self, errors: str = "strict") -> str:
+        return self._body.decode("utf-8", errors)
+
+    async def __aenter__(self) -> "_FakeResponse":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> bool:
+        return False
+
+
+class _FakeCookieJar:
+    def __init__(self) -> None:
+        self.cleared_domains: list[str] = []
+
+    def clear_domain(self, domain: str) -> None:
+        self.cleared_domains.append(domain)
+
+
+class _FakeSession:
+    def __init__(self, response: _FakeResponse) -> None:
+        self._response = response
+        self.cookie_jar = _FakeCookieJar()
+        self.get_calls: list[tuple[str, dict[str, str]]] = []
+        self.allow_redirects: list[bool] = []
+
+    def get(self, url: str, headers: dict[str, str], allow_redirects: bool) -> _FakeResponse:
+        self.get_calls.append((url, headers))
+        self.allow_redirects.append(allow_redirects)
+        return self._response
+
+
+class GetDataTest(unittest.IsolatedAsyncioTestCase):
+    async def test_cookie_is_sent_after_clearing_intradel_cookies(self) -> None:
+        session = _FakeSession(_FakeResponse(200, CORRECT_RESPONSE))
+        result = await api.get_data(session, "PHPSESSID=abc")  # type: ignore[arg-type]
+
+        self.assertEqual(len(result), 3)
+        self.assertEqual(session.get_calls, [(api._DATA_URL, {"Cookie": "PHPSESSID=abc"})])
+        self.assertEqual(session.cookie_jar.cleared_domains, ["intradel.be"])
+
+    async def test_full_browser_header_is_sent_unchanged(self) -> None:
+        # Values a strict cookie parser rejects or rewrites: JSON, spaces, bare flag, attribute
+        # names used as cookie names, commas.
+        raw = (
+            'consent={"a":1}; PHPSESSID=abc; OptanonConsent=datestamp=Thu Oct 24 2026 (CEST); '
+            "flag; path=/; other=a,b"
+        )
+        session = _FakeSession(_FakeResponse(200, CORRECT_RESPONSE))
+        await api.get_data(session, raw)  # type: ignore[arg-type]
+
+        _, headers = session.get_calls[0]
+        self.assertEqual(headers, {"Cookie": raw})
+
+    async def test_empty_cookie_raises_before_any_request(self) -> None:
+        for raw in ("", "   \n", "Cookie:", "  cookie :  \r\n"):
+            session = _FakeSession(_FakeResponse(200, CORRECT_RESPONSE))
+            with self.assertRaisesRegex(api.AuthenticationError, "No cookie found", msg=raw):
+                await api.get_data(session, raw)  # type: ignore[arg-type]
+
+            self.assertEqual(session.get_calls, [], raw)
+
+    async def test_redirect_to_login_raises_authentication_error(self) -> None:
+        session = _FakeSession(_FakeResponse(302, ""))
+        with self.assertRaisesRegex(api.AuthenticationError, "cookie"):
+            await api.get_data(session, "PHPSESSID=expired")  # type: ignore[arg-type]
+
+        # Following the redirect would download and parse the whole login page.
+        self.assertEqual(session.allow_redirects, [False])
+
+    async def test_login_page_served_directly_raises_authentication_error(self) -> None:
+        session = _FakeSession(_FakeResponse(200, INCORRECT_LOGIN))
+        with self.assertRaisesRegex(api.AuthenticationError, "cookie"):
+            await api.get_data(session, "PHPSESSID=expired")  # type: ignore[arg-type]
+
+    async def test_http_error_raises_api_error_without_body(self) -> None:
+        session = _FakeSession(_FakeResponse(503, "<html>" + "x" * 10_000 + "</html>"))
+        with self.assertRaises(api.ApiError) as ctx:
+            await api.get_data(session, "PHPSESSID=abc")  # type: ignore[arg-type]
+
+        self.assertEqual(ctx.exception.status, 503)
+        self.assertEqual(str(ctx.exception), "HTTP 503 from intradel")
+
+    async def test_undecodable_error_body_still_raises_api_error(self) -> None:
+        session = _FakeSession(_FakeResponse(502, b"\xff\xfe not utf-8"))
+        with self.assertLogs("pyintradel.api", "DEBUG"), self.assertRaises(api.ApiError):
+            await api.get_data(session, "PHPSESSID=abc")  # type: ignore[arg-type]
+
+    def test_api_error_survives_pickle(self) -> None:
+        err = pickle.loads(pickle.dumps(api.ApiError(503)))
+
+        self.assertEqual(err.status, 503)
+        self.assertEqual(str(err), "HTTP 503 from intradel")
+
+    async def test_cookie_copied_from_dev_tools_is_normalized(self) -> None:
+        for raw in ("Cookie: PHPSESSID=abc", "cookie:PHPSESSID=abc\n", "  PHPSESSID=abc \r\n"):
+            session = _FakeSession(_FakeResponse(200, CORRECT_RESPONSE))
+            await api.get_data(session, raw)  # type: ignore[arg-type]
+
+            _, headers = session.get_calls[0]
+            self.assertEqual(headers, {"Cookie": "PHPSESSID=abc"}, raw)
+
+
+class SharedSessionTest(unittest.IsolatedAsyncioTestCase):
+    """Real aiohttp client against a local server mimicking intradel's cookie behaviour."""
+
+    async def asyncSetUp(self) -> None:
+        self.received_cookie_headers: list[str] = []
+
+        async def data(request: web.Request) -> web.Response:
+            header = request.headers.get("Cookie", "")
+            self.received_cookie_headers.append(header)
+            # Raw split, like PHP: a strict parser would choke on some real browser cookies.
+            if "PHPSESSID=valid" in [part.strip() for part in header.split(";")]:
+                return web.Response(text=CORRECT_RESPONSE, content_type="text/html")
+            # Like intradel: no valid session, so start an anonymous one and redirect to login.
+            response = web.Response(status=302, headers={"Location": "index.php"})
+            response.set_cookie("PHPSESSID", "anonymous")
+            return response
+
+        app = web.Application()
+        app.router.add_get("/data.php", data)
+        self.server = TestServer(app)
+        await self.server.start_server()
+        self.addAsyncCleanup(self.server.close)
+
+    async def test_cookie_from_earlier_anonymous_request_does_not_override_ours(self) -> None:
+        url = str(self.server.make_url("/data.php"))
+        raw = 'consent={"a":1}; PHPSESSID=valid; flag'
+        # unsafe=True: the default jar ignores cookies from IP addresses such as 127.0.0.1.
+        async with aiohttp.ClientSession(cookie_jar=aiohttp.CookieJar(unsafe=True)) as session:
+            session.cookie_jar.update_cookies({"other": "1"}, URL("https://example.com/"))
+            # Any request without our cookie stores the server's anonymous session in the jar.
+            async with session.get(url, allow_redirects=False) as resp:
+                self.assertEqual(resp.status, 302)
+            self.assertIn("PHPSESSID", [c.key for c in session.cookie_jar])
+
+            with (
+                mock.patch.object(api, "_DATA_URL", url),
+                mock.patch.object(api, "_COOKIE_DOMAIN", self.server.host),
+            ):
+                result = await api.get_data(session, raw)
+
+            remaining = [c.key for c in session.cookie_jar]
+
+        self.assertEqual(len(result), 3)
+        # Sent byte for byte, with nothing from the jar mixed in.
+        self.assertEqual(self.received_cookie_headers[-1], raw)
+        # Cookies of other sites are left alone.
+        self.assertEqual(remaining, ["other"])

pyintradel-0.1.0/tests/api_test.py

@@ -0,0 +1,20 @@
+import unittest
+
+from pyintradel.api.exceptions import AuthenticationError, ParseError
+from pyintradel.api.parser import parse
+from tests.mock import CORRECT_RESPONSE, INCORRECT_LOGIN
+
+
+class ParsingTest(unittest.TestCase):
+    def test_parsing_correct(self) -> None:
+        result = parse(CORRECT_RESPONSE)
+        self.assertEqual(len(result), 3)
+
+    def test_parsing_login_error(self) -> None:
+        self.assertRaises(AuthenticationError, parse, INCORRECT_LOGIN)
+
+    def test_parsing_unexpected_structure(self) -> None:
+        # A bin block whose details are missing, as after a website redesign.
+        html = '<div class="grid"><div class="row"><div class="post__content">'
+        html += "<h3>ORGANIQUE</h3><p>Depuis le : 01-01-2026</p></div></div></div>"
+        self.assertRaises(ParseError, parse, html)