Rename to NamePlaceholder

Author: ax3l

src/pals/kinds/ElementReference.py src/pals/kinds/PlaceholderName.pysrc/pals/kinds/ElementReference.py renamed to src/pals/kinds/PlaceholderName.py

@@ -6,8 +6,11 @@
 from .mixin import BaseElement
 
 
-class ElementReference(BaseModel):
-    """A pydantic model that represents a reference to a named element.
+class PlaceholderName(BaseModel):
+    """Represents a reference to a named element.
+
+    This placeholder is replaced with a physically distinct
+    element during beamline expansion.
 
     This class behaves like a string (via __str__ and __eq__) but stores
     a true reference to the actual element object once it's resolved.
@@ -19,7 +22,7 @@ class ElementReference(BaseModel):
         element: A reference to the resolved element object (None until resolved)
 
     Example:
-        >>> ref = ElementReference(name="drift1")
+        >>> ref = PlaceholderName(name="drift1")
         >>> ref.name
         'drift1'
         >>> str(ref)
@@ -65,7 +68,7 @@ def __eq__(self, other: object) -> bool:
         """Enable string comparison."""
         if isinstance(other, str):
             return self.name == other
-        if isinstance(other, ElementReference):
+        if isinstance(other, PlaceholderName):
             return self.name == other.name and self.element is other.element
         return False
 
@@ -78,6 +81,6 @@ def is_resolved(self) -> bool:
         return self.element is not None
 
     def __repr__(self) -> str:
-        """Return a representation of the ElementReference."""
+        """Return a representation of the PlaceholderName."""
         resolved = "resolved" if self.is_resolved() else "unresolved"
-        return f"ElementReference('{self.name}', {resolved})"
+        return f"PlaceholderName('{self.name}', {resolved})"

src/pals/kinds/__init__.py

@@ -11,7 +11,6 @@
 from .CrabCavity import CrabCavity  # noqa: F401
 from .Drift import Drift  # noqa: F401
 from .EGun import EGun  # noqa: F401
-from .ElementReference import ElementReference  # noqa: F401
 from .Feedback import Feedback  # noqa: F401
 from .Fiducial import Fiducial  # noqa: F401
 from .FloorShift import FloorShift  # noqa: F401
@@ -27,6 +26,7 @@
 from .NullEle import NullEle  # noqa: F401
 from .Octupole import Octupole  # noqa: F401
 from .Patch import Patch  # noqa: F401
+from .PlaceholderName import PlaceholderName  # noqa: F401
 from .Quadrupole import Quadrupole  # noqa: F401
 from .RBend import RBend  # noqa: F401
 from .RFCavity import RFCavity  # noqa: F401

src/pals/kinds/all_elements.py

@@ -14,7 +14,7 @@
 from .CrabCavity import CrabCavity
 from .Drift import Drift
 from .EGun import EGun
-from .ElementReference import ElementReference
+from .PlaceholderName import PlaceholderName
 from .Feedback import Feedback
 from .Fiducial import Fiducial
 from .FloorShift import FloorShift
@@ -83,13 +83,13 @@ def get_all_element_types(extra_types: tuple = None):
 
 
 def get_all_elements_as_annotation(extra_types: tuple = None):
-    """Return the Union type of all allowed elements with their name as the discriminator field.
+    """Return the Union type of all allowed elements with their kind as the discriminator field.
 
-    Note: ElementReference is included to support string references to named elements.
-    Since ElementReference doesn't have a 'kind' field, we cannot use discriminator.
+    Note: PlaceholderName is included to support string references to named elements.
+    Since PlaceholderName doesn't have a 'kind' field, we cannot use discriminator.
     Pydantic will still properly validate the union by trying each type in order in
     our unpack_element_list_structure method.
     """
-    types = get_all_element_types(extra_types) + (ElementReference,)
-    # We can't use discriminator with ElementReference in the union since it has no 'kind' field
+    types = get_all_element_types(extra_types) + (PlaceholderName,)
+    # We can't use discriminator with PlaceholderName in the union since it has no 'kind' field
     return Union[types]

src/pals/kinds/mixin/all_element_mixin.py

@@ -5,7 +5,7 @@
 """
 
 from . import BaseElement
-from ..ElementReference import ElementReference
+from ..PlaceholderName import PlaceholderName
 
 
 def unpack_element_list_structure(
@@ -45,12 +45,12 @@ def unpack_element_list_structure(
     for item in data[field_name]:
         # An element can be a string that refers to another element
         if isinstance(item, str):
-            # Wrap the string in an ElementReference object
-            new_list.append(ElementReference(item))
+            # Wrap the string in a Placeholder name object
+            new_list.append(PlaceholderName(item))
             continue
-        # An element can be an ElementReference instance directly
-        elif isinstance(item, ElementReference):
-            # Keep the ElementReference as-is
+        # An element can be a PlaceholderName instance directly
+        elif isinstance(item, PlaceholderName):
+            # Keep the PlaceholderName as-is
             new_list.append(item)
             continue
         # An element can be a dict
@@ -77,7 +77,7 @@ def unpack_element_list_structure(
                 continue
 
             raise TypeError(
-                f"Value must be a reference string, ElementReference, or a dict, but we got {item!r}"
+                f"Value must be a reference string, PlaceholderName, or a dict, but we got {item!r}"
             )
 
     data[field_name] = new_list

tests/test_elements.py

@@ -561,15 +561,15 @@ def test_BeamLine_with_string_references():
     assert beamline.name == "fodo_cell"
     assert len(beamline.line) == 3
 
-    # First element should be an ElementReference that behaves like the string "drift1"
-    assert isinstance(beamline.line[0], pals.ElementReference)
+    # First element should be a PlaceholderName that behaves like the string "drift1"
+    assert isinstance(beamline.line[0], pals.PlaceholderName)
     assert beamline.line[0] == "drift1"
     assert beamline.line[0].name == "drift1"
     assert beamline.line[0].element is None  # Not yet resolved
     assert not beamline.line[0].is_resolved()
 
-    # Second element should be an ElementReference that behaves like the string "quad1"
-    assert isinstance(beamline.line[1], pals.ElementReference)
+    # Second element should be a PlaceholderName that behaves like the string "quad1"
+    assert isinstance(beamline.line[1], pals.PlaceholderName)
     assert beamline.line[1] == "quad1"
     assert beamline.line[1].name == "quad1"
     assert beamline.line[1].element is None  # Not yet resolved
@@ -588,17 +588,17 @@ def test_BeamLine_with_string_references():
     assert beamline.line[0].element.length == 1.0
 
 
-def test_ElementReference_direct():
-    """Test ElementReference creation and behavior directly"""
+def test_PlaceholderName_direct():
+    """Test PlaceholderName creation and behavior directly"""
     # Test creation with positional argument
-    ref1 = pals.ElementReference("test_element")
+    ref1 = pals.PlaceholderName("test_element")
     assert ref1.name == "test_element"
     assert str(ref1) == "test_element"
     assert ref1 == "test_element"
     assert not ref1.is_resolved()
 
     # Test creation with keyword argument
-    ref2 = pals.ElementReference(name="another_element")
+    ref2 = pals.PlaceholderName(name="another_element")
     assert ref2.name == "another_element"
     assert str(ref2) == "another_element"
     assert ref2 == "another_element"