Python Entry Points

Background reading: how packages register themselves for discovery without hard imports

The Problem

Montage Concord's fit package (when built) will need to find all installed metric and model implementations in order to use them for optimization. The naive solution would be a big import list:

# Naive approach — hardcoded list of every metric
from concord_metrics_univariate import LineLength, HjorthParameters
from concord_metrics_spectral import WelchPSD, BandPower
from concord_metrics_connectivity import PLV, Coherence
# ... and so on for every metric in every package

ALL_METRICS = [LineLength, HjorthParameters, WelchPSD, BandPower, PLV, ...]

This approach breaks the independence of the packages: fit would need to know about (and import from) every metric package. Adding a new metric would require editing fit. That's the opposite of modularity.

Entry Points: Self-Registration

Python's package system allows packages to register themselves under named groups. When you install a package with pip install -e ./concord-metrics-univariate, pip reads its pyproject.toml and stores metadata about what the package provides. Later, any other code can ask: "give me all registered providers of the 'concord.metrics' group."

This is the entry_points system — named after the mechanism in Python's standard library (importlib.metadata.entry_points).

How a Package Registers Itself

In a metric package's pyproject.toml:

[project.entry-points."concord.metrics"]
line_length = "concord_metrics_univariate:LineLength"
hjorth      = "concord_metrics_univariate:HjorthParameters"

This says: "under the group concord.metrics, I provide two entries. The entry named line_length refers to the class LineLength in the module concord_metrics_univariate."

After running pip install -e ./concord-metrics-univariate, these registrations are stored in the package's metadata on disk (not imported yet — just recorded).

How a Consumer Discovers All Registered Classes

from importlib.metadata import entry_points

# Ask for all registered concord.metrics implementations
eps = entry_points(group="concord.metrics")

all_metrics = []
for ep in eps:
    MetricClass = ep.load()   # this is where the import actually happens
    all_metrics.append(MetricClass())

# all_metrics now contains instances of every installed metric
print([m.name for m in all_metrics])
# ["line_length", "hjorth_parameters", "welch_psd", "band_power", ...]

Key insight: the fit package doesn't import anything explicitly. It asks the Python package system for whatever is registered, and loads them on demand. When someone installs a new third-party metric package that registers itself in the same group, fit automatically discovers it — without any code changes.

The Group Name is a Convention

"concord.metrics" is just a string — a namespace agreed on by all packages. Models would use "concord.models". Any string works; the dot-separated format is a convention to avoid collisions with other software.

Analogy: Plugin Systems

You may have used software that has "plugins" — add-on features that you install separately and the main program automatically detects. Audio editors, IDEs, game engines — they all use a similar plugin registration concept. Python entry_points is the standard mechanism for this in the Python ecosystem.

Another familiar example: pytest uses entry_points for its plugins. When you install pytest-cov, it registers itself under pytest11. pytest discovers it automatically and activates the coverage feature — you don't have to tell pytest it's installed.

Console Scripts

Entry points are also used for command-line tools. This is why you can run pytest or pip from the terminal — these are registered as console_scripts:

[project.scripts]
pytest = "pytest:main"     # creates a 'pytest' command that calls pytest.main()

concord-server could similarly register itself as a console command:

[project.scripts]
concord-server = "concord_server.server:main"
# Then you could just type: concord-server

Summary