How does importlib.metadata.entry_points() let one distribution discover another's plugins?

### The data model An **entry point** is a three-part record stored in an installed distribution's metadata: * a **group** — a namespace string such as `console_scripts` or `hooksrv.handlers`, * a **name** — unique within that group *for that distribution*, * a **value** — `module.path:object`, optionally with a dotted attribute chain after the colon. The records live in `<name>-<version>.dist-info/entry_points.txt` inside the environment's `site-packages`. They are **metadata, not code**: a distribution can advertise an object it never imports, and a reader can see the advertisement without importing anything of the advertiser. ### Declaring a plugin The host project publishes a group name as its plugin contract. A completely unrelated third-party project then writes, in its own `pyproject.toml`: ```toml [project.entry-points."hooksrv.handlers"] github = "hooksrv_github.handler:GitHubHandler" ``` Installing that distribution into the same environment is the entire wiring step. There is no config file to edit, no import line to add to the host, and — critically — the host never needs to know the plugin's name at build time. The reserved groups `console_scripts` and `gui_scripts` are the same mechanism with the installer as the consumer. ### Discovering them ```python from importlib.metadata import entry_points for ep in entry_points(group="hooksrv.handlers"): handler_cls = ep.load() ``` `entry_points()` walks the distributions visible on `sys.path`, parses their metadata, and returns an `EntryPoints` collection — a tuple-like object you can filter with `.select(group=...)` or, equivalently, by passing `group=` / `name=` straight to `entry_points()`. Each element is an `EntryPoint` exposing `.name`, `.value`, `.group`, `.module`, `.attr` and `.load()`. Only `.load()` executes anything: it imports the module named by `.module` and resolves `.attr` on it, returning the object. Discovery is therefore cheap and safe; activation is neither. ### The API changed under you This is version-sensitive and interviewers who have maintained a library will ask about it. In Python 3.9 and earlier, `entry_points()` returned a plain dict of group name to list, so code said `entry_points()["hooksrv.handlers"]`. **3.10** added the selection keywords and deprecated the dict interface; **3.12 removed it**. On 3.14, `entry_points()` returns `EntryPoints`, and subscripting it with a string selects by **entry point name**, not by group — so the old dict-style line does not raise a helpful error, it raises `KeyError` for a group that plainly exists. `entry_points()` also takes no positional arguments: `entry_points("hooksrv.handlers")` is a `TypeError`. For libraries supporting older interpreters, the compatibility answer is the backport distribution rather than version-sniffing. ### Designing the contract The group name is a public API, so namespace it with your project name to avoid colliding with somebody else's idea of `handlers`. Publish what the loaded object must *be* — a class implementing a documented protocol, a factory callable, a module — and validate it after `.load()`, because the type system cannot check across a distribution boundary. Names are not globally unique: two installed distributions may register the same name in your group, and the collection will contain both, so decide precedence deterministically instead of relying on discovery order. Two operational details matter. First, entry points are recorded **at install time**, so editing `pyproject.toml` in an editable checkout does not change what discovery sees until you reinstall. Second, discovery reflects the environment, not your source tree: the same code discovers a different plugin set in a container image than on a developer laptop, which is exactly the property that makes the mechanism useful and exactly the property that makes plugin bugs environment-shaped. The wider plugin-architecture question — when a host should be extensible at all, and how to keep a microkernel core thin — is design theory that belongs elsewhere; what is Python-specific is that the registry is the installed environment itself, maintained by the installer, and readable without importing a single plugin.