spectre-core 0.0.12__py3-none-any.whl → 0.0.13__py3-none-any.whl

spectre_core/capture_configs/_capture_templates.py

@@ -3,168 +3,247 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 from copy import deepcopy
-from typing import Any
-from dataclasses import dataclass
+from typing import Any, Iterator
 
+from ._capture_modes import CaptureMode
 from ._parameters import Parameter, Parameters
-from ._pconstraints import PConstraint
-from ._ptemplates import (
-    PTemplate, 
-    PNames,
-    get_base_ptemplate
-)
+from ._pconstraints import BasePConstraint
+from ._ptemplates import PTemplate, get_base_ptemplate
+from ._ptemplates import PName
 
 class CaptureTemplate:
-    """A managed collection of PTemplates"""
-    def __init__(self):
-        self._ptemplates: dict[str, PTemplate] = {}
+    """A managed collection of parameter templates. Strictly defines what parameters are required
+    in a capture config, and the values each parameter can take.
+    """
+    def __init__(
+        self
+    ) -> None:
+        """Initialise a `CaptureTemplate` instance.
+        """
+        self._ptemplates: dict[PName, PTemplate] = {}
 
 
     @property
-    def name_list(self) -> list[str]:
-        """List the names of all stored PTemplates."""
+    def name_list(
+        self
+    ) -> list[PName]:
+        """The names of all required parameters in the capture template."""
         return list(self._ptemplates.keys())
     
 
-    def add_ptemplate(self,
-                      ptemplate: PTemplate) -> None:
-        """Add a ptemplate to this capture template."""
+    def add_ptemplate(
+        self,
+        ptemplate: PTemplate
+    ) -> None:
+        """Add a parameter template to the capture template.
+
+        :param ptemplate: Describes a required parameter for this capture template.
+        """
         self._ptemplates[ptemplate.name] = ptemplate
 
 
-    def get_ptemplate(self,
-                      parameter_name: str) -> PTemplate:
-        """Get the ptemplate corresponding with the parameter name."""
+    def get_ptemplate(
+        self,
+        parameter_name: PName
+    ) -> PTemplate:
+        """Get the parameter template corresponding to the parameter with the name `parameter_name`.
+
+        :param parameter_name: The name of the parameter.
+        :return: The corresponding `PTemplate` instance.
+        :raises ValueError: If the parameter name is not found in the template.
+        """
         if parameter_name not in self._ptemplates:
             raise ValueError(f"Parameter with name '{parameter_name}' is not found in the template. "
                              f"Expected one of {self.name_list}")   
         return self._ptemplates[parameter_name]
       
 
-    def __apply_parameter_template(self,
-                                   parameter: Parameter):
-        """Apply the corresponding parameter template to the input parameter"""
+    def __apply_parameter_template(
+        self,
+        parameter: Parameter
+    ) -> None:
+        """Apply the corresponding parameter template to the input parameter.
+        
+        As a side effect, the value of the input parameter will be type cast
+        according to the template.
+        """
         ptemplate = self.get_ptemplate(parameter.name)
         parameter.value = ptemplate.apply_template(parameter.value)
 
 
-    def __apply_parameter_templates(self,
-                                    parameters: Parameters) -> None:
-        """Apply the corresponding parameter template to all explictly specified parameters"""
+    def __apply_parameter_templates(
+        self,
+        parameters: Parameters
+    ) -> None:
+        """Apply the corresponding parameter template to each of the input parameters."""
         for parameter in parameters:
             self.__apply_parameter_template(parameter)
 
     
-    def __fill_missing_with_defaults(self,
-                                     parameters: Parameters) -> None:
-        """For any missing parameters (as per the capture template), use the corresponding default value."""
+    def __fill_missing_with_defaults(
+        self,
+        parameters: Parameters
+    ) -> None:
+        """Add default parameters to `parameters` for any missing entries.
+
+        Missing parameters are identified by comparing `parameters` against the
+        current capture template. Defaults are derived from the corresponding
+        parameter templates.
+        """
         for ptemplate in self:
             if ptemplate.name not in parameters.name_list:
+                # no args for `make_parameter` implies the parameter with the default value will be used.
                 parameter = ptemplate.make_parameter()
                 parameters.add_parameter(parameter.name, 
                                          parameter.value)
 
 
-    def apply_template(self,
-                       parameters: Parameters) -> Parameters:
-        """Validate parameters, fill missing with defaults, and return anew."""
-        self.__apply_parameter_templates(parameters)
+    def apply_template(
+        self,
+        parameters: Parameters
+    ) -> Parameters:
+        """Apply the capture template to the input parameters. This involves:
+        
+        - Adding default parameters if they are missing with respect to this template.
+        - Type casting the value of each input parameter according to the corresponding parameter template.
+        - Validating the value of each input parameter against any corresponding pconstraints.
+
+        :param parameters: The parameters to apply this capture template to.
+        :return: A `Parameters` instance compliant with this template.
+        """
         self.__fill_missing_with_defaults(parameters)
+        self.__apply_parameter_templates(parameters)
         return parameters
 
 
-    def __iter__(self):
-        """Iterate over stored ptemplates"""
+    def __iter__(
+        self
+    ) -> Iterator[PTemplate]:
+        """Iterate over stored ptemplates."""
         yield from self._ptemplates.values() 
 
 
-    def set_default(self, 
-                    parameter_name: str, 
-                    default: Any) -> None:
-        """Set the default of an existing ptemplate."""
+    def set_default(
+        self, 
+        parameter_name: PName, 
+        default: Any
+    ) -> None:
+        """Set the default of an existing parameter template.
+
+        :param parameter_name: The name of the parameter template to be updated.
+        :param default: The new default value.
+        """
         self.get_ptemplate(parameter_name).default = default
 
 
-    def set_defaults(self, 
-                     *ptuples: tuple[str, Any]) -> None:
-        """Update defaults for multiple ptemplates."""
+    def set_defaults(
+        self, 
+        *ptuples: tuple[PName, Any]
+    ) -> None:
+        """Update the defaults of multiple parameter templates.
+
+        :param ptuples: Tuples of the form (`parameter_name`, `new_default`) to update defaults.
+        """
         for (parameter_name, default) in ptuples:
             self.set_default(parameter_name, default)
 
 
-    def enforce_default(self,
-                        parameter_name: str) -> None:
-        """Enforce the default of an existing ptemplate"""
+    def enforce_default(
+        self,
+        parameter_name: PName
+    ) -> None:
+        """Set the `enforce_default` attribute of an existing parameter template to True.
+
+        :param parameter_name: The name of the parameter template to enforce its default value.
+        """
         self.get_ptemplate(parameter_name).enforce_default = True
 
 
-    def enforce_defaults(self, 
-                         *parameter_names: str) -> None:
-        """Enforce defaults for multiple parameter names."""
+    def enforce_defaults(
+        self, 
+        *parameter_names: PName
+    ) -> None:
+        """Set the `enforce_default` attribute of multiple existing parameter templates to True.
+
+        :param parameter_names: The names of the parameter templates to enforce their default values.
+        """
         for name in parameter_names:
             self.enforce_default(name)
 
 
-    def add_pconstraint(self,
-                        parameter_name: str,
-                        pconstraints: list[PConstraint]) -> None:
-        """Add a pconstraint to an existing ptemplate"""
+    def add_pconstraint(
+        self,
+        parameter_name: PName,
+        pconstraints: list[BasePConstraint]
+    ) -> None:
+        """Add one or more `PConstraint` instances to an existing parameter template.
+
+        :param parameter_name: The name of the parameter template to add constraints to.
+        :param pconstraints: A list of `PConstraint` instances to be added.
+        """
         for pconstraint in pconstraints:
             self.get_ptemplate(parameter_name).add_pconstraint(pconstraint)
 
 
-    def to_dict(self) -> dict:
-        return {ptemplate.name: ptemplate.to_dict() for ptemplate in self}
+    def to_dict(
+        self
+    ) -> dict[str, dict[str, str]]:
+        """Convert the current instance to a serialisable dictionary.
 
+        :return: A dictionary representation of this capture template, where all values
+        are formatted strings.
+        """
+        return {ptemplate.name.value: ptemplate.to_dict() for ptemplate in self}
+    
+    
+
+def make_base_capture_template(
+    *pnames: PName
+) -> CaptureTemplate:
+    """Make a capture template composed entirely of base `PTemplate` instances.
 
-def make_base_capture_template(*parameter_names: str):
-    """Make a capture template, composed entirely of base ptemplates."""
+    :param pnames: The names of parameters to include in the capture template.
+    :return: A capture template composed of base parameter templates.
+    """
     capture_template = CaptureTemplate()
-    for name in parameter_names:
-        capture_template.add_ptemplate( get_base_ptemplate(name) )
+    for pname in pnames:
+        capture_template.add_ptemplate( get_base_ptemplate(pname) )
     return capture_template
 
 
-@dataclass(frozen=True)
-class CaptureModes:
-    """Pre-defined capture types"""
-    FIXED_CENTER_FREQUENCY: str = "fixed-center-frequency"
-    SWEPT_CENTER_FREQUENCY: str = "swept-center-frequency"
-
-
 def _make_fixed_frequency_capture_template(
 ) -> CaptureTemplate:
     """The absolute minimum required parameters for any fixed frequency capture template."""
     capture_template = make_base_capture_template(
-        PNames.BATCH_SIZE,
-        PNames.CENTER_FREQUENCY,
-        PNames.BATCH_KEY,
-        PNames.EVENT_HANDLER_KEY,
-        PNames.FREQUENCY_RESOLUTION,
-        PNames.INSTRUMENT,
-        PNames.OBS_ALT,
-        PNames.OBS_LAT,
-        PNames.OBS_LON,
-        PNames.OBJECT,
-        PNames.ORIGIN,
-        PNames.SAMPLE_RATE,
-        PNames.TELESCOPE,
-        PNames.TIME_RANGE,
-        PNames.TIME_RESOLUTION,
-        PNames.WATCH_EXTENSION,
-        PNames.WINDOW_HOP,
-        PNames.WINDOW_SIZE,
-        PNames.WINDOW_TYPE,
+        PName.BATCH_SIZE,
+        PName.CENTER_FREQUENCY,
+        PName.BATCH_KEY,
+        PName.EVENT_HANDLER_KEY,
+        PName.FREQUENCY_RESOLUTION,
+        PName.INSTRUMENT,
+        PName.OBS_ALT,
+        PName.OBS_LAT,
+        PName.OBS_LON,
+        PName.OBJECT,
+        PName.ORIGIN,
+        PName.SAMPLE_RATE,
+        PName.TELESCOPE,
+        PName.TIME_RANGE,
+        PName.TIME_RESOLUTION,
+        PName.WATCH_EXTENSION,
+        PName.WINDOW_HOP,
+        PName.WINDOW_SIZE,
+        PName.WINDOW_TYPE,
     )
     capture_template.set_defaults(
-            (PNames.EVENT_HANDLER_KEY,     CaptureModes.FIXED_CENTER_FREQUENCY),
-            (PNames.BATCH_KEY,             CaptureModes.FIXED_CENTER_FREQUENCY),
-            (PNames.WATCH_EXTENSION,       "bin")
+            (PName.EVENT_HANDLER_KEY,     "fixed_center_frequency"),
+            (PName.BATCH_KEY,             "iq_stream"),
+            (PName.WATCH_EXTENSION,       "bin")
     )
     capture_template.enforce_defaults(
-        PNames.EVENT_HANDLER_KEY,
-        PNames.BATCH_KEY,
-        PNames.WATCH_EXTENSION
+        PName.EVENT_HANDLER_KEY,
+        PName.BATCH_KEY,
+        PName.WATCH_EXTENSION
     )
     return capture_template
 
@@ -172,50 +251,56 @@ def _make_swept_frequency_capture_template(
 ) -> CaptureTemplate:
     """The absolute minimum required parameters for any swept frequency capture template."""
     capture_template = make_base_capture_template(
-        PNames.BATCH_SIZE,
-        PNames.BATCH_KEY,
-        PNames.EVENT_HANDLER_KEY,
-        PNames.FREQUENCY_RESOLUTION,
-        PNames.FREQUENCY_STEP,
-        PNames.INSTRUMENT,
-        PNames.MAX_FREQUENCY,
-        PNames.MIN_FREQUENCY,
-        PNames.OBS_ALT,
-        PNames.OBS_LAT,
-        PNames.OBS_LON,
-        PNames.OBJECT,
-        PNames.ORIGIN,
-        PNames.SAMPLE_RATE,
-        PNames.SAMPLES_PER_STEP,
-        PNames.TELESCOPE,
-        PNames.TIME_RANGE,
-        PNames.TIME_RESOLUTION,
-        PNames.WATCH_EXTENSION,
-        PNames.WINDOW_HOP,
-        PNames.WINDOW_SIZE,
-        PNames.WINDOW_TYPE)
+        PName.BATCH_SIZE,
+        PName.BATCH_KEY,
+        PName.EVENT_HANDLER_KEY,
+        PName.FREQUENCY_RESOLUTION,
+        PName.FREQUENCY_STEP,
+        PName.INSTRUMENT,
+        PName.MAX_FREQUENCY,
+        PName.MIN_FREQUENCY,
+        PName.OBS_ALT,
+        PName.OBS_LAT,
+        PName.OBS_LON,
+        PName.OBJECT,
+        PName.ORIGIN,
+        PName.SAMPLE_RATE,
+        PName.SAMPLES_PER_STEP,
+        PName.TELESCOPE,
+        PName.TIME_RANGE,
+        PName.TIME_RESOLUTION,
+        PName.WATCH_EXTENSION,
+        PName.WINDOW_HOP,
+        PName.WINDOW_SIZE,
+        PName.WINDOW_TYPE)
     capture_template.set_defaults(
-            (PNames.EVENT_HANDLER_KEY,     CaptureModes.SWEPT_CENTER_FREQUENCY),
-            (PNames.BATCH_KEY,             CaptureModes.SWEPT_CENTER_FREQUENCY),
-            (PNames.WATCH_EXTENSION,       "bin")
+            (PName.EVENT_HANDLER_KEY,     "swept_center_frequency"),
+            (PName.BATCH_KEY,             "iq_stream"),
+            (PName.WATCH_EXTENSION,       "bin")
     )
     capture_template.enforce_defaults(
-        PNames.EVENT_HANDLER_KEY,
-        PNames.BATCH_KEY,
-        PNames.WATCH_EXTENSION
+        PName.EVENT_HANDLER_KEY,
+        PName.BATCH_KEY,
+        PName.WATCH_EXTENSION
     )
     return capture_template
 
 
-_base_capture_templates = {
-    CaptureModes.FIXED_CENTER_FREQUENCY: _make_fixed_frequency_capture_template(),
-    CaptureModes.SWEPT_CENTER_FREQUENCY: _make_swept_frequency_capture_template()
+_base_capture_templates: dict[CaptureMode, CaptureTemplate] = {
+    CaptureMode.FIXED_CENTER_FREQUENCY: _make_fixed_frequency_capture_template(),
+    CaptureMode.SWEPT_CENTER_FREQUENCY: _make_swept_frequency_capture_template()
 }
 
+
 def get_base_capture_template(
-       capture_mode: str
+    capture_mode: CaptureMode
 ) -> CaptureTemplate:
-    """Create a fresh deep copy of a pre-defined capture template"""
+    """Get a pre-defined capture template, to be configured according to the specific use-case.
+
+    :param capture_mode: The mode used to retrieve the capture template.
+    :return: A deep copy of the template for the specified mode.
+    :raises KeyError: If no capture template is found for the given mode.
+    """
     if capture_mode not in _base_capture_templates:
         raise KeyError(f"No capture template found for the capture mode '{capture_mode}'. "
                        f"Expected one of {list(_base_capture_templates.keys())}")

spectre_core/capture_configs/_parameters.py

@@ -2,85 +2,146 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Any, Optional, TypeVar
+from typing import Any, Optional, TypeVar, Generic, Iterator, overload, cast
 
-T = TypeVar('T')
+from ._pnames import PName
 
-class Parameter:
-    """A named value."""
-    def __init__(self, 
-                 name: str,
-                 value: Optional[T] = None):
+# value type
+VT = TypeVar('VT')
+
+class Parameter(Generic[VT]):
+    """A simple container for a named value."""
+    def __init__(
+        self, 
+        name: PName,
+        value: Optional[VT] = None
+    ) -> None:
+        """Initialise a `Parameter` instance.
+
+        :param name: The name of the parameter.
+        :param value: The value of the parameter. Defaults to None.
+        """
         self._name = name
-        self._value: Optional[T] = value
+        self._value: Optional[VT] = value
 
 
     @property
-    def name(self) -> str:
+    def name(
+        self
+    ) -> PName:
         """The parameter name."""
         return self._name
     
 
     @property
-    def value(self) -> Optional[T]:
+    def value(
+        self
+    ) -> Optional[VT]:
         """The parameter value."""
         return self._value
     
     
     @value.setter
-    def value(self, v: Optional[T]) -> None:
-        """Update the parameter value."""
+    def value(
+        self, 
+        v: Optional[VT]
+    ) -> None:
+        """Update the parameter value.
+
+        :param v: The new value to set for the parameter.
+        """
         self._value = v
 
 
 class Parameters:
-    """A collection of parameters."""
-    def __init__(self):
-        self._parameters: dict[str, Parameter] = {}
+    """A managed collection of parameters."""
+    def __init__(
+        self
+    ) -> None:
+        """Initialise a `Parameters` instance."""
+        self._parameters: dict[PName, Parameter] = {}
+    
     
-
     @property
-    def name_list(self) -> list[str]:
+    def name_list(
+        self
+    ) -> list[PName]:
         """List the names of stored parameters."""
         return list(self._parameters.keys())
 
 
-    def add_parameter(self, 
-                      name: str,
-                      value: Optional[T] = None) -> None:
-        """Add a new parameter."""
+    def add_parameter(
+        self, 
+        name: PName,
+        value: Optional[VT]
+    ) -> None:
+        """Add a `Parameter` instance to this `Parameters` instance with the input name and value.
+
+        :param name: The name of the parameter.
+        :param value: The value of the parameter.
+        :raises KeyError: If a parameter already exists under the input name.
+        """
         if name in self._parameters:
-            raise ValueError(f"Cannot add a parameter with name '{name}', "
-                             f"since a parameter already exists with that name. ")
+            raise KeyError(f"Cannot add a parameter with name '{name}', "
+                           f"since a parameter already exists with that name. ")
         self._parameters[name] = Parameter(name, value)
 
 
-    def get_parameter(self, 
-                      name: str) -> Parameter:
-        """Get the parameter with the corresponding name."""
+    def get_parameter(
+        self, 
+        name: PName
+    ) -> Parameter:
+        """Get the stored `Parameter` instance corresponding to the input name.
+
+        :param name: The name of the parameter.
+        :raises KeyError: If a parameter with the input name does not exist.
+        :return: A `Parameter` instance with the input name, if it exists.
+        """
         if name not in self._parameters:
             raise KeyError(f"Parameter with name '{name}' does not exist. "
                            f"Expected one of {self.name_list}")      
         return self._parameters[name]
 
 
-    def get_parameter_value(self,
-                            name: str) -> Optional[T]:
-        """Get the value of the parameter with the corresponding name."""
+    def get_parameter_value(
+        self,
+        name: PName
+    ) -> Optional[VT]:
+        """Get the value of the parameter with the corresponding name.
+
+        :param name: The name of the parameter.
+        :return: The value of the parameter with the input name.
+        """
         return self.get_parameter(name).value
     
 
-    def __iter__(self):
-        """Iterate over stored parameters"""
+    def __iter__(
+        self
+    ) -> Iterator[Parameter]:
+        """Iterate over stored parameters."""
         yield from self._parameters.values() 
 
     
-    def to_dict(self) -> dict:
-        """Convert the class instance to an equivalent dictionary representation"""
-        return {p.name: p.value for p in self}
+    def to_dict(
+        self
+    ) -> dict[str, Optional[Any]]:
+        """Convert the `Parameters` instance to a serialisable dictionary.
+
+        :return: A dictionary representation of the stored parameters.
+        """
+        return {p.name.value: p.value for p in self}
     
-def _parse_string_parameter(string_parameter: str) -> list[str]:
-    """Parse string of the form 'a=b; into a list of the form [a, b]"""
+
+def _parse_string_parameter(
+    string_parameter: str
+) -> list[str]:
+    """Parse string of the form `a=b` into a list of the form `[a, b]`.
+
+    :param string_parameter: A string representation of a capture config parameter.
+    :raises ValueError: If the input parameter is not of the form `a=b`.
+    :return: The parsed components of the input string parameter, using the `=` character as a separator.
+    The return list will always contain two elements.
+    """
     if not string_parameter or '=' not in string_parameter:
         raise ValueError(f"Invalid format: '{string_parameter}'. Expected 'KEY=VALUE'.")
     if string_parameter.startswith('=') or string_parameter.endswith('='):
@@ -89,9 +150,15 @@ def _parse_string_parameter(string_parameter: str) -> list[str]:
     string_parameter = string_parameter.strip()
     return string_parameter.split('=', 1)
     
-
-def parse_string_parameters(string_parameters: list[str]) -> dict[str, str]:
-    """Parses a list of strings of the form 'a=b'; into a dictionary mapping each 'a' to each 'b'"""
+    
+def parse_string_parameters(
+    string_parameters: list[str]
+) -> dict[str, str]:
+    """Parses a list of strings of the form `a=b` into a dictionary mapping each `a` to each `b`.
+
+    :param string_parameters: A list of strings, where each element is of the form `a=b`.
+    :return: A dictionary mapping each `a` to each `b`, after parsing each element.
+    """
     d = {}
     for string_parameter in string_parameters:
         k, v = _parse_string_parameter(string_parameter)
@@ -99,9 +166,15 @@ def parse_string_parameters(string_parameters: list[str]) -> dict[str, str]:
     return d
     
 
-def make_parameters(d: dict[str, Any]):
-    """Make an instance of parameters based on the input dictionary"""
+def make_parameters(
+    d: dict[str, Any]
+) -> Parameters:
+    """Create a `Parameters` instance from the given dictionary. Each key is interpreted as a valid `PName`.
+
+    :param d: A dictionary where keys represent parameter names and values represent their corresponding values.
+    :return: An instance of `Parameters` with each key-value pair in `d` added as a parameter.
+    """
     parameters = Parameters()
     for k, v in d.items():
-        parameters.add_parameter(k, v)
+        parameters.add_parameter(PName(k), v)
     return parameters