nextmv 0.27.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

nextmv/input.py

@@ -1,4 +1,26 @@
-"""Module for handling input sources and data."""
+"""
+Module for handling input sources and data.
+
+This module provides classes and functions for loading and handling input data
+in various formats for decision problems. It supports JSON, plain text, CSV,
+and CSV archive formats and can load data from standard input or files.
+
+Classes
+-------
+InputFormat
+    Enum defining supported input data formats (JSON, TEXT, CSV, CSV_ARCHIVE).
+Input
+    Container for input data with format specification and options.
+InputLoader
+    Base class for loading inputs from various sources.
+LocalInputLoader
+    Class for loading inputs from local files or stdin.
+
+Functions
+---------
+load
+    Load input data using a specified loader.
+"""
 
 import copy
 import csv
@@ -14,7 +36,28 @@ from nextmv.options import Options
 
 
 class InputFormat(str, Enum):
-    """Format of an `Input`."""
+    """
+    Format of an `Input`.
+
+    You can import the `InputFormat` class directly from `nextmv`:
+
+    ```python
+    from nextmv import InputFormat
+    ```
+
+    This enum specifies the supported formats for input data.
+
+    Attributes
+    ----------
+    JSON : str
+        JSON format, utf-8 encoded.
+    TEXT : str
+        Text format, utf-8 encoded.
+    CSV : str
+        CSV format, utf-8 encoded.
+    CSV_ARCHIVE : str
+        CSV archive format: multiple CSV files.
+    """
 
     JSON = "json"
     """JSON format, utf-8 encoded."""
@@ -31,9 +74,15 @@ class Input:
     """
     Input for a decision problem.
 
+    You can import the `Input` class directly from `nextmv`:
+
+    ```python
+    from nextmv import Input
+    ```
+
     Parameters
     ----------
-    data : Any
+    data : Union[dict[str, Any], str, list[dict[str, Any]], dict[str, list[dict[str, Any]]]]
         The actual data.
     input_format : InputFormat, optional
         Format of the input data. Default is `InputFormat.JSON`.
@@ -47,17 +96,46 @@ class Input:
         list[dict[str, Any]],  # CSV
         dict[str, list[dict[str, Any]]],  # CSV_ARCHIVE
     ]
-    """The actual data. The data can be of various types, depending on the
-    input format."""
+    """
+    The actual data.
+
+    The data can be of various types, depending on the input format:
+
+    - For `JSON`: `Union[dict[str, Any], Any]`
+    - For `TEXT`: `str`
+    - For `CSV`: `list[dict[str, Any]]`
+    - For `CSV_ARCHIVE`: `dict[str, list[dict[str, Any]]]`
+    """
 
     input_format: Optional[InputFormat] = InputFormat.JSON
-    """Format of the input data. Default is `InputFormat.JSON`."""
+    """
+    Format of the input data.
+
+    Default is `InputFormat.JSON`.
+    """
+
     options: Optional[Options] = None
-    """Options that the `Input` were created with."""
+    """
+    Options that the `Input` was created with.
+
+    A copy of the options is made during initialization, ensuring the original
+    options remain unchanged even if modified later.
+    """
 
     def __post_init__(self):
-        """Check that the data matches the format given to initialize the
-        class."""
+        """
+        Check that the data matches the format given to initialize the class.
+
+        This method is automatically called after the dataclass is initialized.
+        It validates that the data provided is of the correct type according to
+        the specified input_format and makes a deep copy of the options to ensure
+        the input maintains its own copy.
+
+        Raises
+        ------
+        ValueError
+            If the data type doesn't match the expected type for the given format.
+        """
 
         if self.input_format == InputFormat.JSON:
             try:
@@ -96,14 +174,30 @@ class Input:
         """
         Convert the input to a dictionary.
 
-        Parameters
-        ----------
-        None
+        This method serializes the Input object to a dictionary format that can be
+        easily converted to JSON or other serialization formats.
 
         Returns
         -------
         dict[str, Any]
-            The input as a dictionary.
+            A dictionary containing the input data, format, and options.
+
+            The structure is:
+            ```python
+            {
+                "data": <the input data>,
+                "input_format": <the input format as a string>,
+                "options": <the options as a dictionary or None>
+            }
+            ```
+
+        Examples
+        --------
+        >>> from nextmv.input import Input, InputFormat
+        >>> input_obj = Input(data={"key": "value"}, input_format=InputFormat.JSON)
+        >>> input_dict = input_obj.to_dict()
+        >>> print(input_dict)
+        {'data': {'key': 'value'}, 'input_format': 'json', 'options': None}
         """
 
         return {
@@ -114,7 +208,18 @@ class Input:
 
 
 class InputLoader:
-    """Base class for loading inputs."""
+    """
+    Base class for loading inputs.
+
+    You can import the `InputLoader` class directly from `nextmv`:
+
+    ```python
+    from nextmv import InputLoader
+    ```
+
+    This abstract class defines the interface for input loaders. Subclasses must
+    implement the `load` method to provide concrete input loading functionality.
+    """
 
     def load(
         self,
@@ -154,20 +259,84 @@ class InputLoader:
 
 class LocalInputLoader(InputLoader):
     """
-    Class for loading local inputs. This class can load input data from the
-    local filesystem, by using stdin, a file, or a directory, where applicable.
+    Class for loading local inputs.
+
+    You can import the `LocalInputLoader` class directly from `nextmv`:
+
+    ```python
+    from nextmv import LocalInputLoader
+    ```
+
+    This class can load input data from the local filesystem, by using stdin,
+    a file, or a directory, where applicable. It supports various input formats
+    like JSON, TEXT, CSV, and CSV archive.
+
     Call the `load` method to read the input data.
+
+    Examples
+    --------
+    >>> from nextmv.input import LocalInputLoader, InputFormat
+    >>> loader = LocalInputLoader()
+    >>> # Load JSON from stdin or file
+    >>> input_obj = loader.load(input_format=InputFormat.JSON, path="data.json")
+    >>> # Load CSV from a file
+    >>> input_obj = loader.load(input_format=InputFormat.CSV, path="data.csv")
     """
 
     def _read_text(path: str, _) -> str:
+        """
+        Read a text file and return its contents.
+
+        Parameters
+        ----------
+        path : str
+            Path to the text file.
+        _ : Any
+            Placeholder for unused parameter (for API consistency).
+
+        Returns
+        -------
+        str
+            Contents of the text file with trailing newlines removed.
+        """
         with open(path, encoding="utf-8") as f:
             return f.read().rstrip("\n")
 
     def _read_csv(path: str, csv_configurations: Optional[dict[str, Any]]) -> list[dict[str, Any]]:
+        """
+        Read a CSV file and return its contents as a list of dictionaries.
+
+        Parameters
+        ----------
+        path : str
+            Path to the CSV file.
+        csv_configurations : dict[str, Any], optional
+            Configuration parameters for the CSV DictReader.
+
+        Returns
+        -------
+        list[dict[str, Any]]
+            List of dictionaries where each dictionary represents a row in the CSV.
+        """
         with open(path, encoding="utf-8") as f:
             return list(csv.DictReader(f, **csv_configurations))
 
     def _read_json(path: str, _) -> Union[dict[str, Any], Any]:
+        """
+        Read a JSON file and return its parsed contents.
+
+        Parameters
+        ----------
+        path : str
+            Path to the JSON file.
+        _ : Any
+            Placeholder for unused parameter (for API consistency).
+
+        Returns
+        -------
+        Union[dict[str, Any], Any]
+            Parsed JSON data.
+        """
         with open(path, encoding="utf-8") as f:
             return json.load(f)
 
@@ -177,6 +346,13 @@ class LocalInputLoader(InputLoader):
         InputFormat.TEXT: lambda _: sys.stdin.read().rstrip("\n"),
         InputFormat.CSV: lambda csv_configurations: list(csv.DictReader(sys.stdin, **csv_configurations)),
     }
+    """
+    Dictionary of functions to read from standard input.
+
+    Each key is an InputFormat, and each value is a function that reads from
+    standard input in that format.
+    """
+
     # These callbacks were not implemented with lambda because we needed
     # multiple lines. By using `open`, we needed the `with` to be able to close
     # the file.
@@ -185,6 +361,12 @@ class LocalInputLoader(InputLoader):
         InputFormat.TEXT: _read_text,
         InputFormat.CSV: _read_csv,
     }
+    """
+    Dictionary of functions to read from files.
+
+    Each key is an InputFormat, and each value is a function that reads from
+    a file in that format.
+    """
 
     def load(
         self,
@@ -256,8 +438,27 @@ class LocalInputLoader(InputLoader):
         use_file_reader: bool = False,
     ) -> Union[dict[str, Any], str, list[dict[str, Any]]]:
         """
-        Load a utf-8 encoded file. Can come from stdin or a file in the
-        filesystem.
+        Load a utf-8 encoded file from stdin or filesystem.
+
+        This internal method handles loading data in various formats from either
+        standard input or a file.
+
+        Parameters
+        ----------
+        csv_configurations : dict[str, Any], optional
+            Configuration parameters for the CSV DictReader.
+        path : str, optional
+            Path to the file to read from. If None or empty, reads from stdin.
+        input_format : InputFormat, optional
+            Format of the input data. Default is JSON.
+        use_file_reader : bool, optional
+            Whether to force using the file reader even if path is None.
+            Default is False.
+
+        Returns
+        -------
+        Union[dict[str, Any], str, list[dict[str, Any]]]
+            Data read from stdin or file in the specified format.
         """
 
         # If we forcibly want to use the file reader, we can do so.
@@ -277,7 +478,29 @@ class LocalInputLoader(InputLoader):
         path: Optional[str] = None,
     ) -> dict[str, list[dict[str, Any]]]:
         """
-        Load files from a directory. Will only load CSV files.
+        Load CSV files from a directory.
+
+        This internal method loads all CSV files from a specified directory,
+        organizing them into a dictionary where each key is the filename
+        (without .csv extension) and each value is the parsed CSV content.
+
+        Parameters
+        ----------
+        csv_configurations : dict[str, Any], optional
+            Configuration parameters for the CSV DictReader.
+        path : str, optional
+            Path to the directory containing CSV files. If None or empty,
+            uses "./input" as the default directory.
+
+        Returns
+        -------
+        dict[str, list[dict[str, Any]]]
+            Dictionary mapping filenames to CSV contents.
+
+        Raises
+        ------
+        ValueError
+            If the path is not a directory or the default directory doesn't exist.
         """
 
         dir_path = "input"
@@ -312,32 +535,14 @@ def load_local(
     csv_configurations: Optional[dict[str, Any]] = None,
 ) -> Input:
     """
-    DEPRECATION WARNING
-    ----------
-    `load_local` is deprecated, use `load` instead.
+    !!! warning
+        `load_local` is deprecated, use `load` instead.
+
+    Load input data from local sources.
 
     This is a convenience function for instantiating a `LocalInputLoader`
     and calling its `load` method.
 
-    Load the input data. The input data can be in various formats. For
-    `InputFormat.JSON`, `InputFormat.TEXT`, and `InputFormat.CSV`, the data can
-    be streamed from stdin or read from a file. When the `path` argument is
-    provided (and valid), the input data is read from the file specified by
-    `path`, otherwise, it is streamed from stdin. For
-    `InputFormat.CSV_ARCHIVE`, the input data is read from the directory
-    specified by `path`. If the `path` is not provided, the default location
-    `input` is used. The directory should contain one or more files, where each
-    file in the directory is a CSV file.
-
-    The `Input` that is returned contains the `data` attribute. This data can
-    be of different types, depending on the provided `input_format`:
-
-    - `InputFormat.JSON`: the data is a `dict[str, Any]`.
-    - `InputFormat.TEXT`: the data is a `str`.
-    - `InputFormat.CSV`: the data is a `list[dict[str, Any]]`.
-    - `InputFormat.CSV_ARCHIVE`: the data is a `dict[str, list[dict[str, Any]]]`.
-        Each key is the name of the CSV file, minus the `.csv` extension.
-
     Parameters
     ----------
     input_format : InputFormat, optional
@@ -347,19 +552,22 @@ def load_local(
     path : str, optional
         Path to the input data.
     csv_configurations : dict[str, Any], optional
-        Configurations for loading CSV files. The default `DictReader` is used
-        when loading a CSV file, so you have the option to pass in a dictionary
-        with custom kwargs for the `DictReader`.
+        Configurations for loading CSV files. Custom kwargs for
+        Python's `csv.DictReader`.
 
     Returns
     -------
     Input
-        The input data.
+        The loaded input data in an Input object.
 
     Raises
     ------
     ValueError
-        If the path is not a directory when working with CSV_ARCHIVE.
+        If the path is invalid or data format is incorrect.
+
+    See Also
+    --------
+    load : The recommended function to use instead.
     """
 
     deprecated(
@@ -372,6 +580,7 @@ def load_local(
 
 
 _LOCAL_INPUT_LOADER = LocalInputLoader()
+"""Default instance of LocalInputLoader used by the load function."""
 
 
 def load(
@@ -382,54 +591,63 @@ def load(
     loader: Optional[InputLoader] = _LOCAL_INPUT_LOADER,
 ) -> Input:
     """
-    This is a convenience function for loading an `Input`, i.e.: load the input
-    data. The `loader` is used to call the `.load` method. Note that the
-    default loader is the `LocalInputLoader`.
-
-    The input data can be in various formats. For
-    `InputFormat.JSON`, `InputFormat.TEXT`, and `InputFormat.CSV`, the data can
-    be streamed from stdin or read from a file. When the `path` argument is
-    provided (and valid), the input data is read from the file specified by
-    `path`, otherwise, it is streamed from stdin. For
-    `InputFormat.CSV_ARCHIVE`, the input data is read from the directory
-    specified by `path`. If the `path` is not provided, the default location
-    `input` is used. The directory should contain one or more files, where each
-    file in the directory is a CSV file.
-
-    The `Input` that is returned contains the `data` attribute. This data can
-    be of different types, depending on the provided `input_format`:
-
-    - `InputFormat.JSON`: the data is a `dict[str, Any]`.
-    - `InputFormat.TEXT`: the data is a `str`.
-    - `InputFormat.CSV`: the data is a `list[dict[str, Any]]`.
-    - `InputFormat.CSV_ARCHIVE`: the data is a `dict[str, list[dict[str, Any]]]`.
+    Load input data using the specified loader.
+
+    You can import the `load` function directly from `nextmv`:
+
+    ```python
+    from nextmv import load
+    ```
+
+    This is a convenience function for loading an `Input` object. By default,
+    it uses the `LocalInputLoader` to load data from local sources.
+
+    The input data can be in various formats and can be loaded from different
+    sources depending on the loader:
+
+    - `InputFormat.JSON`: the data is a `dict[str, Any]`
+    - `InputFormat.TEXT`: the data is a `str`
+    - `InputFormat.CSV`: the data is a `list[dict[str, Any]]`
+    - `InputFormat.CSV_ARCHIVE`: the data is a `dict[str, list[dict[str, Any]]]`
         Each key is the name of the CSV file, minus the `.csv` extension.
 
     Parameters
     ----------
-    input_format: InputFormat, optional
+    input_format : InputFormat, optional
         Format of the input data. Default is `InputFormat.JSON`.
-    options: Options, optional
+    options : Options, optional
         Options for loading the input data.
-    path: str, optional
-        Path to the input data.
-    csv_configurations: dict[str, Any], optional
-        Configurations for loading CSV files. The default `DictReader` is used
-        when loading a CSV file, so you have the option to pass in a dictionary
-        with custom kwargs for the `DictReader`.
-    loader: InputLoader, optional
-        The loader to use for loading the input data. Default is
-        `LocalInputLoader`.
+    path : str, optional
+        Path to the input data. For file-based loaders:
+        - If provided, reads from the specified file or directory
+        - If None, typically reads from stdin (for JSON, TEXT, CSV)
+          or uses a default directory (for CSV_ARCHIVE)
+    csv_configurations : dict[str, Any], optional
+        Configurations for loading CSV files. Custom kwargs for
+        Python's `csv.DictReader`.
+    loader : InputLoader, optional
+        The loader to use for loading the input data.
+        Default is an instance of `LocalInputLoader`.
 
     Returns
     -------
     Input
-        The input data.
+        The loaded input data in an Input object.
 
     Raises
     ------
     ValueError
-        If the path is not a directory when working with CSV_ARCHIVE.
+        If the path is invalid or data format is incorrect.
+
+    Examples
+    --------
+    >>> from nextmv.input import load, InputFormat
+    >>> # Load JSON from stdin
+    >>> input_obj = load(input_format=InputFormat.JSON)
+    >>> # Load CSV from a file
+    >>> input_obj = load(input_format=InputFormat.CSV, path="data.csv")
+    >>> # Load CSV archive from a directory
+    >>> input_obj = load(input_format=InputFormat.CSV_ARCHIVE, path="input_dir")
     """
 
     return loader.load(input_format, options, path, csv_configurations)

nextmv/logger.py

@@ -1,14 +1,48 @@
-"""Logger that writes to stderr."""
+"""
+Logger module that writes to stderr.
+
+This module provides utilities for redirecting standard output to standard error
+and for writing log messages directly to stderr.
+
+Functions
+---------
+redirect_stdout
+    Redirect all messages written to stdout to stderr.
+reset_stdout
+    Reset stdout to its original value.
+log
+    Log a message to stderr.
+"""
 
 import sys
 
+# Original stdout reference held when redirection is active
 __original_stdout = None
+# Flag to track if stdout has been redirected
 __stdout_redirected = False
 
 
 def redirect_stdout() -> None:
-    """Redirect all messages written to stdout to stderr. When you do not want
-    to redirect stdout anymore, call `reset_stdout`."""
+    """
+    Redirect all messages written to stdout to stderr.
+
+    You can import the `redirect_stdout` function directly from `nextmv`:
+
+    ```python
+    from nextmv import redirect_stdout
+    ```
+
+    This function captures the current sys.stdout and replaces it with sys.stderr.
+    When redirection is no longer needed, call `reset_stdout()` to restore the
+    original stdout.
+
+    Examples
+    --------
+    >>> redirect_stdout()
+    >>> print("This will go to stderr")
+    >>> reset_stdout()
+    >>> print("This will go to stdout")
+    """
 
     global __original_stdout, __stdout_redirected
     if __stdout_redirected:
@@ -20,9 +54,26 @@ def redirect_stdout() -> None:
 
 
 def reset_stdout() -> None:
-    """Reset stdout to its original value. This function should always be
-    called after `redirect_stdout` to avoid unexpected behavior."""
+    """
+    Reset stdout to its original value.
+
+    You can import the `reset_stdout` function directly from `nextmv`:
+
+    ```python
+    from nextmv import reset_stdout
+    ```
+
+    This function should always be called after `redirect_stdout()` to avoid
+    unexpected behavior. It restores the original stdout that was captured
+    during redirection.
 
+    Examples
+    --------
+    >>> redirect_stdout()
+    >>> print("This will go to stderr")
+    >>> reset_stdout()
+    >>> print("This will go to stdout")
+    """
     global __original_stdout, __stdout_redirected
     if not __stdout_redirected:
         return
@@ -40,8 +91,21 @@ def log(message: str) -> None:
     """
     Log a message to stderr.
 
-    Args:
-        message: The message to log.
+    You can import the `log` function directly from `nextmv`:
+
+    ```python
+    from nextmv import log
+    ```
+
+    Parameters
+    ----------
+    message : str
+        The message to log.
+
+    Examples
+    --------
+    >>> log("An error occurred")
+    An error occurred
     """
 
     print(message, file=sys.stderr)