User functions

enable_engine(domain, engine, /)

Activate engine for domain so its overrides take priority over the defaults.

domain may be the module the domain is named after, an AccelerationDomain, or the name of one; engine may be an AccelerationEngine or the name of one. Enabling an engine that is already active is an idempotent no-op.

Passing the module is preferred:

import mylib
import coheriq

coheriq.enable_engine(mylib, "fast-engine")

A domain is registered as a side effect of importing the library that defines it, so a name can only be looked up once that import has happened. Passing the module removes that ordering hazard, because the module cannot be named before it has been imported.

Passing REFERENCE selects the domain’s own reference implementation. That is worth doing explicitly even though it is what happens by default, because an explicit call takes precedence over the domain’s environment variable: it pins the reference implementation regardless of the surrounding environment, which silence cannot do.

Parameters:

• domain (str | AccelerationDomain | ModuleType)

• engine (str | AccelerationEngine)

Return type:

None

available_engines(domain, /)

Return the names of the engines that can be enabled for domain, sorted.

domain may be the module the domain is named after, an AccelerationDomain, or the name of one.

Every name returned is a valid argument to enable_engine(). The result always includes REFERENCE, the domain’s own reference implementation, so it is never empty. In the current version of Coheriq it is listed first, with the remaining engines following in alphabetical order.

Besides the reference implementation, this reports both engines that have already been registered (because their module has been imported) and engines advertised through the coheriq.engines.<domain> entry point group but not yet imported, since enable_engine() accepts either. Advertised plugins are not imported in order to answer this question, so a name being listed means that enable_engine() will attempt it, not that it is guaranteed to load.

Unlike calling an acceleration candidate, this does not resolve or freeze the implementation: an engine can still be enabled afterwards.

Parameters:

domain (str | AccelerationDomain | ModuleType)

Return type:

tuple[str, …]

active_engine(domain, /)

Return the name of the engine domain has resolved to, or None.

domain may be the module the domain is named after, an AccelerationDomain, or the name of one.

There are three possible results:

• None – the domain has not resolved an engine yet, so a different one can still be enabled.

• REFERENCE (the string "reference") – the domain has resolved to its own reference implementation. It is too late to enable a different engine.

• any other non-empty string – the name of the engine that is active.

None therefore means “not decided yet”, while REFERENCE means “decided on the reference implementation”.

Unlike calling an acceleration candidate, this does not resolve or freeze the implementation.

Parameters:

domain (str | AccelerationDomain | ModuleType)

Return type:

str | None

known_domains()

Return domains known to the current process.

Only domains that have been constructed in the current process are reported. This does not include installed domains from packages that have not yet been imported.

Return type:

tuple[str, …]

REFERENCE = 'reference'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.