Qiskit / coheriq / 41148545228

92%

main: 93%

push

github

Let a module stand in for a domain name (#38)

* Add available_engines() and active_engine() introspection functions

These are the two functions anticipated when enable_engine became a free
function: the argument for that shape was that a domain author should not
have to re-export each new user-facing function, so these follow it.

available_engines(domain) returns a sorted tuple of the engine names that
can be enabled.  It unions the domain's engine registry with the names
advertised through the coheriq.engines.<domain> entry point group, because
enable_engine accepts either.  Advertised plugins are deliberately not
imported to answer the question, so a listed name means enable_engine will
attempt it, not that it is guaranteed to load.

active_engine(domain) returns the name of the enabled engine, or None.
None covers both a domain that has not resolved its implementation yet and
one already frozen on its defaults: "no engine is active" is equally true
of both, and collapsing them keeps the return type str | None.

Neither function resolves or freezes the implementation.  This is the
deliberate contrast with calling a candidate: asking which engine is
active must not commit the domain to an answer, since that would make an
introspection call silently foreclose enabling an engine afterwards.

A sorted tuple rather than a set: these results are usually shown to a
person, and set iteration order for strings varies between processes,
which would make documentation examples and error messages
non-reproducible.

Also factors the domain-or-name coercion out of enable_engine into a
shared _resolve_domain helper, now that three public functions accept
that same argument.

Adds a release note; this is the first note in releasenotes/notes/.

Assisted-by: Claude Opus 5

* Rename active_engine() to active_implementation(), reporting "reference"

The previous signature returned None in two distinct situations: the domain
had not resolved an implementation yet, an... (continued)

55 of 55 new or added lines in 4 files covered. (100.0%)

270 of 295 relevant lines covered (91.53%)

0.92 hits per line