Refactor factory methods, etc.

Author: AndrewSazonov

docs/user-guide/analysis-workflow/analysis.md

@@ -269,21 +269,21 @@ An example of setting aliases for parameters in a structure:
 
 ```python
 # Set aliases for the atomic displacement parameters
-project.analysis.aliases.add(
+project.analysis.aliases.add_from_scratch(
     label='biso_La',
     param_uid=project.structures['lbco'].atom_sites['La'].b_iso.uid,
 )
-project.analysis.aliases.add(
+project.analysis.aliases.add_from_scratch(
     label='biso_Ba',
     param_uid=project.structures['lbco'].atom_sites['Ba'].b_iso.uid,
 )
 
 # Set aliases for the occupancies of the atom sites
-project.analysis.aliases.add(
+project.analysis.aliases.add_from_scratch(
     label='occ_La',
     param_uid=project.structures['lbco'].atom_sites['La'].occupancy.uid,
 )
-project.analysis.aliases.add(
+project.analysis.aliases.add_from_scratch(
     label='occ_Ba',
     param_uid=project.structures['lbco'].atom_sites['Ba'].occupancy.uid,
 )
@@ -300,12 +300,12 @@ other aliases.
 An example of setting constraints for the aliases defined above:
 
 ```python
-project.analysis.constraints.add(
+project.analysis.constraints.add_from_scratch(
     lhs_alias='biso_Ba',
     rhs_expr='biso_La',
 )
 
-project.analysis.constraints.add(
+project.analysis.constraints.add_from_scratch(
     lhs_alias='occ_Ba',
     rhs_expr='1 - occ_La',
 )

docs/user-guide/analysis-workflow/experiment.md

@@ -153,7 +153,7 @@ experiment = Experiment(
     radiation_probe='neutron',
     scattering_type='bragg',
 )
-project.experiments.add(experiment)
+project.experiments.add_from_scratch(experiment)
 ```
 
 ## Modifying Parameters
@@ -188,8 +188,8 @@ project.experiments['hrpt'].instrument.calib_twotheta_offset = 0.6
 
 ```python
 # Add excluded regions to the experiment
-project.experiments['hrpt'].excluded_regions.add(start=0, end=10)
-project.experiments['hrpt'].excluded_regions.add(start=160, end=180)
+project.experiments['hrpt'].excluded_regions.add_from_scratch(start=0, end=10)
+project.experiments['hrpt'].excluded_regions.add_from_scratch(start=160, end=180)
 ```
 
 ### 3. Peak Category { #peak-category }
@@ -213,18 +213,18 @@ project.experiments['hrpt'].peak.broad_lorentz_y = 0.1
 project.experiments['hrpt'].background_type = 'line-segment'
 
 # Add background points
-project.experiments['hrpt'].background.add(x=10, y=170)
-project.experiments['hrpt'].background.add(x=30, y=170)
-project.experiments['hrpt'].background.add(x=50, y=170)
-project.experiments['hrpt'].background.add(x=110, y=170)
-project.experiments['hrpt'].background.add(x=165, y=170)
+project.experiments['hrpt'].background.add_from_scratch(x=10, y=170)
+project.experiments['hrpt'].background.add_from_scratch(x=30, y=170)
+project.experiments['hrpt'].background.add_from_scratch(x=50, y=170)
+project.experiments['hrpt'].background.add_from_scratch(x=110, y=170)
+project.experiments['hrpt'].background.add_from_scratch(x=165, y=170)
 ```
 
 ### 5. Linked Phases Category { #linked-phases-category }
 
 ```python
 # Link the structure defined in the previous step to the experiment
-project.experiments['hrpt'].linked_phases.add(id='lbco', scale=10.0)
+project.experiments['hrpt'].linked_phases.add_from_scratch(id='lbco', scale=10.0)
 ```
 
 ### 6. Measured Data Category { #measured-data-category }

docs/user-guide/analysis-workflow/model.md

@@ -64,7 +64,7 @@ reference it later.
 ```python
 # Add a structure with default parameters
 # The structure name is used to reference it later.
-project.structures.add(name='nacl')
+project.structures.add_from_scratch(name='nacl')
 ```
 
 The `add` method creates a new structure with default parameters. You can then

src/easydiffraction/analysis/analysis.py

@@ -416,7 +416,7 @@ def fit_mode(self, strategy: str) -> None:
             # Pre-populate all experiments with weight 0.5
             self.joint_fit_experiments = JointFitExperiments()
             for id in self.project.experiments.names:
-                self.joint_fit_experiments.add(id=id, weight=0.5)
+                self.joint_fit_experiments.add_from_scratch(id=id, weight=0.5)
         console.paragraph('Current fit mode changed to')
         console.print(self._fit_mode)
 
@@ -554,7 +554,7 @@ def fit(self):
                 # parameters can be resolved correctly during fitting.
                 object.__setattr__(dummy_experiments, '_parent', self.project)
 
-                dummy_experiments._add(experiment)
+                dummy_experiments.add(experiment)
                 self.fitter.fit(
                     structures,
                     dummy_experiments,

src/easydiffraction/core/category.py

@@ -103,19 +103,27 @@ def from_cif(self, block):
         """Populate this collection from a CIF block."""
         category_collection_from_cif(self, block)
 
-    @checktype
-    def _add(self, item) -> None:
-        """Add an item to the collection."""
+    def add(self, item) -> None:
+        """Insert a pre-built item into the collection.
+
+        Args:
+            item: A ``CategoryItem`` instance to add.
+        """
         self[item._identity.category_entry_name] = item
 
     @checktype
-    def add(self, **kwargs) -> None:
-        """Create and add a new child instance from the provided
-        arguments.
+    def add_from_scratch(self, **kwargs) -> None:
+        """Create a new item with the given attributes and add it.
+
+        A default instance of the collection's item type is created,
+        then each keyword argument is applied via ``setattr``.
+
+        Args:
+            **kwargs: Attribute names and values for the new item.
         """
         child_obj = self._item_type()
 
         for attr, val in kwargs.items():
             setattr(child_obj, attr, val)
 
-        self._add(child_obj)
+        self.add(child_obj)

src/easydiffraction/core/datablock.py

@@ -3,8 +3,6 @@
 
 from __future__ import annotations
 
-from typeguard import typechecked
-
 from easydiffraction.core.category import CategoryCollection
 from easydiffraction.core.category import CategoryItem
 from easydiffraction.core.collection import CollectionBase
@@ -21,9 +19,17 @@ def __init__(self):
 
     def __str__(self) -> str:
         """Human-readable representation of this component."""
-        name = self._log_name
-        items = getattr(self, '_items', None)
-        return f'<{name} ({items})>'
+        name = self.unique_name
+        cls = type(self).__name__
+        categories = '\n'.join(f'  - {c}' for c in self.categories)
+        return f"{cls} datablock '{name}':\n{categories}"
+
+    def __repr__(self) -> str:
+        """Developer-oriented representation of this component."""
+        name = self.unique_name
+        cls = type(self).__name__
+        num_categories = len(self.categories)
+        return f'<{cls} datablock "{name}" ({num_categories} categories)>'
 
     def _update_categories(
         self,
@@ -88,8 +94,21 @@ class DatablockCollection(CollectionBase):
     Experiments).
 
     Each item is a DatablockItem.
+
+    Subclasses provide explicit ``add_from_*`` convenience methods
+    that delegate to the corresponding factory classmethods, then
+    call :meth:`add` with the resulting item.
     """
 
+    def add(self, item) -> None:
+        """Add a pre-built item to the collection.
+
+        Args:
+            item: A ``DatablockItem`` instance (e.g. a ``Structure``
+                or ``ExperimentBase`` subclass).
+        """
+        self[item._identity.datablock_entry_name] = item
+
     def __str__(self) -> str:
         """Human-readable representation of this component."""
         name = self._log_name
@@ -124,8 +143,3 @@ def as_cif(self) -> str:
         from easydiffraction.io.cif.serialize import datablock_collection_to_cif
 
         return datablock_collection_to_cif(self)
-
-    @typechecked
-    def _add(self, item) -> None:
-        """Add an item to the collection."""
-        self[item._identity.datablock_entry_name] = item

src/easydiffraction/core/factory.py

@@ -8,7 +8,6 @@
 from easydiffraction.datablocks.experiment.item.enums import ScatteringTypeEnum
 
 
-# TODO: Consider inheriting from FactoryBase
 class PeakFactory:
     """Factory for creating peak profile objects.