nusmods-api 0.1.0__tar.gz

nusmods_api-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.3
+Name: nusmods-api
+Version: 0.1.0
+Summary: A Python wrapper for the NUSMods API
+Author: kommade
+Author-email: kommade <khoojarrell@gmail.com>
+Requires-Dist: requests>=2.34.2
+Requires-Python: >=3.15.0
+Description-Content-Type: text/markdown
+
+# nusmods-api
+
+A typed Python wrapper for the [NUSMods API](https://api.nusmods.com/).
+
+The client provides access to module lists, detailed module information, venue
+data, and shared timetable URLs from [nusmods.com](https://nusmods.com/).
+Responses are converted into immutable Python dataclasses.
+
+## Requirements
+
+- Python 3.15 or newer
+- Internet access when making API requests
+
+## Installation
+
+### With uv
+
+```powershell
+uv add nusmods-api
+```
+
+For local development:
+
+```powershell
+uv sync
+```
+
+### With pip
+
+```powershell
+pip install nusmods-api
+```
+
+## Quick start
+
+```python
+from nusmods_api import NUSModsClient
+
+client = NUSModsClient(academic_year="2026-2027")
+
+modules = client.get_module_list()
+for module in modules[:5]:
+    print(module.moduleCode, module.title)
+
+module = client.get_module("CS2030S")
+print(module.title)
+print(module.description)
+```
+
+If no academic year is supplied, the client uses the current calendar year and
+the following year. For example, a client created in 2026 uses `2026-2027`.
+
+## Client configuration
+
+```python
+from nusmods_api import NUSModsClient
+
+client = NUSModsClient(
+    academic_year="2026-2027",
+    timeout=20.0,
+    cache_directory=".nusmods_cache",
+    cache_expiration=86_400,
+)
+```
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `academic_year` | Current year and next year | Academic year in `YYYY-YYYY` format |
+| `timeout` | `10.0` | HTTP timeout in seconds |
+| `cache_directory` | `.nusmods_cache` | Directory for cached JSON responses |
+| `cache_expiration` | `86400` | Cache lifetime in seconds; use `None` for no expiration |
+
+Set `cache_directory=None` to disable caching:
+
+```python
+client = NUSModsClient(cache_directory=None)
+```
+
+## API usage
+
+### Module list
+
+```python
+modules = client.get_module_list()
+
+for module in modules:
+    print(module.moduleCode, module.title, module.semesters)
+```
+
+### Detailed module information
+
+```python
+modules = client.get_module_information()
+module = client.get_module(" cs2030s ")
+
+print(module.moduleCode)  # CS2030S
+print(module.acadYear)
+print(module.semesterData)
+```
+
+Module codes are stripped and normalized to uppercase by `get_module`.
+
+### Venues
+
+```python
+venues = client.get_venues(semester=1)
+print(venues)
+
+venue_information = client.get_venue_information(semester=1)
+for venue, entries in venue_information.items():
+    print(venue, entries)
+```
+
+`semester` must be `1` or `2`.
+
+### Shared timetables
+
+Pass a NUSMods share URL to `get_shared_timetable`:
+
+```python
+share_url = (
+    "https://nusmods.com/timetable/sem-1/share?"
+    "CS1231S=TUT:25B,LEC:1&"
+    "CS2030S=REC:04,LAB:10B,LEC:1&"
+    "GES1034=LEC:1,TUT:E2&"
+    "IS1108=TUT:14,LEC:2&"
+    "MA1522=LEC:1"
+)
+
+timetable = client.get_shared_timetable(share_url)
+
+for lesson in timetable.weekly:
+    print(
+        lesson.moduleCode,
+        lesson.lessonType,
+        lesson.classNo,
+        lesson.day,
+        lesson.startTime,
+        lesson.endTime,
+        lesson.venue,
+    )
+
+for exam in timetable.exams:
+    print(exam.moduleCode, exam.examDate, exam.examDuration)
+```
+
+The client parses the module selections from the URL and retrieves the
+corresponding module data from the NUSMods API. Lesson type codes such as
+`LEC`, `TUT`, `LAB`, and `REC` are mapped to their full names.
+
+`Timetable` also provides convenience methods:
+
+```python
+monday = timetable.get_day_schedule("Monday")
+exam = timetable.get_exam_for_module("CS2030S")
+```
+
+## Data models
+
+The package exposes frozen dataclasses for common API response types:
+
+- `ModuleCondensed` — module code, title, and offered semesters
+- `Module` — detailed module information
+- `Lesson` — class schedule information
+- `LessonWithModule` — a lesson including its module code
+- `VenueLesson` and `VenueInformation` — venue timetable data
+- `WeekRange` — date-based lesson ranges
+- `Workload` — workload components
+- `PrerequisiteTree` — nested prerequisite expressions
+- `ExamTimetable` — exam information
+- `Timetable` — selected weekly lessons and exams
+
+Some model fields retain the NUSMods API naming convention, such as
+`moduleCode`, `classNo`, `startTime`, `lessonType`, and `examDate`.
+
+## Error handling
+
+The client raises package-specific exceptions:
+
+```python
+from nusmods_api import (
+    NUSModsHTTPError,
+    NUSModsInvalidResponseError,
+    NUSModsNotFoundError,
+    NUSModsRequestError,
+)
+
+try:
+    module = client.get_module("CS2030S")
+except NUSModsNotFoundError:
+    print("The module or academic year was not found")
+except NUSModsHTTPError as error:
+    print(error.status_code, error.url)
+except NUSModsInvalidResponseError:
+    print("The API returned invalid JSON")
+except NUSModsRequestError:
+    print("The API could not be reached")
+```
+
+Invalid client arguments, malformed share URLs, invalid semesters, and
+unmatched lesson selections raise `ValueError`.
+
+## Testing
+
+Run the default unit test suite:
+
+```powershell
+uv run pytest
+```
+
+The live integration test makes real requests to the NUSMods API:
+
+```powershell
+uv run pytest tests/test_live_client.py -m live -q
+```
+
+The live test requires internet access and may need its expected timetable
+dates updated when NUSMods publishes a new academic-year dataset.
+
+## License
+
+No license has been specified yet.

nusmods_api-0.1.0/README.md

@@ -0,0 +1,222 @@
+# nusmods-api
+
+A typed Python wrapper for the [NUSMods API](https://api.nusmods.com/).
+
+The client provides access to module lists, detailed module information, venue
+data, and shared timetable URLs from [nusmods.com](https://nusmods.com/).
+Responses are converted into immutable Python dataclasses.
+
+## Requirements
+
+- Python 3.15 or newer
+- Internet access when making API requests
+
+## Installation
+
+### With uv
+
+```powershell
+uv add nusmods-api
+```
+
+For local development:
+
+```powershell
+uv sync
+```
+
+### With pip
+
+```powershell
+pip install nusmods-api
+```
+
+## Quick start
+
+```python
+from nusmods_api import NUSModsClient
+
+client = NUSModsClient(academic_year="2026-2027")
+
+modules = client.get_module_list()
+for module in modules[:5]:
+    print(module.moduleCode, module.title)
+
+module = client.get_module("CS2030S")
+print(module.title)
+print(module.description)
+```
+
+If no academic year is supplied, the client uses the current calendar year and
+the following year. For example, a client created in 2026 uses `2026-2027`.
+
+## Client configuration
+
+```python
+from nusmods_api import NUSModsClient
+
+client = NUSModsClient(
+    academic_year="2026-2027",
+    timeout=20.0,
+    cache_directory=".nusmods_cache",
+    cache_expiration=86_400,
+)
+```
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `academic_year` | Current year and next year | Academic year in `YYYY-YYYY` format |
+| `timeout` | `10.0` | HTTP timeout in seconds |
+| `cache_directory` | `.nusmods_cache` | Directory for cached JSON responses |
+| `cache_expiration` | `86400` | Cache lifetime in seconds; use `None` for no expiration |
+
+Set `cache_directory=None` to disable caching:
+
+```python
+client = NUSModsClient(cache_directory=None)
+```
+
+## API usage
+
+### Module list
+
+```python
+modules = client.get_module_list()
+
+for module in modules:
+    print(module.moduleCode, module.title, module.semesters)
+```
+
+### Detailed module information
+
+```python
+modules = client.get_module_information()
+module = client.get_module(" cs2030s ")
+
+print(module.moduleCode)  # CS2030S
+print(module.acadYear)
+print(module.semesterData)
+```
+
+Module codes are stripped and normalized to uppercase by `get_module`.
+
+### Venues
+
+```python
+venues = client.get_venues(semester=1)
+print(venues)
+
+venue_information = client.get_venue_information(semester=1)
+for venue, entries in venue_information.items():
+    print(venue, entries)
+```
+
+`semester` must be `1` or `2`.
+
+### Shared timetables
+
+Pass a NUSMods share URL to `get_shared_timetable`:
+
+```python
+share_url = (
+    "https://nusmods.com/timetable/sem-1/share?"
+    "CS1231S=TUT:25B,LEC:1&"
+    "CS2030S=REC:04,LAB:10B,LEC:1&"
+    "GES1034=LEC:1,TUT:E2&"
+    "IS1108=TUT:14,LEC:2&"
+    "MA1522=LEC:1"
+)
+
+timetable = client.get_shared_timetable(share_url)
+
+for lesson in timetable.weekly:
+    print(
+        lesson.moduleCode,
+        lesson.lessonType,
+        lesson.classNo,
+        lesson.day,
+        lesson.startTime,
+        lesson.endTime,
+        lesson.venue,
+    )
+
+for exam in timetable.exams:
+    print(exam.moduleCode, exam.examDate, exam.examDuration)
+```
+
+The client parses the module selections from the URL and retrieves the
+corresponding module data from the NUSMods API. Lesson type codes such as
+`LEC`, `TUT`, `LAB`, and `REC` are mapped to their full names.
+
+`Timetable` also provides convenience methods:
+
+```python
+monday = timetable.get_day_schedule("Monday")
+exam = timetable.get_exam_for_module("CS2030S")
+```
+
+## Data models
+
+The package exposes frozen dataclasses for common API response types:
+
+- `ModuleCondensed` — module code, title, and offered semesters
+- `Module` — detailed module information
+- `Lesson` — class schedule information
+- `LessonWithModule` — a lesson including its module code
+- `VenueLesson` and `VenueInformation` — venue timetable data
+- `WeekRange` — date-based lesson ranges
+- `Workload` — workload components
+- `PrerequisiteTree` — nested prerequisite expressions
+- `ExamTimetable` — exam information
+- `Timetable` — selected weekly lessons and exams
+
+Some model fields retain the NUSMods API naming convention, such as
+`moduleCode`, `classNo`, `startTime`, `lessonType`, and `examDate`.
+
+## Error handling
+
+The client raises package-specific exceptions:
+
+```python
+from nusmods_api import (
+    NUSModsHTTPError,
+    NUSModsInvalidResponseError,
+    NUSModsNotFoundError,
+    NUSModsRequestError,
+)
+
+try:
+    module = client.get_module("CS2030S")
+except NUSModsNotFoundError:
+    print("The module or academic year was not found")
+except NUSModsHTTPError as error:
+    print(error.status_code, error.url)
+except NUSModsInvalidResponseError:
+    print("The API returned invalid JSON")
+except NUSModsRequestError:
+    print("The API could not be reached")
+```
+
+Invalid client arguments, malformed share URLs, invalid semesters, and
+unmatched lesson selections raise `ValueError`.
+
+## Testing
+
+Run the default unit test suite:
+
+```powershell
+uv run pytest
+```
+
+The live integration test makes real requests to the NUSMods API:
+
+```powershell
+uv run pytest tests/test_live_client.py -m live -q
+```
+
+The live test requires internet access and may need its expected timetable
+dates updated when NUSMods publishes a new academic-year dataset.
+
+## License
+
+No license has been specified yet.

nusmods_api-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "nusmods-api"
+version = "0.1.0"
+description = "A Python wrapper for the NUSMods API"
+readme = "README.md"
+requires-python = ">=3.15.0"
+dependencies = ["requests>=2.34.2"]
+
+[[project.authors]]
+name = "kommade"
+email = "khoojarrell@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+markers = ["live: tests that make requests to the live NUSMods API"]

nusmods_api-0.1.0/pyproject.toml.orig

@@ -0,0 +1,26 @@
+[project]
+name = "nusmods-api"
+version = "0.1.0"
+description = "A Python wrapper for the NUSMods API"
+readme = "README.md"
+authors = [
+    { name = "kommade", email = "khoojarrell@gmail.com" }
+]
+requires-python = ">=3.15.0"
+dependencies = [
+    "requests>=2.34.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "live: tests that make requests to the live NUSMods API",
+]

nusmods_api-0.1.0/src/nusmods_api/__init__.py

@@ -0,0 +1,35 @@
+from .client import NUSModsClient
+from .exceptions import (
+    NUSModsError,
+    NUSModsRequestError,
+    NUSModsHTTPError,
+    NUSModsInvalidResponseError,
+    NUSModsNotFoundError,
+)
+from .models import (
+    WeekRange,
+    Lesson,
+    Workload,
+    PrerequisiteTree,
+    ModuleCondensed,
+    Module,
+    VenueLesson,
+    VenueInformation,
+)
+
+__all__ = [
+    "NUSModsClient",
+    "NUSModsError",
+    "NUSModsRequestError",
+    "NUSModsHTTPError",
+    "NUSModsInvalidResponseError",
+    "NUSModsNotFoundError",
+    "WeekRange",
+    "Lesson",
+    "Workload",
+    "PrerequisiteTree",
+    "ModuleCondensed",
+    "Module",
+    "VenueLesson",
+    "VenueInformation",
+]

nusmods_api-0.1.0/src/nusmods_api/cache.py

@@ -0,0 +1,65 @@
+"""Local cache for NUSMods API data."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+class Cache:
+    def __init__(
+        self,
+        directory: str | Path = ".nusmods_cache",
+        expiration: int | None = 86_400,
+    ) -> None:
+        self.directory = Path(directory)
+        self.expiration = expiration
+        self.directory.mkdir(parents=True, exist_ok=True)
+        
+    def _path_for(self, key: str) -> Path:
+        filename = hashlib.sha256(
+            key.encode()
+        ).hexdigest() + ".json"
+        
+        return self.directory / filename
+    
+    def get(self, key: str) -> Any | None:
+        path = self._path_for(key)
+        if not path.exists():
+            return None
+        
+        if self.expiration is not None and time.time() - path.stat().st_mtime > self.expiration:
+            path.unlink()
+            return None
+        
+        try:
+            return json.loads(path.read_text())
+        except (json.JSONDecodeError, OSError):
+            return None
+        
+    def set(self, key: str, value: Any) -> None:
+        path = self._path_for(key)
+        temp_path = path.with_suffix(".tmp")
+        
+        temp_path.write_text(
+            json.dumps(value, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        temp_path.replace(path)
+        
+    def delete(self, key: str) -> None:
+        path = self._path_for(key)
+    
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+        
+    def clear(self) -> None:
+        for file in self.directory.glob("*.json"):
+            try:
+                file.unlink()
+            except FileNotFoundError:
+                pass

nusmods_api-0.1.0/src/nusmods_api/client.py

@@ -0,0 +1,394 @@
+"""Main client for the NUSMods API."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import requests
+from datetime import datetime, date
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+from .cache import Cache
+
+from .exceptions import (
+    NUSModsRequestError,
+    NUSModsHTTPError,
+    NUSModsInvalidResponseError,
+    NUSModsNotFoundError,
+)
+
+from .models import (
+    WeekRange,
+    Lesson,
+    LessonWithModule,
+    Workload,
+    PrerequisiteTree,
+    SemesterData,
+    ModuleCondensed,
+    Module,
+    VenueLesson,
+    VenueInformation,
+    ExamTimetable,
+    Timetable,
+)
+
+class NUSModsClient:
+    BASE_URL = "https://api.nusmods.com/v2"
+    
+    LESSON_TYPE_NAMES = {
+        "LEC": "Lecture",
+        "TUT": "Tutorial",
+        "LAB": "Laboratory",
+        "REC": "Recitation",
+        "SEM": "Seminar",
+        "SEC": "Sectional Teaching",
+        "PRA": "Practical",
+    }
+
+    DAY_ORDER = {
+        "Monday": 0,
+        "Tuesday": 1,
+        "Wednesday": 2,
+        "Thursday": 3,
+        "Friday": 4,
+        "Saturday": 5,
+        "Sunday": 6,
+    }
+
+    
+    def __init__(
+        self,
+        academic_year: str | None = None,
+        timeout: float = 10.0,
+        cache_directory: str | Path | None = ".nusmods_cache",
+        cache_expiration: int | None = 86_400,
+    ) -> None:
+        if academic_year is not None:
+            if re.fullmatch(r"\d{4}-\d{4}", academic_year) is None:
+                raise ValueError("Invalid academic year format. Expected 'YYYY-YYYY'.")
+            self.academic_year = academic_year
+        else:
+            this_year = datetime.now().year
+            next_year = this_year + 1
+            self.academic_year = f"{this_year}-{next_year}"
+        self.timeout = timeout
+        
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Accept": "application/json",
+            "User-Agent": f"nusmods-api-python/0.1.0)",
+        })
+        
+        self.cache = Cache(
+            directory=cache_directory,
+            expiration=cache_expiration,
+        ) if cache_directory is not None else None
+        
+    def _build_url(self, endpoint: str) -> str:
+        if self.academic_year is None:
+            raise ValueError("Academic year is not set")
+        return f"{self.BASE_URL}/{self.academic_year}/{endpoint}"
+    
+    def _get(self, path: str) -> Any:
+        url = self._build_url(path)
+        
+        if self.cache is not None:
+            cached_response = self.cache.get(url)
+            if cached_response is not None:
+                return cached_response
+        
+        try:
+            response = self.session.get(url, timeout=self.timeout)
+        except requests.RequestException as e:
+            raise NUSModsRequestError(
+                f"Could not connect to NUSMods API: {url}"
+            ) from e
+            
+        if response.status_code == 404:
+            raise NUSModsNotFoundError(url)
+        
+        if not response.ok:
+            raise NUSModsHTTPError(
+                status_code=response.status_code,
+                url=url,
+                message=f"NUSMods API returned HTTP {response.status_code}",
+            )
+        try:
+            data = response.json()
+        except ValueError as e:
+            raise NUSModsInvalidResponseError(
+                url=url,
+                message="Invalid JSON response",
+            ) from e
+        
+        if self.cache is not None:
+            self.cache.set(url, data)
+            
+        return data
+            
+    def get_module_list(self) -> list[ModuleCondensed]:
+        """Get a list of all modules for the academic year."""
+        data = self._get("modules.json")
+        return [ModuleCondensed(**module) for module in data]
+    
+    def get_module_information(self) -> list[Module]:
+        """Get detailed information for all modules for the academic year."""
+        data = self._get("moduleInformation.json")
+        return [self._parse_module(module) for module in data]
+    
+    def get_module(self, module_code: str) -> Module:
+        """Get detailed information for a specific module."""
+        module_code = module_code.strip().upper()
+        data = self._get(f"modules/{module_code}.json")
+        return self._parse_module(data)
+
+    def _parse_module(self, data: dict[str, Any]) -> Module:
+        module_data = {
+            "moduleCode": data["moduleCode"],
+            "title": data["title"],
+            "semesters": data.get("semesters", []),
+            "acadYear": data["acadYear"],
+            "preclusion": data.get("preclusion"),
+            "description": data.get("description"),
+            "department": data.get("department"),
+            "faculty": data.get("faculty"),
+            "moduleCredit": data.get("moduleCredit"),
+            "attributes": data.get("attributes"),
+            "prerequisite": data.get("prerequisite"),
+            "corequisite": data.get("corequisite"),
+            "workload": (
+                Workload.from_list(data["workload"])
+                if isinstance(data.get("workload"), list)
+                else data.get("workload")
+            ),
+            "fulfill_requirements": data.get("fulfillRequirements"),
+            "prerequisite_tree": self._parse_prerequisite_tree(
+                data.get("prereqTree")
+            ),
+            "semesterData": [
+                SemesterData(
+                    semester=semester["semester"],
+                    examDate=semester.get("examDate"),
+                    examDuration=semester.get("examDuration"),
+                    timetable=[
+                        Lesson(**{
+                            key: lesson[key]
+                            for key in (
+                                "classNo",
+                                "startTime",
+                                "endTime",
+                                "weeks",
+                                "venue",
+                                "day",
+                                "lessonType",
+                                "size",
+                            )
+                        })
+                        for lesson in semester.get("timetable") or []
+                    ],
+                )
+                for semester in data.get("semesterData") or []
+            ],
+        }
+        return Module(**module_data)
+
+    def _parse_prerequisite_tree(
+        self,
+        data: dict[str, Any] | None,
+    ) -> PrerequisiteTree | None:
+        if data is None:
+            return None
+
+        def parse_children(
+            values: list[str | dict[str, Any]],
+        ) -> list[str | PrerequisiteTree]:
+            return list(filter(None, (
+                self._parse_prerequisite_tree(value)
+                if isinstance(value, dict)
+                else value
+                for value in values
+            )))
+
+        return PrerequisiteTree(
+            and_=parse_children(data["and"]) if "and" in data else None,
+            or_=parse_children(data["or"]) if "or" in data else None,
+        )
+    
+    def get_venues(self, semester: int) -> list[str]:
+        """Get a list of all venues for the academic year."""
+        if semester not in (1, 2):
+            raise ValueError("Semester must be 1 or 2")
+        data = self._get(f"semesters/{semester}/venues.json")
+        return data
+    
+    def get_venue_information(self, semester: int) -> dict[str, list[VenueInformation]]:
+        """Get timetable information grouped by venue"""
+        if semester not in (1, 2):
+            raise ValueError("Semester must be 1 or 2")
+        data = self._get(f"semesters/{semester}/venues.json")
+        venue_info = {}
+        for venue in data:
+            venue_name = venue["venue"]
+            lessons = [VenueInformation(**lesson) for lesson in venue["classes"]]
+            venue_info[venue_name] = lessons
+        return venue_info
+        
+    def get_shared_timetable(
+        self,
+        share_url: str,
+    ) -> Timetable:
+        parsed_url = urlparse(share_url)
+
+        if parsed_url.netloc not in {
+            "nusmods.com",
+            "www.nusmods.com",
+        }:
+            raise ValueError("URL must belong to nusmods.com")
+
+        semester_match = re.search(
+            r"/timetable/sem-(\d+)/share",
+            parsed_url.path,
+        )
+
+        if semester_match is None:
+            raise ValueError(
+                "URL must have the form /timetable/sem-{n}/share"
+            )
+
+        semester = int(semester_match.group(1))
+        query = parse_qs(parsed_url.query)
+
+        if not query:
+            raise ValueError("Share URL contains no module selections")
+
+        weekly_lessons: list[LessonWithModule] = []
+        exams: list[ExamTimetable] = []
+
+        for module_code, selection_groups in query.items():
+            module = self.get_module(module_code)
+
+            semester_data = next(
+                (
+                    data
+                    for data in module.semesterData or []
+                    if data.semester == semester
+                ),
+                None,
+            )
+
+            if semester_data is None:
+                raise ValueError(
+                    f"{module_code} has no data for semester {semester}"
+                )
+
+            selected_lessons = self._select_lessons(
+                module_code=module_code,
+                lessons=semester_data.timetable or [],
+                selection_groups=selection_groups,
+            )
+
+            weekly_lessons.extend(selected_lessons)
+
+            if semester_data.examDate is not None:
+                exams.append(
+                    ExamTimetable(
+                        moduleCode=module_code,
+                        examDate=semester_data.examDate,
+                        examDuration=semester_data.examDuration,
+                    )
+                )
+
+        weekly_lessons.sort(key=self._lesson_sort_key)
+        exams.sort(key=self._exam_sort_key)
+
+        return Timetable(
+            semester=semester,
+            weekly=weekly_lessons,
+            exams=exams,
+        )
+    
+    def _select_lessons(
+        self,
+        module_code: str,
+        lessons: list[Lesson],
+        selection_groups: list[str],
+    ) -> list[LessonWithModule]:
+        requested: set[tuple[str, str]] = set()
+
+        for selection_group in selection_groups:
+            for selection in selection_group.split(","):
+                try:
+                    lesson_type_code, class_no = selection.split(":", 1)
+                except ValueError as error:
+                    raise ValueError(
+                        f"Invalid lesson selection for {module_code}: "
+                        f"{selection!r}"
+                    ) from error
+
+                lesson_type = self.LESSON_TYPE_NAMES.get(
+                    lesson_type_code.upper(),
+                    lesson_type_code,
+                )
+
+                requested.add((lesson_type, class_no))
+
+        selected = [
+            LessonWithModule(
+                moduleCode=module_code,
+                classNo=lesson.classNo,
+                startTime=lesson.startTime,
+                endTime=lesson.endTime,
+                weeks=lesson.weeks,
+                venue=lesson.venue,
+                day=lesson.day,
+                lessonType=lesson.lessonType,
+                size=lesson.size,
+            )
+            for lesson in lessons
+            if (lesson.lessonType, lesson.classNo) in requested
+        ]
+
+        found = {
+            (lesson.lessonType, lesson.classNo)
+            for lesson in selected
+        }
+
+        missing = requested - found
+
+        if missing:
+            raise ValueError(
+                f"Could not find selected lessons for {module_code}: "
+                f"{sorted(missing)}"
+            )
+
+        return selected
+    
+    def _lesson_sort_key(
+        self,
+        lesson: LessonWithModule,
+    ) -> tuple[int, int, str, str]:
+        try:
+            start_minutes = (
+                int(lesson.startTime[:2]) * 60
+                + int(lesson.startTime[2:])
+            )
+        except ValueError:
+            start_minutes = 0
+
+        return (
+            self.DAY_ORDER.get(lesson.day, len(self.DAY_ORDER)),
+            start_minutes,
+            lesson.moduleCode,
+            lesson.lessonType,
+        )
+        
+    def _exam_sort_key(
+        self,
+        exam: ExamTimetable,
+    ) -> tuple[date, str]:
+        return (
+            exam.examDate or date.max,
+            exam.moduleCode,
+        )

nusmods_api-0.1.0/src/nusmods_api/exceptions.py

@@ -0,0 +1,40 @@
+"""Typed exceptions for the NUSMods API."""
+
+
+class NUSModsError(Exception):
+    """Base exception for all errors raised by the NUSMods wrapper."""
+
+
+class NUSModsRequestError(NUSModsError):
+    """Raised when a request cannot be completed."""
+
+
+class NUSModsHTTPError(NUSModsError):
+    """Raised when the API returns an unsuccessful HTTP status code."""
+
+    def __init__(
+        self,
+        status_code: int,
+        url: str,
+        message: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.url = url
+        self.message = message or f"NUSMods API returned HTTP {status_code}"
+        super().__init__(f"{self.message}: {url}")
+
+
+class NUSModsNotFoundError(NUSModsHTTPError):
+    """Raised when the requested academic-year resource does not exist."""
+
+    def __init__(self, url: str) -> None:
+        super().__init__(404, url, "NUSMods resource not found")
+
+
+class NUSModsInvalidResponseError(NUSModsError):
+    """Raised when the API response cannot be decoded as JSON."""
+
+    def __init__(self, url: str, message: str = "Invalid JSON response") -> None:
+        self.url = url
+        self.message = message
+        super().__init__(f"{message}: {url}")

nusmods_api-0.1.0/src/nusmods_api/models.py

@@ -0,0 +1,180 @@
+"""Typed models for responses from the NUSMods v2 API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Any, TypeAlias
+
+
+@dataclass(frozen=True)
+class WeekRange:
+    """A date-based lesson range used for special classes."""
+
+    start: date
+    end: date
+    week_interval: int | None = None
+    weeks: list[int] | None = None
+
+
+LessonWeeks: TypeAlias = list[int] | WeekRange
+
+
+@dataclass(frozen=True)
+class Lesson:
+    classNo: str
+    startTime: str
+    endTime: str
+    weeks: LessonWeeks
+    venue: str
+    day: str
+    lessonType: str
+    size: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.weeks, (list, WeekRange)):
+            object.__setattr__(self, "weeks", parse_weeks(self.weeks))
+
+@dataclass(frozen=True)
+class LessonWithModule(Lesson):
+    moduleCode: str
+
+@dataclass(frozen=True)
+class Workload:
+    """Workload for a module.
+
+    The workload is represented as a list of strings, where each string
+    represents a workload component in the format ``<hours>:<component>``.
+    For example, ``"2:Lecture"`` means 2 hours of lecture per week.
+    """
+
+    lecture: int | None = None
+    tutorial: int | None = None
+    lab: int | None = None
+    project: int | None = None
+    preparation: int | None = None
+    string: str | None = None
+    
+    @staticmethod
+    def from_string(workload_str: str) -> Workload:
+        return Workload(string=workload_str)
+    
+    @staticmethod
+    def from_list(workload_list: list[str]) -> Workload:
+        if len(workload_list) != 5:
+            raise ValueError("Workload list must have exactly 5 elements.")
+        order = ["lecture", "tutorial", "lab", "project", "preparation"]
+        d = {}
+        for i in range(5):
+            d[order[i]] = workload_list[i]
+        return Workload(**d)
+
+
+@dataclass(frozen=True)
+class PrerequisiteTree:
+    """Recursive prerequisite expression.
+
+    A node normally contains either ``and`` or ``or``. Leaf values are
+    module codes represented as strings.
+    """
+
+    and_: list[str | PrerequisiteTree] | None = None
+    or_: list[str | PrerequisiteTree] | None = None
+
+
+
+@dataclass(frozen=True)
+class SemesterData:
+    """Semester data for a module."""
+
+    semester: int
+    examDate: date | None = None
+    examDuration: int | None = None
+    timetable: list[Lesson] | None = None
+    
+    def __post_init__(self) -> None:
+        if self.examDate is not None and not isinstance(self.examDate, date):
+            object.__setattr__(self, "examDate", parse_date(self.examDate))
+
+@dataclass(frozen=True)
+class ModuleCondensed:
+    moduleCode: str
+    title: str
+    semesters: list[int]
+
+
+@dataclass(frozen=True)
+class Module(ModuleCondensed):
+    acadYear: str
+    preclusion: str | None = None
+    description: str | None = None
+    department: str | None = None
+    faculty: str | None = None
+    workload: Workload | None = None
+    moduleCredit: int | None = None
+    attributes: dict[str, Any] | None = None
+    semesterData: list[SemesterData] | None = None
+    prerequisite: str | None = None
+    fulfill_requirements: list[str] | None = None
+    corequisite: str | None = None
+    prerequisite_tree: PrerequisiteTree | None = None
+
+
+@dataclass(frozen=True)
+class VenueLesson(Lesson):
+    moduleCode: str = ""
+
+
+@dataclass(frozen=True)
+class VenueInformation:
+    """Information about a venue and its lessons."""
+
+    day: str
+    classes: list[VenueLesson]
+    availability: dict[str, str] | None = None
+
+@dataclass(frozen=True)
+class ExamTimetable:
+    """Exam timetable for a module."""
+
+    moduleCode: str
+    examDate: date | None = None
+    examDuration: int | None = None
+
+@dataclass(frozen=True)
+class Timetable:
+    """Timetable for a semester."""
+    semester: int
+    weekly: list[LessonWithModule]
+    exams: list[ExamTimetable]
+    
+    def get_day_schedule(self, day: str) -> list[Lesson]:
+        """Get the lessons for a specific day of the week."""
+        if day not in {"Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"}:
+            raise ValueError("Day must be one of Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday")
+        return [lesson for lesson in self.weekly if lesson.day == day]
+    
+    def get_exam_for_module(self, module_code: str) -> ExamTimetable | None:
+        """Get the exam timetable for a specific module."""
+        for exam in self.exams:
+            if exam.moduleCode == module_code:
+                return exam
+        return None
+
+def parse_date(value: str) -> date:
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).date()
+
+
+def parse_weeks(value: list[int] | dict[str, Any]) -> LessonWeeks:
+    if isinstance(value, list):
+        return value
+
+    return WeekRange(
+        start=parse_date(value["start"]),
+        end=parse_date(value["end"]),
+        weeks=value.get("weeks"),
+        week_interval=value.get("weekInterval"),
+    )