Rename builder class

Author: BrianMichell

src/mdio/core/v1/__init__.py

@@ -4,7 +4,7 @@
 """
 
 from ._overloads import mdio
-from .builder import Builder
+from .builder import MDIODatasetBuilder
 from .builder import write_mdio_metadata
 from ._serializer import (
     make_coordinate,
@@ -17,7 +17,7 @@
 
 
 __all__ = [
-    "Builder",
+    "MDIODatasetBuilder",
     "AbstractTemplateFactory",
     "make_coordinate",
     "make_dataset",

src/mdio/core/v1/builder.py

@@ -43,10 +43,11 @@ class _BuilderState(Enum):
     HAS_VARIABLES = auto()
 
 
-class Builder:
+class MDIODatasetBuilder:
     """Builder for creating MDIO datasets with enforced build order.
 
-    The build order is:
+    This builder implements the builder pattern to create MDIO datasets with a v1 schema.
+    It enforces a specific build order to ensure valid dataset construction:
     1. Must add dimensions first via add_dimension()
     2. Can optionally add coordinates via add_coordinate()
     3. Must add variables via add_variable()
@@ -77,7 +78,7 @@ def add_dimension(
         long_name: str = None,
         data_type: ScalarType | StructuredType = ScalarType.INT32,
         metadata: Optional[List[AllUnits | UserAttributes]] | Dict[str, Any] = None,
-    ) -> "Builder":
+    ) -> "MDIODatasetBuilder":
         """Add a dimension.
 
         This must be called at least once before adding coordinates or variables.
@@ -117,7 +118,7 @@ def add_coordinate(
         dimensions: Optional[List[NamedDimension | str]] = None,
         data_type: ScalarType | StructuredType = ScalarType.FLOAT32,
         metadata: Optional[List[AllUnits | UserAttributes]] | Dict[str, Any] = None,
-    ) -> "Builder":
+    ) -> "MDIODatasetBuilder":
         """Add a coordinate after adding at least one dimension."""
         if self._state == _BuilderState.INITIAL:
             raise ValueError(
@@ -164,7 +165,7 @@ def add_variable(
         compressor: Blosc | ZFP | None = None,
         coordinates: Optional[List[Coordinate | str]] = None,
         metadata: Optional[VariableMetadata] = None,
-    ) -> "Builder":
+    ) -> "MDIODatasetBuilder":
         """Add a variable after adding at least one dimension."""
         if self._state == _BuilderState.INITIAL:
             raise ValueError("Must add at least one dimension before adding variables")

tests/unit/schema/v1/test_template_builder.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from mdio.core.v1.builder import Builder as TemplateBuilder
+from mdio.core.v1.builder import MDIODatasetBuilder
 from mdio.core.v1.builder import _BuilderState
 from mdio.core.v1.builder import write_mdio_metadata
 from mdio.schema.compressors import Blosc
@@ -15,7 +15,7 @@
 
 def test_builder_initialization():
     """Test basic builder initialization."""
-    builder = TemplateBuilder("test_dataset")
+    builder = MDIODatasetBuilder("test_dataset")
     assert builder.name == "test_dataset"
     assert builder.api_version == "1.0.0"
     assert isinstance(builder.created_on, datetime)
@@ -27,7 +27,7 @@ def test_builder_initialization():
 
 def test_dimension_builder_state():
     """Test dimension builder state transitions and functionality."""
-    builder = TemplateBuilder("test_dataset")
+    builder = MDIODatasetBuilder("test_dataset")
 
     # First dimension should change state to HAS_DIMENSIONS and create a variable
     builder = builder.add_dimension("x", 100, long_name="X Dimension")
@@ -55,7 +55,7 @@ def test_dimension_builder_state():
 
 def test_dimension_with_metadata():
     """Test adding dimensions with custom metadata."""
-    builder = TemplateBuilder("test_dataset")
+    builder = MDIODatasetBuilder("test_dataset")
 
     # Add dimension with custom metadata
     builder = builder.add_dimension(
@@ -74,7 +74,7 @@ def test_dimension_with_metadata():
 
 def test_coordinate_builder_state():
     """Test coordinate builder state transitions and functionality."""
-    builder = TemplateBuilder("test_dataset")
+    builder = MDIODatasetBuilder("test_dataset")
 
     # Should not be able to add coordinates before dimensions
     with pytest.raises(
@@ -106,7 +106,7 @@ def test_coordinate_builder_state():
 
 def test_variable_builder_state():
     """Test variable builder state transitions and functionality."""
-    builder = TemplateBuilder("test_dataset")
+    builder = MDIODatasetBuilder("test_dataset")
 
     # Should not be able to add variables before dimensions
     with pytest.raises(
@@ -136,7 +136,7 @@ def test_variable_builder_state():
 def test_build_dataset():
     """Test building a complete dataset."""
     dataset = (
-        TemplateBuilder("test_dataset")
+        MDIODatasetBuilder("test_dataset")
         .add_dimension("x", 100)
         .add_dimension("y", 200)
         .add_coordinate("x_coord", dimensions=["x"])
@@ -159,7 +159,7 @@ def test_build_dataset():
 def test_auto_naming():
     """Test automatic naming of coordinates and variables."""
     dataset = (
-        TemplateBuilder("test_dataset")
+        MDIODatasetBuilder("test_dataset")
         .add_dimension("x", 100)
         .add_coordinate()  # Should be named "coord_0"
         .add_coordinate()  # Should be named "coord_1"
@@ -176,7 +176,7 @@ def test_auto_naming():
 def test_default_dimensions():
     """Test that coordinates and variables use all dimensions by default."""
     dataset = (
-        TemplateBuilder("test_dataset")
+        MDIODatasetBuilder("test_dataset")
         .add_dimension("x", 100)
         .add_dimension("y", 200)
         .add_coordinate()  # Should use both x and y dimensions
@@ -194,7 +194,7 @@ def test_default_dimensions():
 
 def test_build_order_enforcement():
     """Test that the builder enforces the correct build order."""
-    builder = TemplateBuilder("test_dataset")
+    builder = MDIODatasetBuilder("test_dataset")
 
     # Should not be able to add coordinates before dimensions
     with pytest.raises(
@@ -218,7 +218,7 @@ def test_build_order_enforcement():
 def test_toy_example(tmp_path):
     """Test building a toy dataset with multiple variables and attributes."""
     dataset = (
-        TemplateBuilder(
+        MDIODatasetBuilder(
             "campos_3d",
             attributes={
                 "textHeader": [

tests/unit/test_template_factory.py

@@ -1,5 +1,7 @@
 """Unit tests for MDIO v1 factory."""
 
+# TODO(BrianMichell): Update this to use canonical factory functions. 
+
 from datetime import datetime
 from datetime import timezone