Source code for qblox_scheduler.data_dir

# SPDX-FileCopyrightText: Copyright 2020-2025, Quantify Consortium
# SPDX-FileCopyrightText: © 2026 Qblox <https://qblox.com>
# SPDX-License-Identifier: BSD-3-Clause

"""Data handling utilities for Qblox Scheduler."""

from pathlib import Path
from typing import ClassVar

import rich


def _get_default_datadir(verbose: bool = False) -> Path:
    """
    Returns (and optionally print) a default datadir path.

    Intended for fast prototyping, tutorials, examples, etc..

    Parameters
    ----------
    verbose
        If ``True`` prints the returned datadir.

    Returns
    -------
    :
        The ``Path.home() / "qblox_data"`` path.

    """
    datadir = (Path.home() / "qblox_data").resolve()
    if verbose:
        rich.print(f"Data will be saved in:\n{datadir}")

    return datadir




class OutputDirectoryManager:
    """
    Manages output directory paths for Qblox Scheduler data storage.

    The class maintains a single instance throughout
    the application lifecycle, ensuring consistent directory management.

    Attributes
    ----------
    _datadir : str or Path
        The current data directory path. Private attribute managed through
        setter and getter methods.

    """

    DATADIR: ClassVar[Path] = _get_default_datadir()



    @classmethod
    def set_datadir(cls, datadir: Path | str | None = None) -> None:
        """
        Sets the data directory.

        Parameters
        ----------
        datadir : pathlib.Path or str or None
            Path of the data directory. If set to ``None``, resets the datadir to the
            default datadir (``<top_level>/data``).

        """
        if isinstance(datadir, str):
            datadir = Path(datadir)

        if datadir is None:
            datadir = _get_default_datadir()

        try:
            Path(datadir).mkdir(exist_ok=True, parents=True)
        except PermissionError as e:
            raise PermissionError(
                f"Permission error while setting datadir {datadir}."
                "\nPlease make sure you have the correct permissions."
            ) from e

        cls.DATADIR = datadir




    @classmethod
    def get_datadir(cls) -> Path:
        """
        Returns the current data directory.

        Returns
        -------
        :
            The current data directory.

        """
        if not Path.is_dir(cls.DATADIR):
            raise NotADirectoryError(
                "The datadir is not valid."
                "\nWe recommend to settle for a single common data directory for all \n"
                "notebooks/experiments within your measurement setup/PC.\n"
                "E.g. '~/qblox_data' (unix), or 'D:\\Data\\qblox_data' (Windows).\n"
            )
        return cls.DATADIR