Source code for pyml_datasets._registry

"""Registry of the bundled datasets: listing, lookup by name and loading by name.

The names and the tasks of the datasets come from ``datasets/__init__.py``, which is generated
and imports no dataset module. A dataset module is imported when that dataset is asked for,
so the cost of ``import pyml_datasets`` does not grow with the number of datasets.
"""

import importlib
from collections.abc import Callable
from types import ModuleType
from typing import Final

from ._types import Dataset, DatasetInfo, Task
from .datasets import DATASET_TASKS

_PACKAGE: Final = "pyml_datasets"


def _unknown(name: str) -> ValueError:
    """Build the error for a dataset name that is not bundled.

    Parameters
    ----------
    name : str
        The name that was asked for.

    Returns
    -------
    ValueError
        Error that lists the available names.
    """
    available = ", ".join(sorted(DATASET_TASKS))
    return ValueError(f"Unknown dataset {name!r}. Available datasets: {available}.")


def _module(name: str) -> ModuleType:
    """Import the module of a bundled dataset and check it against the generated index.

    Parameters
    ----------
    name : str
        Dataset name.

    Returns
    -------
    types.ModuleType
        The module ``pyml_datasets.datasets.<name>``.

    Raises
    ------
    ValueError
        If no dataset has this name.
    RuntimeError
        If the name or the task in the ``INFO`` of the module differs from the generated
        index, which means ``python -m scripts gen`` was not run after a change.
    """
    if name not in DATASET_TASKS:
        raise _unknown(name)
    module = importlib.import_module(f".datasets.{name}", _PACKAGE)
    info: DatasetInfo = module.INFO
    if info.name != name or info.task != DATASET_TASKS[name]:
        raise RuntimeError(
            f"The index of datasets does not match the INFO of {name!r}. Run python -m scripts gen."
        )
    return module


[docs] def list_datasets(task: Task | None = None) -> tuple[str, ...]: """List the names of the bundled datasets. No dataset module is imported to answer this. Parameters ---------- task : {"classification", "regression"}, optional Keep only the datasets of this task, all datasets if not given. Returns ------- tuple of str Dataset names in alphabetical order. Each name works with ``load_dataset``. Examples -------- >>> from pyml_datasets import list_datasets >>> "iris" in list_datasets() True >>> "iris" in list_datasets("regression") False """ return tuple( sorted(name for name, kind in DATASET_TASKS.items() if task is None or kind == task) )
[docs] def get_info(name: str) -> DatasetInfo: """Return the provenance and license of a dataset without reading its data. Parameters ---------- name : str Dataset name, one of ``list_datasets()``. Returns ------- DatasetInfo License, source, citation and changes of the dataset. Raises ------ ValueError If no dataset has this name. Examples -------- >>> from pyml_datasets import get_info >>> get_info("iris").license 'CC-BY-4.0' """ info: DatasetInfo = _module(name).INFO return info
[docs] def load_dataset(name: str) -> Dataset: """Load a dataset by its name. This is the same as calling the ``load_<name>`` function of the dataset. Parameters ---------- name : str Dataset name, one of ``list_datasets()``. Returns ------- Dataset Freshly loaded dataset. Raises ------ ValueError If no dataset has this name. Examples -------- >>> from pyml_datasets import load_dataset >>> X, y = load_dataset("iris") >>> X.shape (150, 4) """ loader: Callable[[], Dataset] = getattr(_module(name), f"load_{name}") return loader()