enhance template_registry.py documentation for clarity and detail

Author: tasansal

src/mdio/builder/template_registry.py

@@ -1,8 +1,22 @@
-"""Template registry for MDIO v1 dataset templates."""
+"""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``.
+"""
+
+from __future__ import annotations
 
 import copy
 import threading
-from typing import Optional
+from typing import TYPE_CHECKING
 
 from mdio.builder.templates.abstract_dataset_template import AbstractDatasetTemplate
 from mdio.builder.templates.seismic_2d_poststack import Seismic2DPostStackTemplate
@@ -13,15 +27,42 @@
 from mdio.builder.templates.seismic_3d_prestack_coca import Seismic3DPreStackCocaTemplate
 from mdio.builder.templates.seismic_3d_prestack_shot import Seismic3DPreStackShotTemplate
 
+if TYPE_CHECKING:
+    from mdio.builder.templates.abstract_dataset_template import AbstractDatasetTemplate
+
+
+__all__ = [
+    "TemplateRegistry",
+    "get_template_registry",
+    "register_template",
+    "get_template",
+    "is_template_registered",
+    "list_templates",
+]
+
 
 class TemplateRegistry:
-    """A thread-safe singleton registry for dataset templates."""
+    """Thread-safe singleton registry for dataset templates.
 
-    _instance: Optional["TemplateRegistry"] = None
-    _lock = threading.RLock()
-    _initialized = False
+    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.
 
-    def __new__(cls) -> "TemplateRegistry":
+    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.
+    """
+
+    _instance: TemplateRegistry | None = None
+    _lock: threading.RLock = threading.RLock()
+    _initialized: bool = False
+
+    def __new__(cls) -> TemplateRegistry:
         """Create or return the singleton instance.
 
         Uses double-checked locking pattern to ensure thread safety.
@@ -41,21 +82,24 @@ def __init__(self) -> None:
             with self._lock:
                 if not self._initialized:
                     self._templates: dict[str, AbstractDatasetTemplate] = {}
-                    self._registry_lock = threading.RLock()
+                    self._registry_lock: threading.RLock = threading.RLock()
                     self._register_default_templates()
                     TemplateRegistry._initialized = True
 
     def register(self, instance: AbstractDatasetTemplate) -> str:
-        """Register a template instance by its name.
+        """Register a template instance under its public name.
+
+        A deep copy of the provided instance is stored internally to avoid accidental side effects
+        from later external mutations.
 
         Args:
-            instance: An instance of template to register.
+            instance: Template instance to register.
 
         Returns:
-            The name of the registered template.
+            The public name of the registered template.
 
         Raises:
-            ValueError: If the template name is already registered.
+            ValueError: If a template with the same name is already registered.
         """
         with self._registry_lock:
             name = instance.name
@@ -66,9 +110,9 @@ def register(self, instance: AbstractDatasetTemplate) -> str:
         return name
 
     def _register_default_templates(self) -> None:
-        """Register default templates if needed.
+        """Register built-in seismic templates.
 
-        Subclasses can override this method to register default templates.
+        Subclasses may override this hook to extend or change the defaults.
         """
         # Post-Stack Data
         self.register(Seismic2DPostStackTemplate("time"))
@@ -92,8 +136,8 @@ def _register_default_templates(self) -> None:
     def get(self, template_name: str) -> AbstractDatasetTemplate:
         """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.
+        Each call returns a fresh, independent copy of the template that can be modified without affecting
+        the original template or other copies.
 
         Args:
             template_name: The name of the template to retrieve.
@@ -152,7 +196,7 @@ def clear(self) -> None:
             self._templates.clear()
 
     @classmethod
-    def get_instance(cls) -> "TemplateRegistry":
+    def get_instance(cls) -> TemplateRegistry:
         """Get the singleton instance (alternative to constructor).
 
         Returns:
@@ -193,8 +237,8 @@ def register_template(template: AbstractDatasetTemplate) -> str:
 def get_template(name: str) -> AbstractDatasetTemplate:
     """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.
+    Each call returns a fresh, independent instance of the template that can be modified without affecting
+    the original template or other copies.
 
     Args:
         name: The name of the template to retrieve.
@@ -220,6 +264,8 @@ def is_template_registered(name: str) -> bool:
 def list_templates() -> list[str]:
     """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.
     """