bocconi-sdk 0.2.0__tar.gz

bocconi_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 youatb contributors
+
+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.

bocconi_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: bocconi-sdk
+Version: 0.2.0
+Summary: Unofficial Python SDK for Bocconi University student services (yoU@B portal, Blackboard, Esse3)
+License-Expression: MIT
+Keywords: bocconi,youatb,blackboard,esse3,university,student
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: websocket-client>=1.7
+Requires-Dist: tzdata>=2024.1; platform_system == "Windows"
+Dynamic: license-file
+
+# Bocconi Software Development Kit
+
+Unofficial Python SDK for **Bocconi University student services**. One
+username/password login unlocks every subsystem through the shared SAML2 SSO
+(`idp.unibocconi.it`). Reverse-engineered from live traffic.
+
+## Subsystems
+
+| Package | System | What you get |
+|---|---|---|
+| `bocconi.youatb` | **yoU@B portal** (`youatb.unibocconi.it`) | Dashboard widgets (SignalR 2.x `widgethub`), lesson calendar JSON feed, profile/careers, language switching |
+| `bocconi.youatb.puntoblu` | **Esse3 / PuntoBlu** (`www.pb.unibocconi.it`) | Student info, exam sessions, grades booklet, fees/certificates/… (HTML scraping) |
+| `bocconi.blackboard` | **Blackboard** (`blackboard.unibocconi.it`) | Courses, deadlines/to-dos, messages, announcements, unread counters, activity stream |
+
+## Install
+
+```powershell
+cd bocconi-sdk
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+```
+
+Dependencies: `requests`, `websocket-client`. Python ≥ 3.9.
+
+## Quickstart — parent client (recommended)
+
+```python
+from datetime import date
+from bocconi import BocconiClient
+
+with BocconiClient("1234567", "your-password") as client:
+    client.login()                       # one SAML login unlocks everything
+
+    yt = client.youatb                   # yoU@B portal
+    print(yt.profile.name, yt.student_id)
+    widgets = yt.dashboard()             # SignalR widgethub
+    for ev in yt.calendar(date(2026, 8, 31), date(2026, 9, 6)):
+        print(ev.start, ev.course_name, ev.room)
+
+    bb = client.blackboard               # Blackboard Ultra
+    for course in bb.courses():
+        print(course.display_id, course.name)
+    for item in bb.todo().future:
+        print(item.due_date, item.title)
+
+    pb = yt.puntoblu                     # Esse3
+    print(pb.student_info().degree_program)
+    print(pb.exam_sessions()[:3])
+```
+
+## Standalone children
+
+Each subsystem also works independently (own session, own login):
+
+```python
+from bocconi.youatb import YouAtBClient
+from bocconi.blackboard import BlackboardClient
+
+with YouAtBClient("1234567", "pw") as yt:
+    yt.login()
+    print(yt.calendar())
+
+bb = BlackboardClient.authenticate("1234567", "pw")   # SAML via Blackboard's SP
+print(bb.me())
+```
+
+Or attach children to an existing authenticated session:
+`YouAtBClient.from_session(session)`, `BlackboardClient.from_session(session)`.
+
+## API overview
+
+### `BocconiClient(username, password, lang="en")`
+
+- `login()` / `logout()` / `close()` — context manager supported.
+- `.youatb` → `YouAtBClient`, `.blackboard` → `BlackboardClient` (lazy).
+- `fetch(url)` — GET any Bocconi SP URL with automatic SSO completion.
+
+### `bocconi.youatb.YouAtBClient`
+
+- `login()`, `profile` (name, photo, careers), `student_id`,
+  `set_career(...)`, `set_language("ita"|"eng")`
+- `dashboard(widget_ids=None)` / `load_widgets(ids)` → `WidgetResult`
+  (`WidgetContent`: `.content_type`, `.url`, `.links`, `.text`; widget-ID
+  constants exported from `bocconi.youatb`)
+- `calendar(start=None, end=None)` → `list[CalendarEvent]` — typed lessons:
+  course code/name, class, professors, room/building/floor, lat/lon, tz-aware
+  Europe/Rome datetimes
+- `.puntoblu` → `PuntoBluClient`
+
+### `bocconi.youatb.puntoblu.PuntoBluClient`
+
+- `student_info()` → `StudentInfo` (bilingual eng/ita, enrolment history)
+- `exam_sessions()` → `list[ExamSession]` — dates, type (partial/general),
+  enrolment windows, booking status/link
+- `booklet()` → `list[BookletEntry]` — credits, year, status, grades
+- `menu()`, `get(path)` + `PB_*` path constants; career interstitial handled
+  automatically (`select_career(stu_id)`)
+
+### `bocconi.blackboard.BlackboardClient`
+
+- `me()` → `BbUser`; `courses()` / `recent_courses()` → `list[BbCourse]`
+- `todo(since=None, until=None)` → `BbTodo` — actionable deadlines grouped
+  `.overdue`/.`due_today`/`.future` (>15-day ranges auto-chunked)
+- `calendar_items` / `deadlines(since, until)` → `list[BbCalendarItem]`
+  (calendar view, keeps completed items)
+- `announcements(course_id)`, `conversations(course_id)`,
+  `message_summary()`, `announcement_counts` / `conversation_counts` /
+  `unread_grades_count` / `discussion_unread_count(course_id)`
+- `calendars()`, `terms()`, `course_membership(course_id)`, `stream()`,
+  `system_preference(key)`, `entitlements()`, `api_get(path)`
+
+## Notes & caveats
+
+- The portal hub speaks **ASP.NET SignalR 2.x** (`clientProtocol=2.1`) — *not*
+  ASP.NET Core SignalR; a minimal 2.x client is bundled
+  (`bocconi.youatb.signalr.SignalR2Client`).
+- Blackboard's SP sends the SAMLRequest via **HTTP-POST binding** — handled
+  transparently by `bocconi.auth` for all services.
+- Hub/Esse3 HTML fragments are **untrusted server-rendered markup**; the SDK
+  never executes embedded scripts, `.text` strips tags.
+- Sessions expire server-side; on `SessionExpiredError` call `login()` again.
+- Unofficial project, not affiliated with Università Bocconi. Use
+  responsibly: don't hammer the servers, don't share session cookies.
+
+This SDK currently does not cover the full range of features offered by the Bocconi yoU@B/Blackboard ecosystem, so feel free to open a pull request
+
+Run the full demo:
+
+```powershell
+$env:YOUATB_USER = "1234567"
+$env:YOUATB_PASS = "your-password"
+python examples/demo.py
+```

bocconi_sdk-0.2.0/README.md

@@ -0,0 +1,134 @@
+# Bocconi Software Development Kit
+
+Unofficial Python SDK for **Bocconi University student services**. One
+username/password login unlocks every subsystem through the shared SAML2 SSO
+(`idp.unibocconi.it`). Reverse-engineered from live traffic.
+
+## Subsystems
+
+| Package | System | What you get |
+|---|---|---|
+| `bocconi.youatb` | **yoU@B portal** (`youatb.unibocconi.it`) | Dashboard widgets (SignalR 2.x `widgethub`), lesson calendar JSON feed, profile/careers, language switching |
+| `bocconi.youatb.puntoblu` | **Esse3 / PuntoBlu** (`www.pb.unibocconi.it`) | Student info, exam sessions, grades booklet, fees/certificates/… (HTML scraping) |
+| `bocconi.blackboard` | **Blackboard** (`blackboard.unibocconi.it`) | Courses, deadlines/to-dos, messages, announcements, unread counters, activity stream |
+
+## Install
+
+```powershell
+cd bocconi-sdk
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+```
+
+Dependencies: `requests`, `websocket-client`. Python ≥ 3.9.
+
+## Quickstart — parent client (recommended)
+
+```python
+from datetime import date
+from bocconi import BocconiClient
+
+with BocconiClient("1234567", "your-password") as client:
+    client.login()                       # one SAML login unlocks everything
+
+    yt = client.youatb                   # yoU@B portal
+    print(yt.profile.name, yt.student_id)
+    widgets = yt.dashboard()             # SignalR widgethub
+    for ev in yt.calendar(date(2026, 8, 31), date(2026, 9, 6)):
+        print(ev.start, ev.course_name, ev.room)
+
+    bb = client.blackboard               # Blackboard Ultra
+    for course in bb.courses():
+        print(course.display_id, course.name)
+    for item in bb.todo().future:
+        print(item.due_date, item.title)
+
+    pb = yt.puntoblu                     # Esse3
+    print(pb.student_info().degree_program)
+    print(pb.exam_sessions()[:3])
+```
+
+## Standalone children
+
+Each subsystem also works independently (own session, own login):
+
+```python
+from bocconi.youatb import YouAtBClient
+from bocconi.blackboard import BlackboardClient
+
+with YouAtBClient("1234567", "pw") as yt:
+    yt.login()
+    print(yt.calendar())
+
+bb = BlackboardClient.authenticate("1234567", "pw")   # SAML via Blackboard's SP
+print(bb.me())
+```
+
+Or attach children to an existing authenticated session:
+`YouAtBClient.from_session(session)`, `BlackboardClient.from_session(session)`.
+
+## API overview
+
+### `BocconiClient(username, password, lang="en")`
+
+- `login()` / `logout()` / `close()` — context manager supported.
+- `.youatb` → `YouAtBClient`, `.blackboard` → `BlackboardClient` (lazy).
+- `fetch(url)` — GET any Bocconi SP URL with automatic SSO completion.
+
+### `bocconi.youatb.YouAtBClient`
+
+- `login()`, `profile` (name, photo, careers), `student_id`,
+  `set_career(...)`, `set_language("ita"|"eng")`
+- `dashboard(widget_ids=None)` / `load_widgets(ids)` → `WidgetResult`
+  (`WidgetContent`: `.content_type`, `.url`, `.links`, `.text`; widget-ID
+  constants exported from `bocconi.youatb`)
+- `calendar(start=None, end=None)` → `list[CalendarEvent]` — typed lessons:
+  course code/name, class, professors, room/building/floor, lat/lon, tz-aware
+  Europe/Rome datetimes
+- `.puntoblu` → `PuntoBluClient`
+
+### `bocconi.youatb.puntoblu.PuntoBluClient`
+
+- `student_info()` → `StudentInfo` (bilingual eng/ita, enrolment history)
+- `exam_sessions()` → `list[ExamSession]` — dates, type (partial/general),
+  enrolment windows, booking status/link
+- `booklet()` → `list[BookletEntry]` — credits, year, status, grades
+- `menu()`, `get(path)` + `PB_*` path constants; career interstitial handled
+  automatically (`select_career(stu_id)`)
+
+### `bocconi.blackboard.BlackboardClient`
+
+- `me()` → `BbUser`; `courses()` / `recent_courses()` → `list[BbCourse]`
+- `todo(since=None, until=None)` → `BbTodo` — actionable deadlines grouped
+  `.overdue`/.`due_today`/`.future` (>15-day ranges auto-chunked)
+- `calendar_items` / `deadlines(since, until)` → `list[BbCalendarItem]`
+  (calendar view, keeps completed items)
+- `announcements(course_id)`, `conversations(course_id)`,
+  `message_summary()`, `announcement_counts` / `conversation_counts` /
+  `unread_grades_count` / `discussion_unread_count(course_id)`
+- `calendars()`, `terms()`, `course_membership(course_id)`, `stream()`,
+  `system_preference(key)`, `entitlements()`, `api_get(path)`
+
+## Notes & caveats
+
+- The portal hub speaks **ASP.NET SignalR 2.x** (`clientProtocol=2.1`) — *not*
+  ASP.NET Core SignalR; a minimal 2.x client is bundled
+  (`bocconi.youatb.signalr.SignalR2Client`).
+- Blackboard's SP sends the SAMLRequest via **HTTP-POST binding** — handled
+  transparently by `bocconi.auth` for all services.
+- Hub/Esse3 HTML fragments are **untrusted server-rendered markup**; the SDK
+  never executes embedded scripts, `.text` strips tags.
+- Sessions expire server-side; on `SessionExpiredError` call `login()` again.
+- Unofficial project, not affiliated with Università Bocconi. Use
+  responsibly: don't hammer the servers, don't share session cookies.
+
+This SDK currently does not cover the full range of features offered by the Bocconi yoU@B/Blackboard ecosystem, so feel free to open a pull request
+
+Run the full demo:
+
+```powershell
+$env:YOUATB_USER = "1234567"
+$env:YOUATB_PASS = "your-password"
+python examples/demo.py
+```

bocconi_sdk-0.2.0/bocconi/__init__.py

@@ -0,0 +1,48 @@
+"""Unofficial Python SDK for Bocconi University student services.
+
+One SAML2 SSO login (idp.unibocconi.it) unlocks all subsystems:
+
+  * :mod:`bocconi.youatb`     — yoU@B portal (SignalR widgets, calendar,
+    profile/careers) and the Esse3 "PuntoBlu" student area
+  * :mod:`bocconi.blackboard` — Blackboard Learn Ultra (courses, deadlines,
+    messages, announcements, activity stream)
+
+Quickstart::
+
+    from bocconi import BocconiClient
+
+    with BocconiClient("1234567", "secret") as client:
+        client.login()
+        client.youatb.dashboard()
+        client.blackboard.courses()
+
+Reverse-engineered from the live services; see youatb-docs.md in the
+sibling ``youatb_re`` project for the full protocol write-up. Unofficial,
+not affiliated with Università Bocconi.
+"""
+
+from . import blackboard, youatb
+from .client import BocconiClient
+from .exceptions import (
+    AuthenticationError,
+    InvalidCredentials,
+    SessionExpiredError,
+    SignalRError,
+    WidgetError,
+    YouAtBError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "BocconiClient",
+    "youatb",
+    "blackboard",
+    # errors
+    "YouAtBError",
+    "AuthenticationError",
+    "InvalidCredentials",
+    "SessionExpiredError",
+    "SignalRError",
+    "WidgetError",
+]

bocconi_sdk-0.2.0/bocconi/auth.py

@@ -0,0 +1,217 @@
+"""SAML2 Web-SSO login against the Bocconi Shibboleth IdP.
+
+Implements the flow documented in youatb-docs.md §2/§5:
+
+    GET <SP protected URL>            -> 302 chain to idp.unibocconi.it
+    GET  IdP login page               -> form with `execution` webflow token
+    POST j_username/j_password        -> 200 auto-submit form (SAMLResponse)
+    POST SAMLResponse to SP ACS URL   -> 302 back, SP session cookies set
+
+No JavaScript is executed; the auto-submit forms are parsed and replayed.
+"""
+
+from __future__ import annotations
+
+import html as _html
+import logging
+import re
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from typing import Dict, List, Optional
+from urllib.parse import urljoin
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    InvalidCredentials,
+    SessionExpiredError,
+)
+
+log = logging.getLogger(__name__)
+
+IDP_HOST = "idp.unibocconi.it"
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36"
+)
+
+_CRED_FAIL_RE = re.compile(
+    r"loginfailed|credentials not recognized|login failed|password.*incorrect",
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Minimal HTML form extraction (stdlib only)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HtmlForm:
+    action: str = ""
+    method: str = "get"
+    inputs: Dict[str, str] = field(default_factory=dict)
+
+
+class _FormParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.forms: List[HtmlForm] = []
+        self._current: Optional[HtmlForm] = None
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        attrs = dict(attrs)
+        if tag == "form":
+            self._current = HtmlForm(
+                action=attrs.get("action", ""),
+                method=attrs.get("method", "get").lower(),
+            )
+        elif tag == "input" and self._current is not None:
+            name = attrs.get("name")
+            if name:
+                self._current.inputs[name] = attrs.get("value", "")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "form" and self._current is not None:
+            self.forms.append(self._current)
+            self._current = None
+
+
+def extract_forms(html_text: str) -> List[HtmlForm]:
+    parser = _FormParser()
+    parser.feed(html_text)
+    return parser.forms
+
+
+def _find_saml_form(html_text: str) -> Optional[HtmlForm]:
+    """Find an auto-submit SAML form.
+
+    Two kinds occur in Bocconi SSO flows:
+      * ``SAMLResponse`` — IdP -> SP (the common case, POST binding response)
+      * ``SAMLRequest``  — SP  -> IdP (POST binding *request*; Blackboard's
+        ``/auth-saml/saml/login`` uses this instead of a 302 redirect)
+    """
+    for form in extract_forms(html_text):
+        if "SAMLResponse" in form.inputs or "SAMLRequest" in form.inputs:
+            return form
+    return None
+
+
+def _find_password_form(html_text: str) -> Optional[HtmlForm]:
+    for form in extract_forms(html_text):
+        if "j_password" in form.inputs or "j_username" in form.inputs:
+            return form
+    return None
+
+
+# ---------------------------------------------------------------------------
+# SAML plumbing
+# ---------------------------------------------------------------------------
+
+def complete_saml_posts(
+    session: requests.Session,
+    response: requests.Response,
+    max_hops: int = 10,
+) -> requests.Response:
+    """Replay auto-submit SAML forms until a real page is reached.
+
+    Handles both directions of the POST binding: IdP->SP ``SAMLResponse``
+    forms (youatb, www.pb, app, ...) and SP->IdP ``SAMLRequest`` forms
+    (Blackboard's ``/auth-saml/saml/login``).
+    """
+    for _ in range(max_hops):
+        form = _find_saml_form(response.text)
+        if form is None:
+            return response
+        action = urljoin(response.url, _html.unescape(form.action))
+        log.debug("SAML POST -> %s", action)
+        response = session.post(action, data=form.inputs, timeout=30)
+    raise AuthenticationError("Too many SAML redirect hops")
+
+
+def has_session_cookie(session: requests.Session) -> bool:
+    """True if the jar holds a session marker of any known Bocconi service."""
+    markers = (".ASPXAUTH", "BbRouter", "samlCookie")
+    return any(
+        c.name in markers or c.name.startswith("_shibsession_")
+        for c in session.cookies
+    )
+
+
+def login(
+    session: requests.Session,
+    entry_url: str,
+    username: str,
+    password: str,
+) -> requests.Response:
+    """Perform a full username/password login starting from any SP entry URL.
+
+    Works for the yoU@B portal (``https://youatb.unibocconi.it/``) as well as
+    for SPs that emit the SAMLRequest via POST binding, e.g. Blackboard
+    (``https://blackboard.unibocconi.it/ultra/institution-page``): the chain
+    eventually reaches the IdP password form either way.
+
+    Returns the final authenticated response.
+
+    Raises:
+        InvalidCredentials: the IdP rejected the credentials.
+        AuthenticationError: any other flow failure.
+    """
+    log.info("Opening %s", entry_url)
+    resp = session.get(entry_url, timeout=30)
+    resp = complete_saml_posts(session, resp)
+
+    pw_form = _find_password_form(resp.text)
+    if pw_form is None:
+        # No login form: either already authenticated (existing IdP session
+        # silently SSO'd us in) or something unexpected happened.
+        if has_session_cookie(session):
+            log.info("Authenticated via existing IdP SSO session")
+            return resp
+        raise AuthenticationError(
+            f"No login form found and no session established (final URL: {resp.url})"
+        )
+
+    action = urljoin(resp.url, _html.unescape(pw_form.action))
+    payload = dict(pw_form.inputs)  # keep any hidden webflow fields
+    payload["j_username"] = username
+    payload["j_password"] = password
+    payload["_eventId_proceed"] = ""
+    log.info("Posting credentials to %s", action)
+    resp = session.post(action, data=payload, timeout=30)
+
+    if "SAMLResponse" not in resp.text:
+        if _CRED_FAIL_RE.search(resp.text) or _find_password_form(resp.text):
+            raise InvalidCredentials("IdP rejected the username/password")
+        raise AuthenticationError(
+            f"Unexpected IdP response (no SAMLResponse, URL: {resp.url})"
+        )
+
+    resp = complete_saml_posts(session, resp)
+
+    if not has_session_cookie(session):
+        raise AuthenticationError(
+            "SAML flow completed but no session cookie was set by the SP"
+        )
+    log.info("Login successful")
+    return resp
+
+
+def ensure_service_session(
+    session: requests.Session,
+    url: str,
+) -> requests.Response:
+    """GET a protected URL on any Bocconi SP, completing SSO if needed.
+
+    With a live IdP session this is silent: the SP bounces us to the IdP and
+    straight back with a fresh SAMLResponse. Raises SessionExpiredError if the
+    IdP asks for credentials again.
+    """
+    resp = session.get(url, timeout=30)
+    resp = complete_saml_posts(session, resp)
+    if IDP_HOST in resp.url and _find_password_form(resp.text):
+        raise SessionExpiredError(
+            "IdP SSO session expired; call YouAtBClient.login() again"
+        )
+    return resp

bocconi_sdk-0.2.0/bocconi/blackboard/__init__.py

@@ -0,0 +1,26 @@
+"""Blackboard Learn Ultra subsystem: courses, deadlines/to-dos, messages,
+announcements, activity stream."""
+
+from .client import (
+    BbAnnouncement,
+    BbCalendar,
+    BbCalendarItem,
+    BbConversation,
+    BbCourse,
+    BbTodo,
+    BbTodoItem,
+    BbUser,
+    BlackboardClient,
+)
+
+__all__ = [
+    "BlackboardClient",
+    "BbUser",
+    "BbCourse",
+    "BbConversation",
+    "BbAnnouncement",
+    "BbCalendarItem",
+    "BbCalendar",
+    "BbTodo",
+    "BbTodoItem",
+]