2026-10-28 08:09:18 +01:00
45 changed files with 784 additions and 1 deletions
@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
@@ -0,0 +1,3 @@
+[submodule "framework"]
+	path = framework
+	url = ssh://git@git.tirsystem.com:10022/TirSystem/SQA-QC-Framework.git
@@ -1,2 +1,120 @@
-# 048-scrapping-python-org
+# 🚀 048 – Scraping python.org with Selenium

+Day 48 of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp*: scrape
+the five upcoming events from [python.org](https://www.python.org/) with
+Selenium and print them as a dictionary. This is a modernised version of the
+original solution.
+
+## 📚 Table of Contents
+
+- [Overview](#-overview)
+- [Requirements](#-requirements)
+- [Setup](#-setup)
+- [Run](#-run)
+- [Tests](#-tests)
+- [License](#-license)
+- [Links](#-links)
+- [Appendix: Project documents](#-appendix-project-documents)
+
+## 🧭 Overview
+
+The program opens python.org in headless Chrome, reads the *Upcoming Events*
+widget and prints:
+
+```python
+{0: {'time': '2026-10-29', 'name': 'PyConFR 2026'}, 1: {...}, ..., 4: {...}}
+```
+
+| Path | Purpose |
+| --- | --- |
+| `src/scraping_python_org/domain` | The `Event` value object |
+| `src/scraping_python_org/application` | The use case and the `EventSource` port |
+| `src/scraping_python_org/infrastructure` | Selenium and Chrome adapters |
+| `src/scraping_python_org/presentation` | Command line entry point and screenshot capture |
+| `tests/` | Unit tests and a headless browser test against a saved page |
+| `docs/wiki/` | Wiki in English, Danish and Bahasa Malaysia |
+
+### The lecture steps
+
+**1. Open the page.** python.org loads in the browser.
+
+![Step 1: python.org home page](docs/screenshots/01-python-org-home.png)
+
+**2. Locate the widget.** Inspect the page: the events sit in the
+`.event-widget` element, each in an `li` with a `time` and an `a` tag.
+
+![Step 2: the Upcoming Events widget](docs/screenshots/02-event-widget.png)
+
+**3. Select the five list items** with the CSS selector `.event-widget li`
+(outlined in red).
+
+![Step 3: the five list items selected](docs/screenshots/03-event-list-highlighted.png)
+
+**4. Build the dictionary** with a `for` loop and print it.
+
+![Step 4: the printed dictionary](docs/screenshots/04-output-dictionary.png)
+
+What each step teaches is in the [wiki](docs/wiki/Home.md).
+
+## 📋 Requirements
+
+- Python 3.11 or newer (developed on 3.13).
+- Google Chrome. Selenium Manager downloads a matching driver by itself.
+
+## 🛠️ Setup
+
+```bash
+python -m venv .venv
+source .venv/Scripts/activate   # Windows Git Bash; on Linux/macOS: .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## ▶️ Run
+
+```bash
+python -m scraping_python_org
+```
+
+Regenerate the screenshots:
+
+```bash
+python -m scraping_python_org.presentation.screenshots
+```
+
+## 🧪 Tests
+
+```bash
+pytest
+```
+
+The `browser` test starts headless Chrome on a saved HTML page; skip it with
+`pytest -m "not browser"`.
+
+## 📄 License
+
+See [LICENSE](./LICENSE).
+
+## 🔗 Links
+
+- [Repository][repository]
+- [Documentation][documentation]
+- [Issue tracker][issues]
+
+## 📎 Appendix: Project documents
+
+| Document | What it tells you |
+| --- | --- |
+| [AGENTS.md][agents] | The rules AI agents follow in this repository |
+| [Artifact registry][registry] | The PO language and where artifacts live |
+| [Framework README][framework-readme] | The framework this project uses |
+| [Framework changelog][framework-changelog] | What changed in each framework release |
+
+---
+
+[repository]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-scrapping-python-org
+[documentation]: ./docs/wiki/Home.md
+[issues]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/048-scrapping-python-org/issues
+[agents]: ./AGENTS.md
+[registry]: ./docs/artifact-registry.md
+[framework-readme]: ./framework/README.md
+[framework-changelog]: ./framework/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Session 001
+
+## Prompt 1
+
+> Day 48 python org. Autonomous mode. Create a Python project (Udemy 100 Days of Code assignment): scrape the five upcoming events from python.org with Selenium into a dictionary `{index: {"time", "name"}}`. We do not make artifacts. Code in src, wiki in docs/wiki in English, Danish and Bahasa Malaysia, a screenshot per lecture step in README and wiki, wiki explains what we gained. Use my solution from github.com/Tirsvad/udemy.python.100-days-of-code (day-48-scrapping-python-org) and modernise it.
+
+**Outcome:** Plan proposed; PO language set to da. Scraper built under `src/` with tests, README and three-language wiki written.
+
+## Prompt 2
+
+> do not make artifacts.
+
+**Outcome:** Treated as waiver of plan documents. Work continued; nothing pushed.
@@ -0,0 +1,56 @@
+# Artifact Registry
+
+This project's artifact state. Types, short names and `CrossReference
+Candidates` come from the framework catalog
+(`framework/registry/artifact-catalog.md`); this file only records where
+each document lives in *this* project and the next version to use.
+
+Delete rows for types you don't use. Add a row the first time you create a
+document of a type. `Primary File` may contain a glob (e.g.
+`docs/use-cases/uc-*/uc.md`); `framework/scripts/find-crossreferences.sh` reads it.
+
+| Short Name | Artifact Type | Primary File | Next Available Version |
+| --- | --- | --- | --- |
+| BC | Business Case | docs/business-case.md | 001 |
+| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 001 |
+
+## Languages
+
+Set the PO language when the project starts; `project-planning` asks for it
+if it is missing. An artifact of a type marked "Written in the PO language"
+exists once, in that language, under its normal name (`business-case.md`); the
+`artifact` skill ("One file per artifact") has the rule.
+
+| Setting | Value |
+| --- | --- |
+| PO language | da |
+| PO domain | it |
+| High-level register | IT Executive English |
+| Technical register | IT Professional English |
+| Wiki languages | en and the PO language, at least (`framework/process/wiki.md`) |
+
+Every artifact of a type marked "Yes" below states its language and domain in
+its `Language` and `Domain` Metadata rows; `new-artifact.sh` fills them from
+`PO language` and `PO domain`. `Language` is a BCP 47 code (`da`, `en`).
+`Domain` is a value from this list; add a row to introduce a domain, so a
+reviewer can see at once which professional vocabulary a document uses.
+
+| Domain | Meaning |
+| --- | --- |
+| it | Software and IT |
+| medical | Healthcare and medical devices |
+| construction | Construction and civil engineering |
+
+| Artifact types | Register | Written in the PO language |
+| --- | --- | --- |
+| BC, KPI, PP, MIL | IT Executive English | Yes |
+| SA, BMC, BPMN, UCD, US, UC, SSD, DM, RA, GOV, DICT | IT Professional English | Yes |
+| OC, SD, DCD, ERD, TP, AD, ADR, TM, RC, QC, source code | IT Professional English | No |
+
+## Notes
+
+- "Next Available Version" is the zero-padded (3-digit) version to use the
+  *next* time a new document of that type is created. Increment it only when
+  a brand-new document is created, not when an existing document's
+  `## Version History` gets a row.
+- `ADR` uses 4 digits (`0001`); `RC` is sequential across all artifact types.
@@ -0,0 +1,21 @@
+[English](Home) · **Dansk** · [Bahasa Malaysia](Home-ms)
+
+# Dag 48 – Scraping af python.org med Selenium
+
+I denne lektion bruger vi Selenium til at læse de fem kommende begivenheder på
+[python.org](https://www.python.org/) og samle dem i en dictionary:
+
+```python
+{0: {"time": "2026-10-29", "name": "PyConFR 2026"}, 1: {...}, ...}
+```
+
+## Sider
+
+- [Lektionens trin](Lecture-Steps-da): de fire trin, hver med et skærmbillede og hvad du får ud af det.
+- [Modernisering](Modernisation-da): hvad der er ændret i forhold til den oprindelige løsning, og hvorfor.
+
+## Hvad du får ud af denne lektion
+
+- Du læser en websides HTML-struktur med browserens inspektionsværktøj.
+- Du vælger locators (`By.CSS_SELECTOR`, `By.TAG_NAME`), der er korte og stabile.
+- Du omsætter scrapede elementer til ren, struktureret Python-data.
@@ -0,0 +1,22 @@
+[English](Home) · [Dansk](Home-da) · **Bahasa Malaysia**
+
+# Hari 48 – Mengikis python.org dengan Selenium
+
+Dalam pelajaran ini kita menggunakan Selenium untuk membaca lima acara akan
+datang di [python.org](https://www.python.org/) dan menyusunnya dalam kamus
+(dictionary):
+
+```python
+{0: {"time": "2026-10-29", "name": "PyConFR 2026"}, 1: {...}, ...}
+```
+
+## Halaman
+
+- [Langkah pelajaran](Lecture-Steps-ms): empat langkah, setiap satu dengan tangkapan skrin dan apa yang anda peroleh.
+- [Pemodenan](Modernisation-ms): apa yang berubah daripada penyelesaian asal dan sebabnya.
+
+## Apa yang anda peroleh daripada pelajaran ini
+
+- Anda membaca struktur HTML sesebuah laman web dengan alat pemeriksa pelayar.
+- Anda memilih locator (`By.CSS_SELECTOR`, `By.TAG_NAME`) yang ringkas dan stabil.
+- Anda menukar elemen yang dikikis kepada data Python yang bersih dan tersusun.
@@ -0,0 +1,21 @@
+**English** · [Dansk](Home-da) · [Bahasa Malaysia](Home-ms)
+
+# Day 48 – Scraping python.org with Selenium
+
+In this lecture we use Selenium to read the five upcoming events from
+[python.org](https://www.python.org/) and organise them in a dictionary:
+
+```python
+{0: {"time": "2026-10-29", "name": "PyConFR 2026"}, 1: {...}, ...}
+```
+
+## Pages
+
+- [Lecture steps](Lecture-Steps): the four steps, each with a screenshot and what you gain from it.
+- [Modernisation](Modernisation): what changed from the original solution and why.
+
+## What you gain in this lecture
+
+- You read a web page's HTML structure with the browser's inspector.
+- You choose locators (`By.CSS_SELECTOR`, `By.TAG_NAME`) that are short and stable.
+- You turn scraped elements into clean, structured Python data.
@@ -0,0 +1,43 @@
+[English](Lecture-Steps) · **Dansk** · [Bahasa Malaysia](Lecture-Steps-ms)
+
+# Lektionens trin
+
+## Trin 1 – Åbn siden
+
+![Forsiden på python.org](images/01-python-org-home.png)
+
+`driver.get("https://www.python.org/")` indlæser siden i Chrome.
+
+**Hvad du får ud af det:** driveren er din fjernbetjening til en rigtig browser.
+Den skal altid lukkes igen, så den moderne kode bruger `try/finally`.
+
+## Trin 2 – Find widgetten med inspektionsværktøjet
+
+![Widgetten Upcoming Events](images/02-event-widget.png)
+
+Højreklik på widgetten og vælg *Inspect*. Begivenhederne ligger i et element med
+klassen `event-widget`; hver begivenhed er en `li` med et `time`- og et `a`-tag.
+
+**Hvad du får ud af det:** du lærer at læse HTML-træet og finde den beholder,
+der rummer præcis de data, du vil have.
+
+## Trin 3 – Vælg de fem listepunkter med en CSS-selector
+
+![De fem listepunkter markeret med rødt](images/03-event-list-highlighted.png)
+
+`driver.find_elements(By.CSS_SELECTOR, ".event-widget li")` returnerer de fem
+punkter. En klassebaseret selector er kortere og mere stabil end den lange
+XPath, man kopierer fra inspektøren, og den rammer ikke urelaterede links.
+
+**Hvad du får ud af det:** du kender Seleniums locator-strategier og ved,
+hvornår CSS-selectors slår XPath.
+
+## Trin 4 – Byg dictionary'en
+
+![Den udskrevne dictionary](images/04-output-dictionary.png)
+
+For hvert punkt læser vi `time` og `a` og gemmer dem under punktets indeks, med
+`enumerate` i stedet for en manuel tæller.
+
+**Hvad du får ud af det:** du omsætter sideelementer til struktureret data: en
+dictionary af dictionaries, klar til brug i resten af et program.
@@ -0,0 +1,43 @@
+[English](Lecture-Steps) · [Dansk](Lecture-Steps-da) · **Bahasa Malaysia**
+
+# Langkah pelajaran
+
+## Langkah 1 – Buka laman
+
+![Laman utama python.org](images/01-python-org-home.png)
+
+`driver.get("https://www.python.org/")` memuatkan laman dalam Chrome.
+
+**Apa yang anda peroleh:** driver ialah alat kawalan jauh untuk pelayar sebenar.
+Ia mesti ditutup semula, jadi kod moden menggunakan `try/finally`.
+
+## Langkah 2 – Cari widget dengan alat pemeriksa
+
+![Widget Upcoming Events](images/02-event-widget.png)
+
+Klik kanan pada widget dan pilih *Inspect*. Acara berada dalam elemen berkelas
+`event-widget`; setiap acara ialah `li` yang mengandungi teg `time` dan `a`.
+
+**Apa yang anda peroleh:** anda belajar membaca pepohon HTML dan mencari
+bekas yang menyimpan data yang tepat seperti yang dikehendaki.
+
+## Langkah 3 – Pilih lima item senarai dengan pemilih CSS
+
+![Lima item senarai ditandakan merah](images/03-event-list-highlighted.png)
+
+`driver.find_elements(By.CSS_SELECTOR, ".event-widget li")` mengembalikan lima
+item. Pemilih berasaskan kelas lebih pendek dan lebih stabil daripada XPath
+panjang yang disalin dari pemeriksa, dan ia tidak memadankan pautan lain.
+
+**Apa yang anda peroleh:** anda mengenali strategi locator Selenium dan bila
+pemilih CSS lebih baik daripada XPath.
+
+## Langkah 4 – Bina kamus
+
+![Kamus yang dicetak](images/04-output-dictionary.png)
+
+Untuk setiap item kita baca `time` dan `a` lalu simpan di bawah indeks item itu,
+dengan `enumerate` dan bukannya pembilang manual.
+
+**Apa yang anda peroleh:** anda menukar elemen halaman kepada data tersusun:
+kamus dalam kamus, sedia digunakan dalam bahagian program yang lain.
@@ -0,0 +1,44 @@
+**English** · [Dansk](Lecture-Steps-da) · [Bahasa Malaysia](Lecture-Steps-ms)
+
+# Lecture steps
+
+## Step 1 – Open the page
+
+![python.org home page](images/01-python-org-home.png)
+
+`driver.get("https://www.python.org/")` loads the page in Chrome.
+
+**What you gain:** the driver is your remote control for a real browser. It
+must always be closed again, so the modern code wraps it in `try/finally`.
+
+## Step 2 – Locate the widget with the inspector
+
+![The Upcoming Events widget](images/02-event-widget.png)
+
+Right-click the widget and choose *Inspect*. The events live inside an element
+with the class `event-widget`; each event is an `li` holding a `time` and an
+`a` tag.
+
+**What you gain:** you learn to read the HTML tree and find the container that
+holds exactly the data you want.
+
+## Step 3 – Select the five list items with a CSS selector
+
+![The five list items outlined in red](images/03-event-list-highlighted.png)
+
+`driver.find_elements(By.CSS_SELECTOR, ".event-widget li")` returns the five
+items. A class-based selector is shorter and more stable than the long XPath
+copied from the inspector, and it does not match unrelated links.
+
+**What you gain:** you know the Selenium locator strategies and when CSS
+selectors beat XPath.
+
+## Step 4 – Build the dictionary
+
+![The printed dictionary](images/04-output-dictionary.png)
+
+For every item we read `time` and `a` and store them under the item's index,
+with `enumerate` instead of a manual counter.
+
+**What you gain:** you turn page elements into structured data: a dictionary
+of dictionaries, ready to use in the rest of a program.
@@ -0,0 +1,16 @@
+[English](Modernisation) · **Dansk** · [Bahasa Malaysia](Modernisation-ms)
+
+# Modernisering
+
+| Oprindelig løsning | Moderne løsning | Hvorfor |
+| --- | --- | --- |
+| Én `main.py` | Lag i `src/scraping_python_org` (domain, application, infrastructure, presentation) | Forretningsreglerne afhænger ikke af Selenium; use casen testes med en fake |
+| Lang absolut XPath | CSS-selector `.event-widget li` | Kort, læsbar, tåler ændringer i layoutet |
+| Manuel tæller `c` | `enumerate` | Mindre kode, ingen fejl med off-by-one |
+| `detach=True` efterfulgt af `driver.quit()` | Headless Chrome i en context manager, der altid lukker | Ingen efterladte browservinduer, kører uden skrivebord |
+| `selenium` uden version i `requirements.txt` | `pyproject.toml` med minimumsversioner | Reproducerbare installationer |
+| Ingen tests | Enhedstests og en headless browsertest på en gemt side | Ændringer er trygge |
+| Ingen typeannotationer | `mypy --strict`, `ruff` | Fejl findes før kørsel |
+
+**Hvad du får ud af det:** en scraper, du kan ændre med ro i sindet; samme idé
+som i lektionen, men bygget som et rigtigt projekt.
@@ -0,0 +1,16 @@
+[English](Modernisation) · [Dansk](Modernisation-da) · **Bahasa Malaysia**
+
+# Pemodenan
+
+| Penyelesaian asal | Penyelesaian moden | Sebab |
+| --- | --- | --- |
+| Satu `main.py` | Lapisan dalam `src/scraping_python_org` (domain, application, infrastructure, presentation) | Peraturan perniagaan tidak bergantung pada Selenium; use case diuji dengan palsu (fake) |
+| XPath mutlak yang panjang | Pemilih CSS `.event-widget li` | Pendek, mudah dibaca, tahan perubahan reka letak |
+| Pembilang manual `c` | `enumerate` | Kod lebih sedikit, tiada ralat off-by-one |
+| `detach=True` diikuti `driver.quit()` | Chrome headless dalam context manager yang sentiasa menutup | Tiada tetingkap pelayar tertinggal, berjalan tanpa desktop |
+| `selenium` tanpa versi dalam `requirements.txt` | `pyproject.toml` dengan versi minimum | Pemasangan yang boleh diulang |
+| Tiada ujian | Ujian unit dan ujian pelayar headless pada halaman tersimpan | Perubahan selamat |
+| Tiada petunjuk jenis | `mypy --strict`, `ruff` | Ralat ditemui sebelum dijalankan |
+
+**Apa yang anda peroleh:** pengikis yang boleh diubah dengan yakin; idea yang
+sama seperti dalam pelajaran, tetapi dibina seperti projek sebenar.
@@ -0,0 +1,16 @@
+**English** · [Dansk](Modernisation-da) · [Bahasa Malaysia](Modernisation-ms)
+
+# Modernisation
+
+| Original solution | Modern solution | Why |
+| --- | --- | --- |
+| One `main.py` | Layers in `src/scraping_python_org` (domain, application, infrastructure, presentation) | Business rules do not depend on Selenium; the use case is tested with a fake |
+| Long absolute XPath | CSS selector `.event-widget li` | Short, readable, survives layout changes |
+| Manual counter `c` | `enumerate` | Less code, no off-by-one risk |
+| `detach=True` followed by `driver.quit()` | Headless Chrome in a context manager that always quits | No stray browser windows, runs without a desktop |
+| Unpinned `selenium` in `requirements.txt` | `pyproject.toml` with minimum versions | Reproducible installs |
+| No tests | Unit tests plus a headless browser test on a saved page | Changes are safe |
+| No type hints | `mypy --strict`, `ruff` | Errors found before running |
+
+**What you gain:** a scraper you can change with confidence, the same idea
+as the lecture but built the way a real project is.
@@ -0,0 +1,17 @@
+**English** · [Dansk](Home-da) · [Bahasa Malaysia](Home-ms)
+
+- [Home](Home)
+- [Lecture steps](Lecture-Steps)
+- [Modernisation](Modernisation)
+
+**Dansk**
+
+- [Hjem](Home-da)
+- [Lektionens trin](Lecture-Steps-da)
+- [Modernisering](Modernisation-da)
+
+**Bahasa Malaysia**
+
+- [Utama](Home-ms)
+- [Langkah pelajaran](Lecture-Steps-ms)
+- [Pemodenan](Modernisation-ms)
@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scraping-python-org"
+version = "0.1.0"
+description = "Scrape the upcoming events from python.org with Selenium."
+requires-python = ">=3.12"
+dependencies = ["selenium>=4.25"]
+
+[dependency-groups]
+dev = ["pytest>=8.3", "ruff>=0.8", "mypy>=1.13"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scraping_python_org"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = ["browser: needs a headless Chrome installed"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "D", "ANN", "SIM", "T20"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+"src/scraping_python_org/presentation/cli.py" = ["T201"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
@@ -0,0 +1 @@
+"""Scrape the upcoming events from python.org."""
@@ -0,0 +1,5 @@
+"""Entry point for ``python -m scraping_python_org``."""
+
+from scraping_python_org.presentation.cli import main
+
+raise SystemExit(main())
@@ -0,0 +1 @@
+"""Use cases and the ports they need."""
@@ -0,0 +1,13 @@
+"""Port for anything that can supply upcoming events."""
+
+from typing import Protocol
+
+from scraping_python_org.domain.event import Event
+
+
+class EventSource(Protocol):
+    """Supplies upcoming events in page order."""
+
+    def fetch_events(self) -> list[Event]:
+        """Return the upcoming events."""
+        ...
@@ -0,0 +1,13 @@
+"""Use case: list the upcoming events as a numbered dictionary."""
+
+from scraping_python_org.application.event_source import EventSource
+
+DEFAULT_LIMIT = 5
+
+
+def get_upcoming_events(
+    source: EventSource, limit: int = DEFAULT_LIMIT
+) -> dict[int, dict[str, str]]:
+    """Return up to ``limit`` events as ``{index: {"time": ..., "name": ...}}``."""
+    events = source.fetch_events()[:limit]
+    return {index: event.to_dict() for index, event in enumerate(events)}
@@ -0,0 +1 @@
+"""Business rules; no input or output."""
@@ -0,0 +1,15 @@
+"""The Event value object."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """An upcoming event with its date text and name."""
+
+    time: str
+    name: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Return the event as a plain dictionary."""
+        return {"time": self.time, "name": self.name}
@@ -0,0 +1 @@
+"""Drivers and adapters for outside technology."""
@@ -0,0 +1,22 @@
+"""Chrome WebDriver lifecycle."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from selenium import webdriver
+
+WINDOW_SIZE = "1280,1000"
+
+
+@contextmanager
+def chrome_driver(headless: bool = True) -> Iterator[webdriver.Chrome]:
+    """Yield a Chrome driver (found by Selenium Manager) and always quit it."""
+    options = webdriver.ChromeOptions()
+    if headless:
+        options.add_argument("--headless=new")
+    options.add_argument(f"--window-size={WINDOW_SIZE}")
+    driver = webdriver.Chrome(options=options)
+    try:
+        yield driver
+    finally:
+        driver.quit()
@@ -0,0 +1,30 @@
+"""Selenium adapter for the EventSource port."""
+
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from scraping_python_org.domain.event import Event
+
+EVENT_WIDGET_SELECTOR = ".event-widget"
+EVENT_ITEM_SELECTOR = f"{EVENT_WIDGET_SELECTOR} li"
+
+
+class SeleniumEventSource:
+    """Reads the events from the event widget of a page."""
+
+    def __init__(self, driver: WebDriver, url: str) -> None:
+        """Remember the driver and the page to read."""
+        self._driver = driver
+        self._url = url
+
+    def fetch_events(self) -> list[Event]:
+        """Open the page and return one Event per widget list item."""
+        self._driver.get(self._url)
+        items = self._driver.find_elements(By.CSS_SELECTOR, EVENT_ITEM_SELECTOR)
+        return [
+            Event(
+                time=item.find_element(By.TAG_NAME, "time").text,
+                name=item.find_element(By.TAG_NAME, "a").text,
+            )
+            for item in items
+        ]
@@ -0,0 +1 @@
+"""Entry points and the composition root."""
@@ -0,0 +1,16 @@
+"""Command line entry point and composition root."""
+
+from scraping_python_org.application.get_upcoming_events import get_upcoming_events
+from scraping_python_org.infrastructure.chrome import chrome_driver
+from scraping_python_org.infrastructure.selenium_event_source import SeleniumEventSource
+
+PYTHON_ORG_URL = "https://www.python.org/"
+
+
+def main() -> int:
+    """Scrape the upcoming events from python.org and print them."""
+    with chrome_driver() as driver:
+        source = SeleniumEventSource(driver, PYTHON_ORG_URL)
+        events = get_upcoming_events(source)
+    print(events)
+    return 0
@@ -0,0 +1,67 @@
+"""Capture one screenshot per lecture step into docs/screenshots/.
+
+Run with ``python -m scraping_python_org.presentation.screenshots``.
+"""
+
+import html
+import logging
+from pathlib import Path
+from urllib.parse import quote
+
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from scraping_python_org.application.get_upcoming_events import get_upcoming_events
+from scraping_python_org.infrastructure.chrome import chrome_driver
+from scraping_python_org.infrastructure.selenium_event_source import (
+    EVENT_ITEM_SELECTOR,
+    EVENT_WIDGET_SELECTOR,
+    SeleniumEventSource,
+)
+from scraping_python_org.presentation.cli import PYTHON_ORG_URL
+
+logger = logging.getLogger(__name__)
+
+OUTPUT_DIR = Path(__file__).resolve().parents[3] / "docs" / "screenshots"
+HIGHLIGHT_SCRIPT = (
+    "document.querySelectorAll(arguments[0])"
+    ".forEach(li => { li.style.outline = '3px solid red'; });"
+)
+OUTPUT_PAGE = (
+    "<html><body style='margin:0;background:#fff'>"
+    "<pre style='display:inline-block;font:18px Consolas,monospace;"
+    "white-space:pre-wrap;margin:0;padding:24px'>{text}</pre>"
+    "</body></html>"
+)
+
+
+def _render_text(driver: WebDriver, text: str, path: Path) -> None:
+    """Screenshot ``text`` rendered in a <pre> block."""
+    page = OUTPUT_PAGE.format(text=html.escape(text))
+    driver.get("data:text/html;charset=utf-8," + quote(page))
+    driver.find_element(By.TAG_NAME, "pre").screenshot(str(path))
+
+
+def capture(output_dir: Path = OUTPUT_DIR) -> list[Path]:
+    """Write the four lecture screenshots and return their paths."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    home = output_dir / "01-python-org-home.png"
+    widget = output_dir / "02-event-widget.png"
+    highlighted = output_dir / "03-event-list-highlighted.png"
+    output = output_dir / "04-output-dictionary.png"
+    with chrome_driver() as driver:
+        events = get_upcoming_events(SeleniumEventSource(driver, PYTHON_ORG_URL))
+        driver.save_screenshot(str(home))
+        driver.find_element(By.CSS_SELECTOR, EVENT_WIDGET_SELECTOR).screenshot(str(widget))
+        driver.execute_script(HIGHLIGHT_SCRIPT, EVENT_ITEM_SELECTOR)
+        driver.find_element(By.CSS_SELECTOR, EVENT_WIDGET_SELECTOR).screenshot(str(highlighted))
+        _render_text(driver, str(events), output)
+    paths = [home, widget, highlighted, output]
+    for path in paths:
+        logger.info("wrote %s", path)
+    return paths
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    capture()
@@ -0,0 +1,35 @@
+from scraping_python_org.application.get_upcoming_events import get_upcoming_events
+from scraping_python_org.domain.event import Event
+
+
+class FakeEventSource:
+    def __init__(self, events: list[Event]) -> None:
+        self._events = events
+
+    def fetch_events(self) -> list[Event]:
+        return self._events
+
+
+def _events(count: int) -> list[Event]:
+    return [Event(f"11-{i:02d}", f"Event {i}") for i in range(count)]
+
+
+def test_get_upcoming_events_numbers_events_from_zero() -> None:
+    result = get_upcoming_events(FakeEventSource(_events(2)))
+
+    assert result == {
+        0: {"time": "11-00", "name": "Event 0"},
+        1: {"time": "11-01", "name": "Event 1"},
+    }
+
+
+def test_get_upcoming_events_limits_to_five_by_default() -> None:
+    assert list(get_upcoming_events(FakeEventSource(_events(8)))) == [0, 1, 2, 3, 4]
+
+
+def test_get_upcoming_events_honours_custom_limit() -> None:
+    assert len(get_upcoming_events(FakeEventSource(_events(8)), limit=3)) == 3
+
+
+def test_get_upcoming_events_returns_empty_dict_without_events() -> None:
+    assert get_upcoming_events(FakeEventSource([])) == {}
@@ -0,0 +1,15 @@
+import dataclasses
+
+import pytest
+
+from scraping_python_org.domain.event import Event
+
+
+def test_to_dict_returns_time_and_name() -> None:
+    assert Event("2026-11-02", "PyCon").to_dict() == {"time": "2026-11-02", "name": "PyCon"}
+
+
+def test_event_is_immutable() -> None:
+    event = Event("2026-11-02", "PyCon")
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        event.name = "Other"  # type: ignore[misc]
@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Welcome to Python.org (fixture)</title></head>
+<body>
+<div id="content">
+  <div class="medium-widget blog-widget"><ul class="menu"><li><time>2026-01-01</time> <a href="/blog/">Not an event</a></li></ul></div>
+  <div class="medium-widget event-widget last">
+    <div class="shrubbery">
+      <h2 class="widget-title"><span class="prompt">&gt;&gt;&gt;</span> Upcoming Events</h2>
+      <p class="give-me-more"><a href="/events/" title="More Events">More</a></p>
+      <ul class="menu">
+        <li><time datetime="2026-11-02T00:00:00+00:00"><span class="say-no-more">2026-</span>11-02</time> <a href="/events/python-events/1001/">PyCon Alpha</a></li>
+        <li><time datetime="2026-11-05T00:00:00+00:00"><span class="say-no-more">2026-</span>11-05</time> <a href="/events/python-events/1002/">PyData Beta</a></li>
+        <li><time datetime="2026-11-09T00:00:00+00:00"><span class="say-no-more">2026-</span>11-09</time> <a href="/events/python-events/1003/">Django Gamma</a></li>
+        <li><time datetime="2026-11-14T00:00:00+00:00"><span class="say-no-more">2026-</span>11-14</time> <a href="/events/python-events/1004/">EuroPython Delta</a></li>
+        <li><time datetime="2026-11-20T00:00:00+00:00"><span class="say-no-more">2026-</span>11-20</time> <a href="/events/python-events/1005/">PyLadies Epsilon</a></li>
+      </ul>
+    </div>
+  </div>
+</div>
+</body>
+</html>
@@ -0,0 +1,30 @@
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+from selenium import webdriver
+
+from scraping_python_org.infrastructure.chrome import chrome_driver
+from scraping_python_org.infrastructure.selenium_event_source import SeleniumEventSource
+
+FIXTURE = Path(__file__).resolve().parents[1] / "fixtures" / "python_org_events.html"
+
+
+@pytest.fixture(scope="module")
+def driver() -> Iterator[webdriver.Chrome]:
+    with chrome_driver() as chrome:
+        yield chrome
+
+
+@pytest.mark.browser
+def test_fetch_events_reads_widget_items_only(driver: webdriver.Chrome) -> None:
+    events = SeleniumEventSource(driver, FIXTURE.as_uri()).fetch_events()
+
+    assert [event.name for event in events] == [
+        "PyCon Alpha",
+        "PyData Beta",
+        "Django Gamma",
+        "EuroPython Delta",
+        "PyLadies Epsilon",
+    ]
+    assert events[0].time == "2026-11-02"
				`@@ -0,0 +1 @@`
				`"""Scrape the upcoming events from python.org."""`
				`@@ -0,0 +1 @@`
				`"""Drivers and adapters for outside technology."""`
				`@@ -0,0 +1 @@`
				`"""Entry points and the composition root."""`