Template Registry¶

A simple, thread-safe place to discover and fetch dataset templates for MDIO.

Why use it¶

One place to find all available templates
Safe to use across threads and the whole app (singleton)
Every fetch gives you your own editable copy (no side effects)
Comes preloaded with common seismic templates

Note

Fetching a template with get_template() returns a deep copy. Editing it will not change the registry or anyone else’s copy.

Quick start¶

from mdio.builder.template_registry import get_template, list_templates

# See what's available
print(list_templates())
# e.g. ["Seismic2DPostStackTime", "Seismic3DPostStackDepth", ...]

# Grab a template by name
template = get_template("Seismic3DPostStackTime")

# Customize your copy (safe)
template.add_units({"amplitude": "unitless"})

Common tasks¶

Fetch a template you can edit¶

from mdio.builder.template_registry import get_template

template = get_template("Seismic2DPostStackDepth")
# Use/modify template freely — it’s your copy

List available templates¶

from mdio.builder.template_registry import list_templates

names = list_templates()
for name in names:
    print(name)

Check if a template exists¶

from mdio.builder.template_registry import is_template_registered

if is_template_registered("Seismic3DPostStackTime"):
    ...  # safe to fetch

Register your own template (optional)¶

If you have a custom template class, register an instance so others can fetch it by name:

from typing import Any
from mdio.builder.template_registry import register_template
from mdio.builder.templates.base import AbstractDatasetTemplate
from mdio.builder.templates.types import SeismicDataDomain


class MyTemplate(AbstractDatasetTemplate):
    def __init__(self, domain: SeismicDataDomain = "time"):
        super().__init__(domain)

    @property
    def _name(self) -> str:
        # The public name becomes something like "MyTemplateTime"
        return f"MyTemplate{self._data_domain.capitalize()}"

    def _load_dataset_attributes(self) -> dict[str, Any]:
        return {"surveyType": "2D", "gatherType": "custom"}


# Make it available globally
registered_name = register_template(MyTemplate("time"))
print(registered_name)  # "MyTemplateTime"

Tip

Use list_templates() to discover the exact names to pass to get_template().

Troubleshooting¶

KeyError: “Template ‘XYZ’ is not registered.”
- The name is wrong or not registered yet.
- Call list_templates() to see valid names, or is_template_registered(name) to check first.

FAQ¶

Do I need to create a TemplateRegistry instance? No. Use the global helpers: get_template, list_templates, register_template, and is_template_registered.
Are templates shared between callers or threads? No. Each get_template() call returns a deep-copied instance that is safe to modify independently.

API reference¶

Template registry for MDIO dataset templates.

This module provides a tiny, thread-safe singleton registry to discover and fetch predefined dataset templates used by the MDIO builder.

Key points

Global, thread-safe singleton (safe to use across threads)
Fetching a template returns a deep-copied instance you can modify freely
Comes pre-populated with common seismic templates

Use the top-level helpers for convenience: get_template, list_templates, register_template, is_template_registered, get_template_registry.

class mdio.builder.template_registry.TemplateRegistry¶

Thread-safe singleton registry for dataset templates.

The registry stores template instances by their public name and returns a deep-copied instance on every retrieval, so callers can safely mutate the returned object without affecting the registry or other callers.

Thread-safety

Creation uses double-checked locking to guarantee a single instance.
Registry operations are protected by an internal re-entrant lock.

Typical usage

Use the module helpers: get_template, list_templates, register_template, and is_template_registered.
Alternatively, use TemplateRegistry.get_instance() for direct access.

Return type:: TemplateRegistry

classmethod get_instance()¶

Get the singleton instance (alternative to constructor).

Returns:: The singleton instance of TemplateRegistry.
Return type:: TemplateRegistry

clear()¶

Clear all registered templates (useful for testing).

Return type:: None

get(template_name)¶

Get an instance of a template from the registry by its name.

Each call returns a fresh, independent copy of the template that can be modified without affecting the original template or other copies.

Parameters:: template_name (str) – The name of the template to retrieve.
Returns:: An instance of the template if found.
Raises:: KeyError – If the template is not registered.
Return type:: AbstractDatasetTemplate

is_registered(template_name)¶

Check if a template is registered in the registry.

Parameters:: template_name (str) – The name of the template to check.
Returns:: True if the template is registered, False otherwise.
Return type:: bool

list_all_templates()¶

Get all registered template names.

Returns:: A list of all registered template names.
Return type:: list[str]

register(instance)¶

A deep copy of the provided instance is stored internally to avoid accidental side effects from later external mutations.

Parameters:: instance (AbstractDatasetTemplate) – Template instance to register.
Returns:: The public name of the registered template.
Raises:: ValueError – If a template with the same name is already registered.
Return type:: str

unregister(template_name)¶

Unregister a template from the registry.

Parameters:: template_name (str) – The name of the template to unregister.
Raises:: KeyError – If the template is not registered.
Return type:: None

mdio.builder.template_registry.get_template(name)¶

Get an instance of a template from the global registry.

Each call returns a fresh, independent instance of the template that can be modified without affecting the original template or other copies.

Parameters:: name (str) – The name of the template to retrieve.
Returns:: An instance of the template if found.
Return type:: AbstractDatasetTemplate

mdio.builder.template_registry.get_template_registry()¶

Get the global template registry instance.

Returns:: The singleton instance of TemplateRegistry.
Return type:: TemplateRegistry

mdio.builder.template_registry.is_template_registered(name)¶

Check if a template is registered in the global registry.

Parameters:: name (str) – The name of the template to check.
Returns:: True if the template is registered, False otherwise.
Return type:: bool

mdio.builder.template_registry.list_templates()¶

List all registered template names.

The order is implementation-defined and may change; do not rely on it for stable sorting.

Returns:: A list of all registered template names.
Return type:: list[str]

mdio.builder.template_registry.register_template(template)¶

Parameters:: template (AbstractDatasetTemplate) – An instance of AbstractDatasetTemplate to register.
Returns:: The name of the registered template.
Return type:: str