FeatureRegistry#

Defined in: voxatlas.core.registry

class voxatlas.core.registry.FeatureRegistry[source]#

Bases: object

Register, inspect, and resolve VoxAtlas feature extractors.

The registry is the central lookup table used by discovery, the CLI, and the pipeline. It stores extractor metadata and optionally tracks features that are unavailable because optional dependencies are missing.

Examples

Usage example:

registry = FeatureRegistry()
registry.register(MyExtractor)
print(registry.list_features())

register(extractor_cls)[source]#

Register an available extractor class.

Parameters:: extractor_cls (type of BaseExtractor) – Extractor class to register.
Returns:: The same extractor class, which makes this method usable as a decorator target.
Return type:: type of BaseExtractor
Raises:: ValueError – Raised when the extractor contract is invalid or the feature name is already registered to a different class.

Notes

Re-registering the same class is treated as a no-op.

Examples

Usage example:

registry.register(MyExtractor)

register_unavailable(*, name, dependencies=None, input_units=None, output_units=None, missing_dependency=None, module_name=None)[source]#

Register metadata for a feature that cannot currently be imported.

Parameters:

name (str) – Feature name.
dependencies (list of str | tuple of str | None) – Declared upstream feature dependencies.
input_units (str | None) – Declared input unit level.
output_units (str | None) – Declared output unit level.
missing_dependency (str | None) – Optional missing dependency name.
module_name (str | None) – Module that defines the feature.

Returns:

The registry is updated in place.

Return type:

None

Notes

This path is used by feature discovery so the CLI can still report features that are unavailable in the current environment.

Examples

Usage example:

registry.register_unavailable(
    name="syntax.dependencies",
    missing_dependency="spacy",
)

get(name)[source]#

Resolve an extractor class from its feature name.

Parameters:: name (str) – Requested feature name.
Returns:: Extractor class registered for the feature.
Return type:: type of BaseExtractor
Raises:: FeatureNotRegisteredError – Raised when the feature is unknown or unavailable.

Examples

Usage example:

extractor_cls = registry.get("acoustic.pitch.f0")
print(extractor_cls.__name__)

get_entry(name)[source]#

Retrieve registry metadata for one feature.

Parameters:: name (str) – Requested feature name.
Returns:: Metadata entry for the feature.
Return type:: FeatureRegistryEntry
Raises:: FeatureNotRegisteredError – Raised when the feature name is unknown.

Examples

Usage example:

entry = registry.get_entry("acoustic.pitch.f0")
print(entry.available)

list()[source]#

Return every registered feature entry in sorted order.

Returns:: Registered entries sorted by feature name.
Return type:: list of FeatureRegistryEntry

Examples

Usage example:

print(registry.list())

list_features()[source]#

Return the sorted list of registered feature names.

Returns:: Registered feature names.
Return type:: list of str

Examples

Usage example:

print(registry.list_features())

by_family(family_name)[source]#

Return all entries that belong to a feature family.

Parameters:: family_name (str) – Family prefix such as "acoustic.pitch".
Returns:: Entries whose names match the requested family prefix.
Return type:: list of FeatureRegistryEntry

Examples

Usage example:

entries = registry.by_family("acoustic.pitch")
print([entry.name for entry in entries])

grouped()[source]#

Group registered entries by their first two name segments.

Returns:: Mapping from family prefix to registry entries.
Return type:: dict

Examples

Usage example:

grouped = registry.grouped()
print(grouped.keys())

clear()[source]#

Remove all registry entries.

Returns:: The registry is cleared in place.
Return type:: None

Examples

Usage example:

registry.clear()