Input Module

This section documents the input components of the Nextmv Python SDK.

input

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.

CLASS	DESCRIPTION
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.

FUNCTION	DESCRIPTION
load	Load input data using a specified loader.

Input dataclass

Input(
    data: Union[
        Union[dict[str, Any], Any],
        str,
        list[dict[str, Any]],
        dict[str, list[dict[str, Any]]],
    ],
    input_format: Optional[InputFormat] = JSON,
    options: Optional[Options] = None,
)

Input for a decision problem.

You can import the Input class directly from nextmv:

from nextmv import Input

PARAMETER	DESCRIPTION
data	The actual data. TYPE: Union[dict[str, Any], str, list[dict[str, Any]], dict[str, list[dict[str, Any]]]]
input_format	Format of the input data. Default is InputFormat.JSON. TYPE: InputFormat DEFAULT: JSON
options	Options that the input was created with. TYPE: Options DEFAULT: None

data instance-attribute

data: Union[
    Union[dict[str, Any], Any],
    str,
    list[dict[str, Any]],
    dict[str, list[dict[str, Any]]],
]

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 class-attribute instance-attribute

input_format: Optional[InputFormat] = JSON

Format of the input data.

Default is InputFormat.JSON.

options class-attribute instance-attribute

options: Optional[Options] = None

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.

to_dict

to_dict() -> dict[str, Any]

Convert the input to a dictionary.

This method serializes the Input object to a dictionary format that can be easily converted to JSON or other serialization formats.

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing the input data, format, and options. The structure is: { "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}

Source code in nextmv/nextmv/input.py

def to_dict(self) -> dict[str, Any]:
    """
    Convert the input to a dictionary.

    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]
        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 {
        "data": self.data,
        "input_format": self.input_format.value,
        "options": self.options.to_dict() if self.options is not None else None,
    }

InputFormat

Bases: str, Enum

Format of an Input.

You can import the InputFormat class directly from nextmv:

from nextmv import InputFormat

This enum specifies the supported formats for input data.

ATTRIBUTE	DESCRIPTION
JSON	JSON format, utf-8 encoded. TYPE: str
TEXT	Text format, utf-8 encoded. TYPE: str
CSV	CSV format, utf-8 encoded. TYPE: str
CSV_ARCHIVE	CSV archive format: multiple CSV files. TYPE: str

CSV class-attribute instance-attribute

CSV = 'csv'

CSV format, utf-8 encoded.

CSV_ARCHIVE class-attribute instance-attribute

CSV_ARCHIVE = 'csv-archive'

CSV archive format: multiple CSV files.

JSON class-attribute instance-attribute

JSON = 'json'

JSON format, utf-8 encoded.

TEXT class-attribute instance-attribute

TEXT = 'text'

Text format, utf-8 encoded.

InputLoader

Base class for loading inputs.

You can import the InputLoader class directly from nextmv:

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.

load

load(
    input_format: InputFormat = JSON,
    options: Optional[Options] = None,
    *args,
    **kwargs,
) -> Input

Read the input data. This method should be implemented by subclasses.

PARAMETER	DESCRIPTION
input_format	Format of the input data. Default is InputFormat.JSON. TYPE: InputFormat DEFAULT: JSON
options	Options for loading the input data. TYPE: Options DEFAULT: None
*args	Additional positional arguments. DEFAULT: ()
**kwargs	Additional keyword arguments. DEFAULT: {}

RETURNS	DESCRIPTION
Input	The input data.

RAISES	DESCRIPTION
NotImplementedError	If the method is not implemented.

Source code in nextmv/nextmv/input.py

def load(
    self,
    input_format: InputFormat = InputFormat.JSON,
    options: Optional[Options] = None,
    *args,
    **kwargs,
) -> Input:
    """
    Read the input data. This method should be implemented by
    subclasses.

    Parameters
    ----------
    input_format : InputFormat, optional
        Format of the input data. Default is `InputFormat.JSON`.
    options : Options, optional
        Options for loading the input data.
    *args
        Additional positional arguments.
    **kwargs
        Additional keyword arguments.

    Returns
    -------
    Input
        The input data.

    Raises
    ------
    NotImplementedError
        If the method is not implemented.
    """

    raise NotImplementedError

LocalInputLoader

Bases: InputLoader

Class for loading local inputs.

You can import the LocalInputLoader class directly from nextmv:

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")

FILE_READERS class-attribute instance-attribute

FILE_READERS = {
    JSON: _read_json,
    TEXT: _read_text,
    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.

STDIN_READERS class-attribute instance-attribute

STDIN_READERS = {
    JSON: lambda _: load(stdin),
    TEXT: lambda _: rstrip("\n"),
    CSV: lambda csv_configurations: list(
        DictReader(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.

load

load(
    input_format: Optional[InputFormat] = JSON,
    options: Optional[Options] = None,
    path: Optional[str] = None,
    csv_configurations: Optional[dict[str, Any]] = None,
) -> Input

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.

PARAMETER	DESCRIPTION
input_format	Format of the input data. Default is InputFormat.JSON. TYPE: InputFormat DEFAULT: JSON
options	Options for loading the input data. TYPE: Options DEFAULT: None
path	Path to the input data. TYPE: str DEFAULT: None
csv_configurations	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. TYPE: dict[str, Any] DEFAULT: None

RETURNS	DESCRIPTION
Input	The input data.

RAISES	DESCRIPTION
ValueError	If the path is not a directory when working with CSV_ARCHIVE.

Source code in nextmv/nextmv/input.py

def load(
    self,
    input_format: Optional[InputFormat] = InputFormat.JSON,
    options: Optional[Options] = None,
    path: Optional[str] = None,
    csv_configurations: Optional[dict[str, Any]] = None,
) -> Input:
    """
    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
        Format of the input data. Default is `InputFormat.JSON`.
    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`.

    Returns
    -------
    Input
        The input data.

    Raises
    ------
    ValueError
        If the path is not a directory when working with CSV_ARCHIVE.
    """

    data: Any = None
    if csv_configurations is None:
        csv_configurations = {}

    if input_format in [InputFormat.JSON, InputFormat.TEXT, InputFormat.CSV]:
        data = self._load_utf8_encoded(path=path, input_format=input_format, csv_configurations=csv_configurations)
    elif input_format == InputFormat.CSV_ARCHIVE:
        data = self._load_archive(path=path, csv_configurations=csv_configurations)

    return Input(data=data, input_format=input_format, options=options)

load

load(
    input_format: Optional[InputFormat] = JSON,
    options: Optional[Options] = None,
    path: Optional[str] = None,
    csv_configurations: Optional[dict[str, Any]] = None,
    loader: Optional[InputLoader] = _LOCAL_INPUT_LOADER,
) -> Input

Load input data using the specified loader.

You can import the load function directly from nextmv:

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.

PARAMETER	DESCRIPTION
input_format	Format of the input data. Default is InputFormat.JSON. TYPE: InputFormat DEFAULT: JSON
options	Options for loading the input data. TYPE: Options DEFAULT: None
path	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) TYPE: str DEFAULT: None
csv_configurations	Configurations for loading CSV files. Custom kwargs for Python's csv.DictReader. TYPE: dict[str, Any] DEFAULT: None
loader	The loader to use for loading the input data. Default is an instance of LocalInputLoader. TYPE: InputLoader DEFAULT: _LOCAL_INPUT_LOADER

RETURNS	DESCRIPTION
Input	The loaded input data in an Input object.

RAISES	DESCRIPTION
ValueError	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")

Source code in nextmv/nextmv/input.py

def load(
    input_format: Optional[InputFormat] = InputFormat.JSON,
    options: Optional[Options] = None,
    path: Optional[str] = None,
    csv_configurations: Optional[dict[str, Any]] = None,
    loader: Optional[InputLoader] = _LOCAL_INPUT_LOADER,
) -> Input:
    """
    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
        Format of the input data. Default is `InputFormat.JSON`.
    options : Options, optional
        Options for loading the input data.
    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 loaded input data in an Input object.

    Raises
    ------
    ValueError
        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)

load_local

load_local(
    input_format: Optional[InputFormat] = JSON,
    options: Optional[Options] = None,
    path: Optional[str] = None,
    csv_configurations: Optional[dict[str, Any]] = None,
) -> Input

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.

PARAMETER	DESCRIPTION
input_format	Format of the input data. Default is InputFormat.JSON. TYPE: InputFormat DEFAULT: JSON
options	Options for loading the input data. TYPE: Options DEFAULT: None
path	Path to the input data. TYPE: str DEFAULT: None
csv_configurations	Configurations for loading CSV files. Custom kwargs for Python's csv.DictReader. TYPE: dict[str, Any] DEFAULT: None

RETURNS	DESCRIPTION
Input	The loaded input data in an Input object.

RAISES	DESCRIPTION
ValueError	If the path is invalid or data format is incorrect.

See Also

load : The recommended function to use instead.

Source code in nextmv/nextmv/input.py

def load_local(
    input_format: Optional[InputFormat] = InputFormat.JSON,
    options: Optional[Options] = None,
    path: Optional[str] = None,
    csv_configurations: Optional[dict[str, Any]] = None,
) -> Input:
    """
    !!! 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.

    Parameters
    ----------
    input_format : InputFormat, optional
        Format of the input data. Default is `InputFormat.JSON`.
    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. Custom kwargs for
        Python's `csv.DictReader`.

    Returns
    -------
    Input
        The loaded input data in an Input object.

    Raises
    ------
    ValueError
        If the path is invalid or data format is incorrect.

    See Also
    --------
    load : The recommended function to use instead.
    """

    deprecated(
        name="load_local",
        reason="`load_local` is deprecated, use `load` instead.",
    )

    loader = LocalInputLoader()
    return loader.load(input_format, options, path, csv_configurations)