pymabibli 0.0.1__tar.gz

pymabibli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bestycame
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymabibli-0.0.1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: pymabibli
+Version: 0.0.1
+Summary: An async Python client for mabibli.be, the libraries of the Province of Liège
+Home-page: https://github.com/bestycame/pymabibli
+Author: Bestycame
+Author-email: bestycame@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: beautifulsoup4>=4.12
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Mabibli Python Client
+## NOT OFFICIALLY SUPPORTED BY THE PROVINCE DE LIÈGE --
+
+An async Python client library for [mabibli.be](https://mabibli.be/), the library network of the Province of Liège.
+This client logs in with your library card and reads your account, loans and borrowing history, and can renew loans.
+Developped for a Home Assistant integration. At least for now.
+
+## Installation
+You can install the package using pip:
+
+```bash
+pip install pymabibli
+```
+
+## Usage
+
+Here's a basic example of how to use the client:
+
+```python
+import asyncio
+
+from pymabibli import MabibliClient
+
+
+async def main():
+    async with MabibliClient("your-card-number", "your-password") as client:
+        # Log in (also done automatically by the other methods)
+        await client.login()
+
+        # Get account information
+        account = await client.get_account()
+        print(f"Membership ends: {account.subscription_end}")
+
+        # Get current loans
+        loans = await client.get_loans()
+        for loan in loans:
+            print(f"{loan.title} [{loan.library}] due {loan.due_date}")
+
+        # Get borrowing history
+        history = await client.get_history()
+        print(f"{len(history)} items borrowed")
+
+        # Renew one loan
+        messages = await client.renew_loan(loans[0])
+
+        # Renew all loans ("Tout prolonger")
+        messages = await client.renew_all()
+
+
+asyncio.run(main())
+```
+
+You can pass your own `aiohttp.ClientSession` with `session=`; the client then leaves it open when closing.
+The login is kept in the session's cookie jar, so each client needs a session of its own:
+two cards sharing one session would see each other's account.
+In Home Assistant, use `async_create_clientsession(hass)` per config entry, not the shared `async_get_clientsession(hass)`.
+
+## Error Handling
+
+The client provides specific exception classes:
+
+### Exception Classes
+
+- `MabibliError`: Base exception for all errors
+- `MabibliAuthError`: Raised when the card number or password is rejected
+- `MabibliConnectionError`: Raised when the site can't be reached or returns an unexpected page
+- `MabibliRenewError`: Raised when a loan can't be renewed or the site refuses the renewal
+
+### Example Error Handling
+
+```python
+from pymabibli import MabibliAuthError, MabibliClient, MabibliRenewError
+
+async def renew_everything():
+    async with MabibliClient("your-card-number", "your-password") as client:
+        try:
+            loans = await client.get_loans()
+        except MabibliAuthError as e:
+            print(f"Login failed: {e}")
+            return
+
+        for loan in loans:
+            if not loan.renewable:
+                continue
+            try:
+                await client.renew_loan(loan)
+            except MabibliRenewError as e:
+                print(f"Could not renew {loan.title}: {e}")
+```
+
+### Authentication
+
+mabibli.be authenticates through a CAS server (`centralcas.gminvent.fr`).
+The client logs in on first use and logs in again when the site's session expires.
+Renewals are never retried automatically: if the session is lost during a renewal, `MabibliAuthError` is raised
+and you should check the loan before trying again.
+
+### API Methods
+
+- `login() -> None`: Log in with the card number and password
+- `get_account() -> Account`: Get name, card number and membership end date
+- `get_loans() -> list[Loan]`: Get current loans, across all pages
+- `get_history() -> list[Loan]`: Get previously borrowed items, newest first, across all pages
+- `renew_loan(loan: Loan) -> list[Message]`: Renew one loan and return the site's messages
+- `renew_all() -> list[Message]`: Renew all renewable loans and return the site's messages
+
+## Development
+
+```bash
+pipenv install --dev
+pipenv run pytest
+pipenv run flake8
+```
+
+The scripts in `examples/` run against the real site with your own card.
+`examples/renew.py` really renews a loan, after asking which one.
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.

pymabibli-0.0.1/README.md

@@ -0,0 +1,119 @@
+# Mabibli Python Client
+## NOT OFFICIALLY SUPPORTED BY THE PROVINCE DE LIÈGE --
+
+An async Python client library for [mabibli.be](https://mabibli.be/), the library network of the Province of Liège.
+This client logs in with your library card and reads your account, loans and borrowing history, and can renew loans.
+Developped for a Home Assistant integration. At least for now.
+
+## Installation
+You can install the package using pip:
+
+```bash
+pip install pymabibli
+```
+
+## Usage
+
+Here's a basic example of how to use the client:
+
+```python
+import asyncio
+
+from pymabibli import MabibliClient
+
+
+async def main():
+    async with MabibliClient("your-card-number", "your-password") as client:
+        # Log in (also done automatically by the other methods)
+        await client.login()
+
+        # Get account information
+        account = await client.get_account()
+        print(f"Membership ends: {account.subscription_end}")
+
+        # Get current loans
+        loans = await client.get_loans()
+        for loan in loans:
+            print(f"{loan.title} [{loan.library}] due {loan.due_date}")
+
+        # Get borrowing history
+        history = await client.get_history()
+        print(f"{len(history)} items borrowed")
+
+        # Renew one loan
+        messages = await client.renew_loan(loans[0])
+
+        # Renew all loans ("Tout prolonger")
+        messages = await client.renew_all()
+
+
+asyncio.run(main())
+```
+
+You can pass your own `aiohttp.ClientSession` with `session=`; the client then leaves it open when closing.
+The login is kept in the session's cookie jar, so each client needs a session of its own:
+two cards sharing one session would see each other's account.
+In Home Assistant, use `async_create_clientsession(hass)` per config entry, not the shared `async_get_clientsession(hass)`.
+
+## Error Handling
+
+The client provides specific exception classes:
+
+### Exception Classes
+
+- `MabibliError`: Base exception for all errors
+- `MabibliAuthError`: Raised when the card number or password is rejected
+- `MabibliConnectionError`: Raised when the site can't be reached or returns an unexpected page
+- `MabibliRenewError`: Raised when a loan can't be renewed or the site refuses the renewal
+
+### Example Error Handling
+
+```python
+from pymabibli import MabibliAuthError, MabibliClient, MabibliRenewError
+
+async def renew_everything():
+    async with MabibliClient("your-card-number", "your-password") as client:
+        try:
+            loans = await client.get_loans()
+        except MabibliAuthError as e:
+            print(f"Login failed: {e}")
+            return
+
+        for loan in loans:
+            if not loan.renewable:
+                continue
+            try:
+                await client.renew_loan(loan)
+            except MabibliRenewError as e:
+                print(f"Could not renew {loan.title}: {e}")
+```
+
+### Authentication
+
+mabibli.be authenticates through a CAS server (`centralcas.gminvent.fr`).
+The client logs in on first use and logs in again when the site's session expires.
+Renewals are never retried automatically: if the session is lost during a renewal, `MabibliAuthError` is raised
+and you should check the loan before trying again.
+
+### API Methods
+
+- `login() -> None`: Log in with the card number and password
+- `get_account() -> Account`: Get name, card number and membership end date
+- `get_loans() -> list[Loan]`: Get current loans, across all pages
+- `get_history() -> list[Loan]`: Get previously borrowed items, newest first, across all pages
+- `renew_loan(loan: Loan) -> list[Message]`: Renew one loan and return the site's messages
+- `renew_all() -> list[Message]`: Renew all renewable loans and return the site's messages
+
+## Development
+
+```bash
+pipenv install --dev
+pipenv run pytest
+pipenv run flake8
+```
+
+The scripts in `examples/` run against the real site with your own card.
+`examples/renew.py` really renews a loan, after asking which one.
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.

pymabibli-0.0.1/pymabibli/__init__.py

@@ -0,0 +1,21 @@
+"""Async client for mabibli.be."""
+
+from .client import MabibliClient
+from .exceptions import (
+    MabibliAuthError,
+    MabibliConnectionError,
+    MabibliError,
+    MabibliRenewError,
+)
+from .models import Account, Loan, Message
+
+__all__ = [
+    "Account",
+    "Loan",
+    "MabibliAuthError",
+    "MabibliClient",
+    "MabibliConnectionError",
+    "MabibliError",
+    "MabibliRenewError",
+    "Message",
+]

pymabibli-0.0.1/pymabibli/client.py

@@ -0,0 +1,214 @@
+"""Client for mabibli.be, which authenticates through the GMInvent CAS server."""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+import logging
+from typing import Self
+from urllib.parse import urljoin, urlsplit
+
+import aiohttp
+
+from .exceptions import MabibliAuthError, MabibliConnectionError, MabibliRenewError
+from .models import Account, Loan, Message
+from .parsers import (
+    BASE_URL,
+    is_logged_in,
+    parse_account,
+    parse_loans_page,
+    parse_messages,
+    parse_renew_all_url,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+ACCOUNT_PATH = "/user"
+LOANS_PATH = "/page/user/prets-en-cours"
+HISTORY_PATH = "/page/user/mon-historique"
+MAX_PAGES = 100
+CAS_HOST = "centralcas.gminvent.fr"
+CAS_LOGIN_URL = f"https://{CAS_HOST}/cas/login"
+SERVICE_URL = f"{BASE_URL}/casservice"
+DEFAULT_SILO = "Chirx"
+
+
+class _FormParser(HTMLParser):
+    """Collect the input fields of the CAS login form."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.fields: dict[str, str] = {}
+        self.has_error = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        attributes = dict(attrs)
+        if tag == "input" and attributes.get("name"):
+            self.fields[attributes["name"]] = attributes.get("value") or ""
+        # Apereo CAS renders failed logins in an element with id "loginErrorsPanel"
+        if attributes.get("id") == "loginErrorsPanel":
+            self.has_error = True
+
+
+class MabibliClient:
+    """Log in to mabibli.be and keep the authenticated session.
+
+    The login lives in the session's cookie jar, so a session passed in must be
+    dedicated to this client: sharing one between two cards mixes their accounts.
+    """
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        session: aiohttp.ClientSession | None = None,
+        silo: str = DEFAULT_SILO,
+    ) -> None:
+        self._username = username
+        self._password = password
+        self._silo = silo
+        self._session = session
+        self._close_session = session is None
+        self.logged_in = False
+
+    async def login(self) -> None:
+        """Authenticate against CAS and land on mabibli.be with a session cookie."""
+        params = {
+            "fromDrupalBGM": "Non",
+            "fromDrupalSilo": self._silo,
+            "service": SERVICE_URL,
+        }
+        page, page_url = await self._fetch(CAS_LOGIN_URL, params=params)
+        # A still valid CAS cookie skips the form and redirects straight to the service
+        if urlsplit(page_url).hostname != CAS_HOST:
+            self.logged_in = True
+            return
+        form = _FormParser()
+        form.feed(page)
+        if "execution" not in form.fields:
+            raise MabibliConnectionError("CAS login form not found")
+
+        data = {
+            "username": self._username,
+            "password": self._password,
+            "customFields[silo]": self._silo,
+            "execution": form.fields["execution"],
+            "_eventId": "submit",
+            "geolocation": "",
+        }
+        try:
+            async with self._get_session().post(
+                CAS_LOGIN_URL, params=params, data=data
+            ) as response:
+                body = await response.text()
+                final_url = response.url
+                status = response.status
+        except aiohttp.ClientError as err:
+            raise MabibliConnectionError(err) from err
+
+        # On success CAS redirects to the service with a ticket, which mabibli.be
+        # exchanges for its own session cookie.
+        if final_url.host == CAS_HOST:
+            result = _FormParser()
+            result.feed(body)
+            if result.has_error or status == 401:
+                raise MabibliAuthError("Invalid card number or password")
+            raise MabibliConnectionError(f"Login did not redirect (HTTP {status})")
+        self.logged_in = True
+
+    async def get_account(self) -> Account:
+        """Return the reader's name, card number and membership end date."""
+        html, _ = await self._get_authenticated(ACCOUNT_PATH)
+        return parse_account(html)
+
+    async def get_loans(self) -> list[Loan]:
+        """Return the items currently on loan, across all pages."""
+        return await self._get_paged_loans(LOANS_PATH)
+
+    async def get_history(self) -> list[Loan]:
+        """Return previously borrowed items, newest first, across all pages."""
+        return await self._get_paged_loans(HISTORY_PATH)
+
+    async def renew_loan(self, loan: Loan) -> list[Message]:
+        """Renew one loan and return the messages the site showed.
+
+        Raises MabibliRenewError if the site reports an error.
+        """
+        if loan.renew_url is None:
+            raise MabibliRenewError(f"{loan.title} cannot be renewed")
+        # Make sure the session is valid first, so the renewal is sent exactly once
+        await self._get_authenticated(LOANS_PATH)
+        return await self._send_renewal(loan.renew_url)
+
+    async def renew_all(self) -> list[Message]:
+        """Renew every renewable loan, like the "Tout prolonger" button."""
+        html, page_url = await self._get_authenticated(LOANS_PATH)
+        url = parse_renew_all_url(html, page_url)
+        if url is None:
+            raise MabibliRenewError("No loans can be renewed")
+        return await self._send_renewal(url)
+
+    async def _send_renewal(self, url: str) -> list[Message]:
+        # Renewal links are state-changing GETs, so they are never retried
+        html, _ = await self._fetch(url)
+        if not is_logged_in(html):
+            self.logged_in = False
+            raise MabibliAuthError("Session lost while renewing; check the loan before retrying")
+        messages = parse_messages(html)
+        if errors := [m.text for m in messages if m.level == "error"]:
+            raise MabibliRenewError("; ".join(errors))
+        return messages
+
+    async def _get_paged_loans(self, path: str) -> list[Loan]:
+        loans: list[Loan] = []
+        url = path
+        visited: set[str] = set()
+        for _ in range(MAX_PAGES):
+            html, page_url = await self._get_authenticated(url)
+            visited.add(page_url)
+            page_loans, next_url = parse_loans_page(html, page_url)
+            loans.extend(page_loans)
+            if next_url is None or next_url in visited:
+                return loans
+            url = next_url
+        _LOGGER.warning("Stopped after %s pages of %s; the list is incomplete", MAX_PAGES, path)
+        return loans
+
+    async def _get_authenticated(self, url: str) -> tuple[str, str]:
+        """Fetch a page, logging in first or again if the Drupal session expired."""
+        url = urljoin(BASE_URL, url)
+        if not self.logged_in:
+            await self.login()
+        html, final_url = await self._fetch(url)
+        if is_logged_in(html):
+            return html, final_url
+        self.logged_in = False
+        await self.login()
+        html, final_url = await self._fetch(url)
+        if not is_logged_in(html):
+            raise MabibliAuthError("Session not accepted after login")
+        return html, final_url
+
+    async def _fetch(self, url: str, **kwargs) -> tuple[str, str]:
+        """Return the body and the final URL after redirects."""
+        try:
+            async with self._get_session().get(urljoin(BASE_URL, url), **kwargs) as response:
+                response.raise_for_status()
+                return await response.text(), str(response.url)
+        except aiohttp.ClientError as err:
+            raise MabibliConnectionError(err) from err
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def close(self) -> None:
+        if self._close_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()

pymabibli-0.0.1/pymabibli/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for pymabibli."""
+
+
+class MabibliError(Exception):
+    """Base error."""
+
+
+class MabibliConnectionError(MabibliError):
+    """The site could not be reached or returned an unexpected response."""
+
+
+class MabibliAuthError(MabibliError):
+    """The card number or password was rejected."""
+
+
+class MabibliRenewError(MabibliError):
+    """The library refused to renew a loan."""

pymabibli-0.0.1/pymabibli/models.py

@@ -0,0 +1,46 @@
+"""Data models for pymabibli."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+
+
+@dataclass(frozen=True)
+class Account:
+    """The reader's account summary."""
+
+    first_name: str
+    last_name: str
+    card_number: str
+    subscription_end: date | None
+    subscription_type: str | None
+
+
+@dataclass(frozen=True)
+class Message:
+    """A status message the site shows after an action, e.g. a renewal."""
+
+    level: str
+    text: str
+
+
+@dataclass(frozen=True)
+class Loan:
+    """A borrowed item."""
+
+    title: str
+    notice_id: str | None
+    document_type: str | None
+    authors: tuple[str, ...]
+    publisher: str | None
+    library: str | None
+    loan_date: date | None
+    due_date: date | None
+    renew_url: str | None
+    # Public; redirects to the cover image, or a generic placeholder when there is none
+    cover_url: str | None = None
+
+    @property
+    def renewable(self) -> bool:
+        return self.renew_url is not None

pymabibli-0.0.1/pymabibli/parsers.py

@@ -0,0 +1,176 @@
+"""Parse the HTML pages of mabibli.be (Drupal + BGM modules)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import date, datetime
+import json
+import re
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup, Tag
+
+from .exceptions import MabibliConnectionError
+from .models import Account, Loan, Message
+
+BASE_URL = "https://mabibli.be"
+_DATE_RE = re.compile(r"(\d{2})[-/](\d{2})[-/](\d{4})")
+# The theme uses Bootstrap alerts; core Drupal markup is kept as a fallback
+_MESSAGE_LEVELS = {
+    "alert-danger": "error",
+    "messages--error": "error",
+    "alert-warning": "warning",
+    "messages--warning": "warning",
+    "alert-success": "status",
+    "alert-info": "status",
+    "messages--status": "status",
+}
+_MESSAGE_SELECTOR = ", ".join(f".{cls}" for cls in _MESSAGE_LEVELS)
+
+
+def is_logged_in(html: str) -> bool:
+    return "/user/logout" in html
+
+
+def parse_account(html: str) -> Account:
+    user = _soup(html).select_one(".user--type-user")
+    if user is None:
+        raise MabibliConnectionError("Account block not found")
+    end = _text(user.select_one(".field--name-field-date-fin-d-abonnement .field__item"))
+    return Account(
+        first_name=_text(user.select_one(".field--name-field-prenom")) or "",
+        last_name=_text(user.select_one(".field--name-field-nom")) or "",
+        card_number=_text(user.select_one(".field--name-username")) or "",
+        subscription_end=_parse_date(end),
+        subscription_type=_text(user.select_one(".field--name-field-type-abonnement")),
+    )
+
+
+def parse_loans_page(html: str, page_url: str = BASE_URL) -> tuple[list[Loan], str | None]:
+    """Return the loans on a page and the URL of the next page, if any."""
+    soup = _soup(html)
+    return _loans(soup, page_url), _next_page_url(soup, page_url)
+
+
+def parse_loans(html: str, page_url: str = BASE_URL) -> list[Loan]:
+    return _loans(_soup(html), page_url)
+
+
+def parse_next_page_url(html: str, page_url: str = BASE_URL) -> str | None:
+    """Return the "Suivant" link of a paged list, or None on the last page."""
+    return _next_page_url(_soup(html), page_url)
+
+
+def parse_renew_all_url(html: str, page_url: str = BASE_URL) -> str | None:
+    link = _soup(html).select_one(".toutprolonger a.button__prolongation[href]")
+    return _absolute(link.get("href") if link else None, page_url)
+
+
+def parse_messages(html: str) -> list[Message]:
+    soup = _soup(html)
+    containers = soup.select("[data-drupal-messages], .messages__wrapper") or [soup]
+    messages: list[Message] = []
+    seen: set[int] = set()
+    for container in containers:
+        for element in container.select(_MESSAGE_SELECTOR):
+            # A wrapper and its inner alert can both carry a message class
+            if id(element) in seen or _has_message_ancestor(element, container):
+                continue
+            seen.add(id(element))
+            level = next(_MESSAGE_LEVELS[c] for c in element.get("class") or [] if c in _MESSAGE_LEVELS)
+            if text := _text(element):
+                messages.append(Message(level, text))
+    return messages
+
+
+def _soup(html: str) -> BeautifulSoup:
+    """Parse a page, including the blocks Drupal BigPipe streams as JSON scripts."""
+    soup = BeautifulSoup(html, "html.parser")
+    for script in soup.select("script[data-big-pipe-replacement-for-placeholder-with-id]"):
+        try:
+            commands = json.loads(script.string or "")
+        except ValueError:
+            continue
+        for command in commands:
+            if command.get("command") == "insert" and command.get("data"):
+                script.insert_before(BeautifulSoup(command["data"], "html.parser"))
+        script.decompose()
+    return soup
+
+
+def _loans(soup: BeautifulSoup, page_url: str) -> list[Loan]:
+    loans: list[Loan] = []
+    for pret in soup.select("div.pret"):
+        item = pret.parent
+        if not isinstance(item, Tag):
+            continue
+        title_link = item.select_one(".field--name-node-title a")
+        renew = pret.select_one("a.button__prolongation")
+        cover = item.select_one(".field--name-field-couverture img[src]")
+        loans.append(
+            Loan(
+                title=_clean_title(_text(title_link) or ""),
+                notice_id=_notice_id(title_link.get("href") if title_link else None),
+                document_type=_text(item.select_one(".typedoc")),
+                authors=_unique(
+                    _text(a)
+                    for a in item.select(".field--name-field-auteurs .field__item")
+                ),
+                publisher=_text(item.select_one(".field--name-field-editeur .field__item")),
+                library=_text(pret.select_one(".mediatheque div")),
+                loan_date=_parse_date(_text(pret.select_one(".field--name-field-date-emprunt"))),
+                due_date=_parse_date(_text(pret.select_one(".field--name-field-date-de-retour"))),
+                renew_url=_absolute(renew.get("href") if renew else None, page_url),
+                cover_url=_absolute(cover.get("src") if cover else None, page_url),
+            )
+        )
+    return loans
+
+
+def _next_page_url(soup: BeautifulSoup, page_url: str) -> str | None:
+    for link in soup.select(".pager a[href]"):
+        if "suivant" in link.get_text().lower():
+            return _absolute(link.get("href"), page_url)
+    return None
+
+
+def _has_message_ancestor(element: Tag, container: Tag) -> bool:
+    for parent in element.parents:
+        if parent is container:
+            return False
+        if any(c in _MESSAGE_LEVELS for c in parent.get("class") or []):
+            return True
+    return False
+
+
+def _absolute(href: object, page_url: str) -> str | None:
+    return urljoin(page_url, href) if isinstance(href, str) else None
+
+
+def _text(tag: Tag | None) -> str | None:
+    if tag is None:
+        return None
+    return " ".join(tag.get_text(" ").split()) or None
+
+
+def _parse_date(value: str | None) -> date | None:
+    if not value or not (match := _DATE_RE.search(value)):
+        return None
+    day, month, year = match.groups()
+    return datetime(int(year), int(month), int(day)).date()
+
+
+def _clean_title(title: str) -> str:
+    # The catalogue marks the leading article with "|", e.g. "L'| Atelier"
+    title = re.sub(r"(['’])\|\s*", r"\1", title)
+    return re.sub(r"\s*\|\s*", " ", title).strip()
+
+
+def _notice_id(href: object) -> str | None:
+    if isinstance(href, str) and (match := re.search(r"/notice/(\d+)", href)):
+        return match.group(1)
+    return None
+
+
+def _unique(values: Iterable[str | None]) -> tuple[str, ...]:
+    return tuple(dict.fromkeys(v for v in values if v))

pymabibli-0.0.1/pymabibli.egg-info/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: pymabibli
+Version: 0.0.1
+Summary: An async Python client for mabibli.be, the libraries of the Province of Liège
+Home-page: https://github.com/bestycame/pymabibli
+Author: Bestycame
+Author-email: bestycame@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: beautifulsoup4>=4.12
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Mabibli Python Client
+## NOT OFFICIALLY SUPPORTED BY THE PROVINCE DE LIÈGE --
+
+An async Python client library for [mabibli.be](https://mabibli.be/), the library network of the Province of Liège.
+This client logs in with your library card and reads your account, loans and borrowing history, and can renew loans.
+Developped for a Home Assistant integration. At least for now.
+
+## Installation
+You can install the package using pip:
+
+```bash
+pip install pymabibli
+```
+
+## Usage
+
+Here's a basic example of how to use the client:
+
+```python
+import asyncio
+
+from pymabibli import MabibliClient
+
+
+async def main():
+    async with MabibliClient("your-card-number", "your-password") as client:
+        # Log in (also done automatically by the other methods)
+        await client.login()
+
+        # Get account information
+        account = await client.get_account()
+        print(f"Membership ends: {account.subscription_end}")
+
+        # Get current loans
+        loans = await client.get_loans()
+        for loan in loans:
+            print(f"{loan.title} [{loan.library}] due {loan.due_date}")
+
+        # Get borrowing history
+        history = await client.get_history()
+        print(f"{len(history)} items borrowed")
+
+        # Renew one loan
+        messages = await client.renew_loan(loans[0])
+
+        # Renew all loans ("Tout prolonger")
+        messages = await client.renew_all()
+
+
+asyncio.run(main())
+```
+
+You can pass your own `aiohttp.ClientSession` with `session=`; the client then leaves it open when closing.
+The login is kept in the session's cookie jar, so each client needs a session of its own:
+two cards sharing one session would see each other's account.
+In Home Assistant, use `async_create_clientsession(hass)` per config entry, not the shared `async_get_clientsession(hass)`.
+
+## Error Handling
+
+The client provides specific exception classes:
+
+### Exception Classes
+
+- `MabibliError`: Base exception for all errors
+- `MabibliAuthError`: Raised when the card number or password is rejected
+- `MabibliConnectionError`: Raised when the site can't be reached or returns an unexpected page
+- `MabibliRenewError`: Raised when a loan can't be renewed or the site refuses the renewal
+
+### Example Error Handling
+
+```python
+from pymabibli import MabibliAuthError, MabibliClient, MabibliRenewError
+
+async def renew_everything():
+    async with MabibliClient("your-card-number", "your-password") as client:
+        try:
+            loans = await client.get_loans()
+        except MabibliAuthError as e:
+            print(f"Login failed: {e}")
+            return
+
+        for loan in loans:
+            if not loan.renewable:
+                continue
+            try:
+                await client.renew_loan(loan)
+            except MabibliRenewError as e:
+                print(f"Could not renew {loan.title}: {e}")
+```
+
+### Authentication
+
+mabibli.be authenticates through a CAS server (`centralcas.gminvent.fr`).
+The client logs in on first use and logs in again when the site's session expires.
+Renewals are never retried automatically: if the session is lost during a renewal, `MabibliAuthError` is raised
+and you should check the loan before trying again.
+
+### API Methods
+
+- `login() -> None`: Log in with the card number and password
+- `get_account() -> Account`: Get name, card number and membership end date
+- `get_loans() -> list[Loan]`: Get current loans, across all pages
+- `get_history() -> list[Loan]`: Get previously borrowed items, newest first, across all pages
+- `renew_loan(loan: Loan) -> list[Message]`: Renew one loan and return the site's messages
+- `renew_all() -> list[Message]`: Renew all renewable loans and return the site's messages
+
+## Development
+
+```bash
+pipenv install --dev
+pipenv run pytest
+pipenv run flake8
+```
+
+The scripts in `examples/` run against the real site with your own card.
+`examples/renew.py` really renews a loan, after asking which one.
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.

pymabibli-0.0.1/pymabibli.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+setup.py
+pymabibli/__init__.py
+pymabibli/client.py
+pymabibli/exceptions.py
+pymabibli/models.py
+pymabibli/parsers.py
+pymabibli.egg-info/PKG-INFO
+pymabibli.egg-info/SOURCES.txt
+pymabibli.egg-info/dependency_links.txt
+pymabibli.egg-info/requires.txt
+pymabibli.egg-info/top_level.txt
+tests/test_client.py
+tests/test_parsers.py

pymabibli-0.0.1/pymabibli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pymabibli-0.0.1/pymabibli.egg-info/requires.txt

@@ -0,0 +1,2 @@
+aiohttp>=3.9
+beautifulsoup4>=4.12

pymabibli-0.0.1/pymabibli.egg-info/top_level.txt

@@ -0,0 +1 @@
+pymabibli

pymabibli-0.0.1/setup.cfg

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

pymabibli-0.0.1/setup.py

@@ -0,0 +1,32 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="pymabibli",
+    version="0.0.1",
+    author="Bestycame",
+    author_email="bestycame@gmail.com",
+    description="An async Python client for mabibli.be, the libraries of the Province of Liège",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/bestycame/pymabibli",
+    packages=find_packages(exclude=["tests", "tests.*", "examples"]),
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Framework :: AsyncIO",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
+    ],
+    python_requires=">=3.12",
+    install_requires=[
+        "aiohttp>=3.9",
+        "beautifulsoup4>=4.12",
+    ],
+)

pymabibli-0.0.1/tests/test_client.py

@@ -0,0 +1,156 @@
+"""Tests for the client, with page fetching stubbed out."""
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+
+from pymabibli import MabibliAuthError, MabibliClient, MabibliRenewError, Message
+from pymabibli.client import CAS_LOGIN_URL, SERVICE_URL
+
+FIXTURES = Path(__file__).parent / "fixtures"
+HISTORY_URL = "https://mabibli.be/page/user/mon-historique"
+LOANS_URL = "https://mabibli.be/page/user/prets-en-cours"
+RENEW_URL = "https://mabibli.be/bgm--prolongation--byId/1/He/2/L25vZGUvMQ=="
+RENEW_ALL_URL = "https://mabibli.be/bgm--toutprolongation--byId/L25vZGUvMQ=="
+LOGGED_OUT_PAGE = "<html><a href='/user/login'>Connexion</a></html>"
+
+
+def _fixture(name: str) -> str:
+    return (FIXTURES / name).read_text(encoding="utf-8")
+
+
+def _history_page(next_href: str) -> str:
+    return (
+        "<a href='/user/logout'>X</a>"
+        "<div class='field__item'><div class='notice'><div class='field--name-node-title'>"
+        "<a href='/notice/1'>Livre</a></div></div><div class='pret'></div></div>"
+        f"<div class='pager'><a href='{next_href}'>Suivant</a></div>"
+    )
+
+
+class FakeSite:
+    """Serve fixture pages by URL, follow fake redirects, and record requests."""
+
+    def __init__(self) -> None:
+        self.pages: dict[str, str] = {}
+        self.redirects: dict[str, str] = {}
+        self.requested: list[str] = []
+
+    async def fetch(self, url: str, **kwargs: object) -> tuple[str, str]:
+        self.requested.append(url)
+        final_url = self.redirects.get(url, url)
+        return self.pages[final_url], final_url
+
+
+@pytest.fixture
+def site() -> FakeSite:
+    return FakeSite()
+
+
+@pytest_asyncio.fixture
+async def client(site: FakeSite, monkeypatch: pytest.MonkeyPatch) -> AsyncIterator[MabibliClient]:
+    async with MabibliClient("041000000000", "secret") as client:
+        # Skip the CAS login; it is covered by the live example script
+        client.logged_in = True
+        monkeypatch.setattr(client, "_fetch", site.fetch)
+        yield client
+
+
+def test_client_can_be_created_outside_event_loop() -> None:
+    MabibliClient("041000000000", "secret")
+
+
+@pytest.mark.asyncio
+async def test_login_with_valid_cas_cookie(client: MabibliClient, site: FakeSite) -> None:
+    client.logged_in = False
+    site.redirects[CAS_LOGIN_URL] = SERVICE_URL
+    site.pages[SERVICE_URL] = "<a href='/user/logout'>X</a>"
+
+    await client.login()
+
+    assert client.logged_in
+    assert site.requested == [CAS_LOGIN_URL]
+
+
+@pytest.mark.asyncio
+async def test_get_history_follows_pages(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[HISTORY_URL] = _fixture("history_page1.html")
+    site.pages[f"{HISTORY_URL}?prh=1"] = _fixture("history_page2.html")
+
+    loans = await client.get_history()
+
+    assert [loan.title for loan in loans] == ["Premier livre", "Second livre"]
+    assert site.requested == [HISTORY_URL, f"{HISTORY_URL}?prh=1"]
+
+
+@pytest.mark.asyncio
+async def test_get_history_resolves_relative_pager_link(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[HISTORY_URL] = _history_page("?prh=1")
+    site.pages[f"{HISTORY_URL}?prh=1"] = _fixture("history_page2.html")
+
+    await client.get_history()
+
+    assert site.requested == [HISTORY_URL, f"{HISTORY_URL}?prh=1"]
+
+
+@pytest.mark.asyncio
+async def test_get_history_stops_on_repeated_page(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[HISTORY_URL] = _history_page("/page/user/mon-historique")
+
+    loans = await client.get_history()
+
+    assert len(loans) == 1
+    assert site.requested == [HISTORY_URL]
+
+
+@pytest.mark.asyncio
+async def test_renew_loan(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[LOANS_URL] = _fixture("loans.html")
+    site.pages[RENEW_URL] = _fixture("renew_success.html")
+    loan = (await client.get_loans())[0]
+
+    assert await client.renew_loan(loan) == [Message("status", "Prolongation effectuée")]
+    assert site.requested[-2:] == [LOANS_URL, RENEW_URL]
+
+
+@pytest.mark.asyncio
+async def test_renew_loan_refused(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[LOANS_URL] = _fixture("loans.html")
+    site.pages[RENEW_URL] = _fixture("renew_error.html")
+    loan = (await client.get_loans())[0]
+
+    with pytest.raises(MabibliRenewError, match="document réservé"):
+        await client.renew_loan(loan)
+
+
+@pytest.mark.asyncio
+async def test_renew_loan_is_not_retried(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[LOANS_URL] = _fixture("loans.html")
+    site.pages[RENEW_URL] = LOGGED_OUT_PAGE
+    loan = (await client.get_loans())[0]
+
+    with pytest.raises(MabibliAuthError, match="check the loan"):
+        await client.renew_loan(loan)
+
+    assert site.requested.count(RENEW_URL) == 1
+    assert not client.logged_in
+
+
+@pytest.mark.asyncio
+async def test_renew_loan_not_renewable(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[LOANS_URL] = _fixture("loans.html")
+    loan = (await client.get_loans())[1]
+
+    with pytest.raises(MabibliRenewError, match="cannot be renewed"):
+        await client.renew_loan(loan)
+
+
+@pytest.mark.asyncio
+async def test_renew_all(client: MabibliClient, site: FakeSite) -> None:
+    site.pages[LOANS_URL] = _fixture("loans.html")
+    site.pages[RENEW_ALL_URL] = _fixture("renew_success.html")
+
+    assert await client.renew_all() == [Message("status", "Prolongation effectuée")]
+    assert site.requested == [LOANS_URL, RENEW_ALL_URL]

pymabibli-0.0.1/tests/test_parsers.py

@@ -0,0 +1,129 @@
+"""Tests for the HTML parsers."""
+
+from datetime import date
+from pathlib import Path
+
+import pytest
+
+from pymabibli import MabibliError
+from pymabibli.models import Message
+from pymabibli.parsers import (
+    is_logged_in,
+    parse_account,
+    parse_loans,
+    parse_messages,
+    parse_next_page_url,
+    parse_renew_all_url,
+)
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def _fixture(name: str) -> str:
+    return (FIXTURES / name).read_text(encoding="utf-8")
+
+
+def test_parse_account() -> None:
+    account = parse_account(_fixture("account.html"))
+    assert account.first_name == "Jeanne"
+    assert account.last_name == "DUPONT"
+    assert account.card_number == "041000000000"
+    assert account.subscription_end == date(2027, 3, 1)
+    assert account.subscription_type == "03 - Adulte (03)"
+
+
+def test_parse_account_unexpected_page() -> None:
+    with pytest.raises(MabibliError, match="Account block not found"):
+        parse_account("<html><a href='/user/logout'>X</a></html>")
+
+
+def test_parse_loans() -> None:
+    first, second = parse_loans(_fixture("loans.html"))
+
+    assert first.title == "L'Atelier des petits artistes"
+    assert first.notice_id == "111"
+    assert first.document_type == "Livre"
+    assert first.authors == ("Wilkes, Angela (1952-....)", "Doe, John Illustrateur")
+    assert first.publisher == "Larousse"
+    assert first.library == "Geer"
+    assert first.loan_date == date(2026, 9, 20)
+    assert first.due_date == date(2026, 11, 22)
+    assert first.renew_url == "https://mabibli.be/bgm--prolongation--byId/1/He/2/L25vZGUvMQ=="
+    assert first.cover_url == "https://mabibli.be/bgm--couverture/1"
+
+    assert second.title == "Le Grand voyage"
+    assert second.document_type == "DVD"
+    assert second.authors == ()
+    assert second.publisher is None
+    assert second.due_date == date(2026, 11, 5)
+    assert not second.renewable
+    assert second.cover_url is None
+
+    assert len({first, second}) == 2
+
+
+def test_parse_loans_resolves_against_page_url() -> None:
+    html = (
+        "<div class='field__item'><div class='field--name-field-couverture'><img src='cover/1'></div>"
+        "<div class='pret'><div class='prolongation'>"
+        "<a class='button__prolongation' href='../renew/1'>Prolonger</a></div></div></div>"
+    )
+    (loan,) = parse_loans(html, "https://mabibli.be/page/user/prets-en-cours")
+    assert loan.renew_url == "https://mabibli.be/page/renew/1"
+    assert loan.cover_url == "https://mabibli.be/page/user/cover/1"
+
+
+def test_clean_title_with_typographic_apostrophe() -> None:
+    html = (
+        "<div class='field__item'><div class='field--name-node-title'><a>L’| Été</a></div>"
+        "<div class='pret'></div></div>"
+    )
+    assert parse_loans(html)[0].title == "L’Été"
+
+
+def test_parse_loans_from_bigpipe() -> None:
+    (loan,) = parse_loans(_fixture("loans_bigpipe.html"))
+    assert loan.title == "L'Atelier des petits artistes"
+    assert loan.library == "Geer"
+    assert loan.due_date == date(2026, 11, 22)
+    assert loan.renewable
+
+
+def test_parse_next_page_url() -> None:
+    assert (
+        parse_next_page_url(_fixture("history_page1.html"))
+        == "https://mabibli.be/page/user/mon-historique?prh=1"
+    )
+    assert parse_next_page_url(_fixture("history_page2.html")) is None
+
+
+def test_parse_renew_all_url() -> None:
+    assert (
+        parse_renew_all_url(_fixture("loans.html"))
+        == "https://mabibli.be/bgm--toutprolongation--byId/L25vZGUvMQ=="
+    )
+    assert parse_renew_all_url(_fixture("history_page1.html")) is None
+
+
+def test_parse_messages() -> None:
+    assert parse_messages(_fixture("renew_success.html")) == [
+        Message("status", "Prolongation effectuée")
+    ]
+    assert parse_messages(_fixture("renew_error.html")) == [
+        Message("error", "Prolongation impossible : document réservé")
+    ]
+    assert parse_messages(_fixture("loans.html")) == []
+
+
+def test_parse_messages_ignores_alerts_outside_message_area() -> None:
+    html = (
+        "<div class='alert alert-danger'>Retard sur un document</div>"
+        "<div data-drupal-messages><div class='messages messages--error'>"
+        "<div class='alert alert-danger'>Prolongation impossible</div></div></div>"
+    )
+    assert parse_messages(html) == [Message("error", "Prolongation impossible")]
+
+
+def test_is_logged_in() -> None:
+    assert is_logged_in(_fixture("loans.html"))
+    assert not is_logged_in("<html><a href='/user/login'>Connexion</a></html>")