nextmv 1.0.0.dev4__py3-none-any.whl → 1.0.0.dev5__py3-none-any.whl

nextmv/options.py

@@ -24,155 +24,6 @@ from dataclasses import dataclass
 from typing import Any
 
 from nextmv.base_model import BaseModel
-from nextmv.deprecated import deprecated
-
-
-@dataclass
-class Parameter:
-    """
-    !!! warning
-        `Parameter` is deprecated, use `Option` instead.
-
-    Parameter that is used in a `Configuration`. When a parameter is required,
-    it is a good practice to provide a default value for it. This is because
-    the configuration will raise an error if a required parameter is not
-    provided through a command-line argument, an environment variable or a
-    default value.
-
-    Parameters
-    ----------
-    name : str
-        The name of the parameter.
-
-    param_type : type
-        The type of the parameter.
-
-    default : Any, optional
-        The default value of the parameter. Even though this is optional, it is
-        recommended to provide a default value for all parameters.
-
-    description : str, optional
-        An optional description of the parameter. This is useful for generating
-        help messages for the configuration.
-
-    required : bool, optional
-        Whether the parameter is required. If a parameter is required, it will
-        be an error to not provide a value for it, either through a command-line
-        argument, an environment variable or a default value.
-
-    choices : list[Optional[Any]], optional
-        Limits values to a specific set of choices.
-
-    Examples
-    --------
-    >>> from nextmv.options import Parameter
-    >>> parameter = Parameter("timeout", int, 60, "The maximum timeout in seconds", required=True)
-    """
-
-    name: str
-    """The name of the parameter."""
-    param_type: type
-    """The type of the parameter."""
-
-    default: Any | None = None
-    """The default value of the parameter. Even though this is optional, it is
-    recommended to provide a default value for all parameters."""
-    description: str | None = None
-    """An optional description of the parameter. This is useful for generating
-    help messages for the configuration."""
-    required: bool = False
-    """Whether the parameter is required. If a parameter is required, it will
-    be an error to not provide a value for it, either trough a command-line
-    argument, an environment variable or a default value."""
-    choices: list[Any | None] = None
-    """Limits values to a specific set of choices."""
-
-    def __post_init__(self):
-        """
-        Post-initialization hook that marks this class as deprecated.
-
-        This method is automatically called after the object is initialized.
-        It displays a deprecation warning to inform users to use the `Option` class instead.
-        """
-        deprecated(
-            name="Parameter",
-            reason="`Parameter` is deprecated, use `Option` instead",
-        )
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "Parameter":
-        """
-        !!! warning
-            `Parameter` is deprecated, use `Option` instead.
-            `Parameter.from_dict` -> `Option.from_dict`
-
-        Creates an instance of `Parameter` from a dictionary.
-
-        Parameters
-        ----------
-        data : dict[str, Any]
-            The dictionary representation of a parameter.
-
-        Returns
-        -------
-        Parameter
-            An instance of `Parameter`.
-        """
-
-        deprecated(
-            name="Parameter.from_dict",
-            reason="`Parameter` is deprecated, use `Option` instead. Parameter.from_dict -> Option.from_dict",
-        )
-
-        param_type_string = data["param_type"]
-        param_type = getattr(builtins, param_type_string.split("'")[1])
-
-        return Parameter(
-            name=data["name"],
-            param_type=param_type,
-            default=data.get("default"),
-            description=data.get("description"),
-            required=data.get("required", False),
-            choices=data.get("choices"),
-        )
-
-    def to_dict(self) -> dict[str, Any]:
-        """
-        !!! warning
-            `Parameter` is deprecated, use `Option` instead.
-            `Parameter.to_dict` -> `Option.to_dict`
-
-        Converts the parameter to a dict.
-
-        Returns
-        -------
-        dict[str, Any]
-            The parameter as a dict with its name, type, default value,
-            description, required flag, and choices.
-
-        Examples
-        --------
-        >>> param = Parameter("timeout", int, 60, "Maximum time in seconds", True)
-        >>> param_dict = param.to_dict()
-        >>> param_dict["name"]
-        'timeout'
-        >>> param_dict["default"]
-        60
-        """
-
-        deprecated(
-            name="Parameter.to_dict",
-            reason="`Parameter` is deprecated, use `Option` instead. Parameter.to_dict -> Option.to_dict",
-        )
-
-        return {
-            "name": self.name,
-            "param_type": str(self.param_type),
-            "default": self.default,
-            "description": self.description,
-            "required": self.required,
-            "choices": self.choices,
-        }
 
 
 @dataclass
@@ -425,8 +276,7 @@ class Options:
         If a required option is not provided through a command-line
         argument, an environment variable or a default value.
     TypeError
-        If an option is not either an `Option` or `Parameter` (deprecated)
-        object.
+        If an option is not an `Option`
     ValueError
         If an environment variable is not of the type of the corresponding
         parameter.
@@ -522,27 +372,6 @@ class Options:
 
         return cloud_dict
 
-    def parameters_dict(self) -> list[dict[str, Any]]:
-        """
-        !!! warning
-            `Parameter` is deprecated, use `Option` instead. `Options.parameters_dict` -> `Options.options_dict`
-
-        Converts the options to a list of dicts. Each dict is the dict
-        representation of a `Parameter`.
-
-        Returns
-        -------
-        list[dict[str, Any]]
-            The list of dictionaries (parameter entries).
-        """
-
-        deprecated(
-            name="Options.parameters_dict",
-            reason="`Parameter` is deprecated, use `Option` instead. Options.parameters_dict -> Options.options_dict",
-        )
-
-        return [param.to_dict() for param in self.options]
-
     def options_dict(self) -> list[dict[str, Any]]:
         """
         Converts the `Options` to a list of dicts. Each dict is the dict
@@ -606,7 +435,7 @@ class Options:
             If a required option is not provided through a command-line
             argument, an environment variable or a default value.
         TypeError
-            If an option is not an `Option` or `Parameter` (deprecated) object.
+            If an option is not an `Option` object.
         ValueError
             If an environment variable is not of the type of the corresponding
             parameter.
@@ -728,41 +557,6 @@ class Options:
 
         return cls(*options)
 
-    @classmethod
-    def from_parameters_dict(cls, parameters_dict: list[dict[str, Any]]) -> "Options":
-        """
-        !!! warning
-
-            `Parameter` is deprecated, use `Option` instead.
-            `Options.from_parameters_dict` -> `Options.from_options_dict`
-
-        Creates an instance of `Options` from parameters in dict form. Each
-        entry is the dict representation of a `Parameter`.
-
-        Parameters
-        ----------
-        parameters_dict : list[dict[str, Any]]
-            The list of dictionaries (parameter entries).
-
-        Returns
-        -------
-        Options
-            An instance of `Options`.
-        """
-
-        deprecated(
-            name="Options.from_parameters_dict",
-            reason="`Parameter` is deprecated, use `Option` instead. "
-            "Options.from_parameters_dict -> Options.from_options_dict",
-        )
-
-        parameters = []
-        for parameter_dict in parameters_dict:
-            parameter = Parameter.from_dict(parameter_dict)
-            parameters.append(parameter)
-
-        return cls(*parameters)
-
     @classmethod
     def from_options_dict(cls, options_dict: list[dict[str, Any]]) -> "Options":
         """
@@ -837,7 +631,7 @@ class Options:
             If a required option is not provided through a command-line
             argument, an environment variable or a default value.
         TypeError
-            If an option is not an `Option` or `Parameter` (deprecated) object.
+            If an option is not an `Option` object.
         ValueError
             If an environment variable is not of the type of the corresponding
             parameter.
@@ -858,10 +652,8 @@ class Options:
         options_by_field_name: dict[str, Option] = {}
 
         for ix, option in enumerate(self.options):
-            if not isinstance(option, Option) and not isinstance(option, Parameter):
-                raise TypeError(
-                    f"expected an <Option> (or deprecated <Parameter>) object, but got {type(option)} in index {ix}"
-                )
+            if not isinstance(option, Option):
+                raise TypeError(f"expected an <Option> object, but got {type(option)} in index {ix}")
 
             # See comment below about ipykernel adding a `-f` argument. We
             # restrict options from having the name 'f' or 'fff' for that
@@ -876,7 +668,7 @@ class Options:
             option.name = option.name.lstrip("-")
 
             kwargs = {
-                "type": self._option_type(option) if self._option_type(option) is not bool else str,
+                "type": option.option_type if option.option_type is not bool else str,
                 "help": self._description(option),
             }
 
@@ -925,12 +717,10 @@ class Options:
             env_value = os.getenv(upper_name)
             if env_value is not None:
                 try:
-                    typed_env_value = (
-                        self._option_type(option)(env_value) if self._option_type(option) is not bool else env_value
-                    )
+                    typed_env_value = option.option_type(env_value) if option.option_type is not bool else env_value
                 except ValueError:
                     raise ValueError(
-                        f'environment variable "{upper_name}" is not of type {self._option_type(option)}'
+                        f'environment variable "{upper_name}" is not of type {option.option_type}'
                     ) from None
 
                 value = self._option_value(option, typed_env_value)
@@ -968,8 +758,6 @@ class Options:
         """
 
         description = ""
-        if isinstance(option, Parameter):
-            description = "DEPRECATED (initialized with <Parameter>, use <Option> instead) "
 
         description += f"[env var: {option.name.upper()}]"
 
@@ -979,7 +767,7 @@ class Options:
         if option.default is not None:
             description += f" (default: {option.default})"
 
-        description += f" (type: {self._option_type(option).__name__})"
+        description += f" (type: {option.option_type.__name__})"
 
         if isinstance(option, Option) and option.additional_attributes is not None:
             description += f" (additional attributes: {option.additional_attributes})"
@@ -1020,7 +808,7 @@ class Options:
             other values are converted to False.
         """
 
-        opt_type = self._option_type(option)
+        opt_type = option.option_type
         if opt_type is not bool:
             return value
 
@@ -1031,39 +819,6 @@ class Options:
 
         return False
 
-    @staticmethod
-    def _option_type(option: Option | Parameter) -> type:
-        """
-        Get the type of an option.
-
-        This auxiliary function was introduced for backwards compatibility with
-        the deprecated `Parameter` class. Once `Parameter` is removed, this function
-        can be removed as well. When the function is removed, use the
-        `option.option_type` attribute directly, instead of calling this function.
-
-        Parameters
-        ----------
-        option : Union[Option, Parameter]
-            The option to get the type for.
-
-        Returns
-        -------
-        type
-            The type of the option.
-
-        Raises
-        ------
-        TypeError
-            If the option is not an `Option` or `Parameter` object.
-        """
-
-        if isinstance(option, Option):
-            return option.option_type
-        elif isinstance(option, Parameter):
-            return option.param_type
-        else:
-            raise TypeError(f"expected an <Option> (or deprecated <Parameter>) object, but got {type(option)}")
-
 
 class OptionsEnforcement:
     """

nextmv/output.py

@@ -8,9 +8,9 @@ destinations.
 Classes
 -------
 RunStatistics
-    Statistics about a general run.
+    Deprecated: Statistics about a general run.
 ResultStatistics
-    Statistics about a specific result.
+    Deprecated: Statistics about a specific result.
 DataPoint
     A data point representing a 2D coordinate.
 Series
@@ -18,7 +18,10 @@ Series
 SeriesData
     Data container for multiple series of data points.
 Statistics
-    Complete statistics container for a solution, including run metrics and result data.
+    Deprecated: Use metrics instead. Complete statistics container for a
+    solution, including run metrics and result data.
+Metrics
+    Metrics container for a solution.
 OutputFormat
     Enumeration of supported output formats.
 SolutionFile
@@ -46,7 +49,9 @@ Attributes
 ASSETS_KEY : str
     Assets key constant used for identifying assets in the run output.
 STATISTICS_KEY : str
-    Statistics key constant used for identifying statistics in the run output.
+    Deprecated: Use METRICS_KEY instead. Statistics key constant used for identifying statistics in the run output.
+METRICS_KEY : str
+    Metrics key constant used for identifying metrics in the run output.
 SOLUTIONS_KEY : str
     Solutions key constant used for identifying solutions in the run output.
 OUTPUTS_KEY : str
@@ -66,7 +71,6 @@ from pydantic import AliasChoices, Field
 
 from nextmv._serialization import serialize_json
 from nextmv.base_model import BaseModel
-from nextmv.deprecated import deprecated
 from nextmv.logger import reset_stdout
 from nextmv.options import Options
 
@@ -76,7 +80,11 @@ Assets key constant used for identifying assets in the run output.
 """
 STATISTICS_KEY = "statistics"
 """
-Statistics key constant used for identifying statistics in the run output.
+Deprecated: Use METRICS_KEY instead. Statistics key constant used for identifying statistics in the run output.
+"""
+METRICS_KEY = "metrics"
+"""
+Metrics key constant used for identifying metrics in the run output.
 """
 SOLUTIONS_KEY = "solutions"
 """
@@ -90,7 +98,7 @@ Outputs key constant used for identifying outputs in the run output.
 
 class RunStatistics(BaseModel):
     """
-    Statistics about a general run.
+    Deprecated: Statistics about a general run.
 
     You can import the `RunStatistics` class directly from `nextmv`:
 
@@ -130,7 +138,7 @@ class RunStatistics(BaseModel):
 
 class ResultStatistics(BaseModel):
     """
-    Statistics about a specific result.
+    Deprecated: Statistics about a specific result.
 
     You can import the `ResultStatistics` class directly from `nextmv`:
 
@@ -170,7 +178,7 @@ class ResultStatistics(BaseModel):
 
 class DataPoint(BaseModel):
     """
-    A data point representing a 2D coordinate.
+    Deprecated: A data point representing a 2D coordinate.
 
     You can import the `DataPoint` class directly from `nextmv`:
 
@@ -203,7 +211,7 @@ class DataPoint(BaseModel):
 
 class Series(BaseModel):
     """
-    A series of data points for visualization or analysis.
+    Deprecated: A series of data points for visualization or analysis.
 
     You can import the `Series` class directly from `nextmv`:
 
@@ -237,7 +245,7 @@ class Series(BaseModel):
 
 class SeriesData(BaseModel):
     """
-    Data container for multiple series of data points.
+    Deprecated: Data container for multiple series of data points.
 
     You can import the `SeriesData` class directly from `nextmv`:
 
@@ -272,6 +280,9 @@ class SeriesData(BaseModel):
 
 class Statistics(BaseModel):
     """
+    !!! warning
+    `Statistics` is deprecated, use `Metrics` instead.
+
     Complete statistics container for a solution, including run metrics and
     result data.
 
@@ -878,7 +889,9 @@ class Output:
         The solution to the decision problem. The type must match the
         `output_format`. Default is None.
     statistics : Optional[Union[Statistics, dict[str, Any]]], optional
-        Statistics of the solution. Default is None.
+        Deprecated: Use Metrics instead. Statistics of the solution. Default is None.
+    metrics : Optional[dict[str, Any]], optional
+        Metrics of the solution. Default is None.
     csv_configurations : Optional[dict[str, Any]], optional
         Configuration for writing CSV files. Default is None.
     json_configurations : Optional[dict[str, Any]], optional
@@ -917,17 +930,16 @@ class Output:
     Examples
     --------
     >>> from nextmv.output import Output, OutputFormat, Statistics, RunStatistics
-    >>> run_stats = RunStatistics(duration=30.0, iterations=100)
-    >>> stats = Statistics(run=run_stats)
+    >>> metrics = {"duration": 30.0, "iterations": 100}
     >>> solution = {"routes": [{"vehicle": 1, "stops": [1, 2, 3]}, {"vehicle": 2, "stops": [4, 5]}]}
     >>> output = Output(
     ...     output_format=OutputFormat.JSON,
     ...     solution=solution,
-    ...     statistics=stats,
+    ...     metrics=metrics,
     ...     json_configurations={"indent": 4}
     ... )
     >>> output_dict = output.to_dict()
-    >>> "solution" in output_dict and "statistics" in output_dict
+    >>> "solution" in output_dict and "metrics" in output_dict
     True
     """
 
@@ -970,11 +982,16 @@ class Output:
     """
     statistics: Statistics | dict[str, Any] | None = None
     """
+    Deprecated: Use Metrics instead.
     Statistics of the solution. These statistics can be of type `Statistics` or a
     simple dictionary. If the statistics are of type `Statistics`, they will be
     serialized to a dictionary using the `to_dict` method. If they are a
-    dictionary, they will be used as is. If the statistics are not provided, an
-    empty dictionary will be used.
+    dictionary, they will be used as is.
+    """
+    metrics: dict[str, Any] | None = None
+    """
+    Metrics of the solution. These metrics should be provided as a simple or
+    nested dictionary.
     """
     csv_configurations: dict[str, Any] | None = None
     """
@@ -1089,7 +1106,7 @@ class Output:
         # Statistics need to end up as a dict, so we achieve that based on the
         # type of statistics that were used to create the class.
         if self.statistics is None:
-            statistics = {}
+            statistics = None
         elif isinstance(self.statistics, Statistics):
             statistics = self.statistics.to_dict()
         elif isinstance(self.statistics, dict):
@@ -1099,6 +1116,18 @@ class Output:
                 f"unsupported statistics type: {type(self.statistics)}, supported types are `Statistics` or `dict`"
             )
 
+        if self.metrics is None:
+            metrics = None
+        elif isinstance(self.metrics, dict):
+            metrics = self.metrics
+        else:
+            raise TypeError(f"unsupported metrics type: {type(self.metrics)}, supported type is `dict`")
+
+        # if both metrics and statistics are None, set statistics to an 
+        # empty dict for backward compatibility
+        if statistics is None and metrics is None:
+            statistics = {}
+            
         # Assets need to end up as a list of dicts, so we achieve that based on
         # the type of each asset in the list.
         assets = []
@@ -1118,10 +1147,16 @@ class Output:
         output_dict = {
             "options": options,
             "solution": self.solution if self.solution is not None else {},
-            STATISTICS_KEY: statistics,
             ASSETS_KEY: assets,
         }
 
+        # Only include statistics in output if it's not None
+        if statistics is not None:
+            output_dict[STATISTICS_KEY] = statistics
+
+        if metrics is not None:
+            output_dict[METRICS_KEY] = metrics
+
         # Add the auxiliary configurations to the output dictionary if they are
         # defined and not empty.
         if (
@@ -1194,9 +1229,9 @@ class LocalOutputWriter(OutputWriter):
 
     Examples
     --------
-    >>> from nextmv.output import LocalOutputWriter, Output, Statistics
+    >>> from nextmv.output import LocalOutputWriter, Output, Metrics
     >>> writer = LocalOutputWriter()
-    >>> output = Output(solution={"result": 42}, statistics=Statistics())
+    >>> output = Output(solution={"result": 42}, metrics={"time": 1.23})
     >>> # Write to stdout
     >>> writer.write(output, path=None)
     >>> # Write to a file
@@ -1518,67 +1553,6 @@ class LocalOutputWriter(OutputWriter):
         )
 
 
-def write_local(
-    output: Output | dict[str, Any],
-    path: str | None = None,
-    skip_stdout_reset: bool = False,
-) -> None:
-    """
-    !!! warning
-        `write_local` is deprecated, use `write` instead.
-
-    Write the output to the local filesystem or stdout.
-
-    This is a convenience function for instantiating a `LocalOutputWriter` and
-    calling its `write` method.
-
-    Parameters
-    ----------
-    output : Union[Output, dict[str, Any]]
-        Output data to write. Can be an Output object or a dictionary.
-    path : str, optional
-        Path to write the output data to. The interpretation depends on the
-        output format:
-
-        - For `OutputFormat.JSON`: File path for the JSON output. If None or
-          empty, writes to stdout.
-        - For `OutputFormat.CSV_ARCHIVE`: Directory path for CSV files. If None
-          or empty, writes to a directory named "output" in the current working
-          directory.
-    skip_stdout_reset : bool, optional
-        Skip resetting stdout before writing the output data. Default is False.
-
-    Raises
-    ------
-    ValueError
-        If the Output.output_format is not supported.
-    TypeError
-        If the output is of an unsupported type.
-
-    Notes
-    -----
-    This function detects if stdout was redirected and resets it to avoid
-    unexpected behavior. If you want to skip this behavior, set the
-    skip_stdout_reset parameter to True.
-
-    Examples
-    --------
-    >>> from nextmv.output import write_local, Output
-    >>> # Write JSON to a file
-    >>> write_local(Output(solution={"result": 42}), path="result.json")
-    >>> # Write JSON to stdout
-    >>> write_local({"simple": "data"})
-    """
-
-    deprecated(
-        name="write_local",
-        reason="`write_local` is deprecated, use `write` instead",
-    )
-
-    writer = LocalOutputWriter()
-    writer.write(output, path, skip_stdout_reset)
-
-
 _LOCAL_OUTPUT_WRITER = LocalOutputWriter()
 """Default LocalOutputWriter instance used by the write function."""