Plugins and utilities¶

Plugin registry¶

Entry-point plugin discovery for decompression models and formatters.

Third-party packages register plugin classes in their pyproject.toml under the diveplan.deco_models group (subclasses of BaseDecoModel) or the diveplan.formatters group (subclasses of BaseFormatter):

[project.entry-points."diveplan.deco_models"]
mymodel = "my_package.model:MyModel"

[project.entry-points."diveplan.formatters"]
myformat = "my_package.output:MyFormatter"

The module-level registry singleton discovers every entry point in a group eagerly on first access — never register an entry point whose module does not exist yet, as one dangling reference breaks all lookups in its group. PluginRegistry.register_model() and PluginRegistry.register_formatter() are the manual escape hatches for tests and notebooks.

class diveplan.registry.PluginRegistry[source]¶

Bases: object

Deco-model and formatter lookup: entry-point discovery plus manual registration.

Discovery runs once per group and is cached; invalidate() forces a re-scan. Manual registrations shadow discovered plugins of the same name.

model(name)[source]¶

Return the plugin class for name, or raise PluginNotFoundError.

Parameters:: name (str)
Return type:: type[BaseDecoModel[Any]]

all_models()[source]¶

All registered plugins, keyed by name.

Return type:: dict[str, type[BaseDecoModel[Any]]]

register_model(name, cls)[source]¶

Manually register a plugin class — escape hatch for tests, notebooks, or plugins that ship inside the core package.

Overrides any discovered plugin with the same name. Does NOT invalidate the discovery cache.

Parameters:

name (str)
cls (type[BaseDecoModel[Any]])

Return type:

None

formatter(name)[source]¶

Return the formatter class for name, or raise PluginNotFoundError.

Parameters:: name (str)
Return type:: type[BaseFormatter]

all_formatters()[source]¶

All registered formatters, keyed by name.

Return type:: dict[str, type[BaseFormatter]]

register_formatter(name, cls)[source]¶

Manually register a formatter class — escape hatch for tests, notebooks, or plugins that ship inside the core package.

Overrides any discovered plugin with the same name. Does NOT invalidate the discovery cache.

Parameters:

name (str)
cls (type[BaseFormatter])

Return type:

None

invalidate()[source]¶

Force re-discovery of both groups on next access. Useful in tests that install/uninstall packages at runtime.

Return type:: None

exception diveplan.registry.PluginNotFoundError(name, available, kind='decompression model')[source]¶

Bases: KeyError

No plugin is registered under the requested name.

name¶: The name that was looked up.

available¶: Names of all currently registered plugins of that kind.

Parameters:

name (str)
available (list[str])
kind (str)

Return type:

None

exception diveplan.registry.PluginInvalidError[source]¶

Bases: TypeError

A discovered or registered plugin does not subclass its plugin base.

Argument coercion¶

Argument-coercion helpers shared across the user-facing API.

These power the “friendly notation” accepted by the fluent profile builders, GasPlan, and plan_ascent(): depths as "40 m" strings or bare metres, gases by name. Library code coerces at its public boundary and works with Pressure/Gas values internally.

diveplan.utils.conversions.coerce_depth_to_pressure(value)[source]¶

Convert a user-facing depth argument to an absolute Pressure.

Parameters:: value (float | int | str | Pressure) – A Pressure (returned as-is), a string parsed by Pressure.from_str() ("40 m", "4.5 bar", "130 ft"…), or a bare number interpreted as metres of depth.
Return type:: Pressure
Returns:: The corresponding absolute pressure under the current config.
Raises:: ValueError – If the value is a string that cannot be parsed, or an unsupported type.

diveplan.utils.conversions.coerce_gas(value)[source]¶

Convert a user-facing gas argument to a Gas.

Parameters:: value (str | Gas) – A Gas (returned as-is) or a name parsed by Gas.from_name() ("air", "ean50", "tx21/35"…).
Return type:: Gas
Returns:: The corresponding gas mixture.
Raises:: ValueError – If the value is a string that cannot be parsed, or an unsupported type.

diveplan.utils.conversions.duration_from_rate(rate, start_pressure, end_pressure)[source]¶

Traverse duration implied by a rate of pressure change.

Parameters:

rate (float) – Rate of pressure change in mbar per minute (always positive; direction is taken from the pressures).
start_pressure (Pressure) – Pressure at the start of the traverse.
end_pressure (Pressure) – Pressure at the end of the traverse.

Return type:

float

Returns:

Duration in minutes.

diveplan.utils.conversions.DEPTH_TYPES = float | int | str | diveplan.core.pressure.Pressure¶

metres, a parseable string, or a Pressure.

Type:: Accepted spellings of a depth

diveplan.utils.conversions.GAS_TYPES = str | diveplan.core.gas.Gas¶

a name like "ean50" or a Gas.

Type:: Accepted spellings of a gas