_config

openml._config

Store module level information like the API key, cache directory and the server

ConfigurationForExamples

ConfigurationForExamples(manager: OpenMLConfigManager)

Allows easy switching to and from a test configuration, used for examples.

Source code in openml/_config.py

def __init__(self, manager: OpenMLConfigManager):
    self._manager = manager
    self._test_apikey = manager._TEST_SERVER_NORMAL_USER_KEY
    self._test_server = f"{manager.TEST_SERVER_URL}/api/v1/xml"

start_using_configuration_for_example

start_using_configuration_for_example() -> None

Sets the configuration to connect to the test server with valid apikey.

To configuration as was before this call is stored, and can be recovered by using the stop_use_example_configuration method.

Source code in openml/_config.py

def start_using_configuration_for_example(self) -> None:
    """Sets the configuration to connect to the test server with valid apikey.

    To configuration as was before this call is stored, and can be recovered
    by using the `stop_use_example_configuration` method.
    """
    if (
        self._start_last_called
        and self._manager._config.server == self._test_server
        and self._manager._config.apikey == self._test_apikey
    ):
        # Method is called more than once in a row without modifying the server or apikey.
        # We don't want to save the current test configuration as a last used configuration.
        return

    self._last_used_server = self._manager._config.server
    self._last_used_key = self._manager._config.apikey
    type(self)._start_last_called = True

    # Test server key for examples
    self._manager._config = replace(
        self._manager._config,
        server=self._test_server,
        apikey=self._test_apikey,
    )
    warnings.warn(
        f"Switching to the test server {self._test_server} to not upload results to "
        "the live server. Using the test server may result in reduced performance of the "
        "API!",
        stacklevel=2,
    )

stop_using_configuration_for_example

stop_using_configuration_for_example() -> None

Return to configuration as it was before start_use_example_configuration.

Source code in openml/_config.py

def stop_using_configuration_for_example(self) -> None:
    """Return to configuration as it was before `start_use_example_configuration`."""
    if not type(self)._start_last_called:
        # We don't want to allow this because it will (likely) result in the `server` and
        # `apikey` variables being set to None.
        raise RuntimeError(
            "`stop_use_example_configuration` called without a saved config."
            "`start_use_example_configuration` must be called first.",
        )

    self._manager._config = replace(
        self._manager._config,
        server=cast("str", self._last_used_server),
        apikey=cast("str", self._last_used_key),
    )
    type(self)._start_last_called = False

OpenMLConfig dataclass

OpenMLConfig(apikey: str | None = '', server: str = 'https://www.openml.org/api/v1/xml', cachedir: Path = _resolve_default_cache_dir(), avoid_duplicate_runs: bool = False, retry_policy: Literal['human', 'robot'] = 'human', connection_n_retries: int = 5, show_progress: bool = False)

Dataclass storing the OpenML configuration.

OpenMLConfigManager

OpenMLConfigManager()

The OpenMLConfigManager manages the configuration of the openml-python package.

Source code in openml/_config.py

def __init__(self) -> None:
    self.console_handler: logging.StreamHandler | None = None
    self.file_handler: logging.handlers.RotatingFileHandler | None = None

    self.OPENML_CACHE_DIR_ENV_VAR = "OPENML_CACHE_DIR"
    self.OPENML_SKIP_PARQUET_ENV_VAR = "OPENML_SKIP_PARQUET"
    self._TEST_SERVER_NORMAL_USER_KEY = "normaluser"
    self.OPENML_TEST_SERVER_ADMIN_KEY_ENV_VAR = "OPENML_TEST_SERVER_ADMIN_KEY"
    self.TEST_SERVER_URL = "https://test.openml.org"

    self._config: OpenMLConfig = OpenMLConfig()
    # for legacy test `test_non_writable_home`
    self._defaults: dict[str, Any] = OpenMLConfig().__dict__.copy()
    self._root_cache_directory: Path = self._config.cachedir

    self.logger = logger
    self.openml_logger = openml_logger

    self._examples = ConfigurationForExamples(self)

    self._setup()

determine_config_file_path

determine_config_file_path() -> Path

Determine the path to the openml configuration file.

Source code in openml/_config.py

def determine_config_file_path(self) -> Path:
    """Determine the path to the openml configuration file."""
    if platform.system().lower() == "linux":
        xdg_home = os.environ.get("XDG_CONFIG_HOME")
        if xdg_home is not None:
            config_dir = self._handle_xdg_config_home_backwards_compatibility(xdg_home)
        else:
            config_dir = Path("~", ".config", "openml")
    else:
        config_dir = Path("~") / ".openml"

    config_dir = Path(config_dir).expanduser().resolve()
    return config_dir / "config"

get_cache_directory

get_cache_directory() -> str

Get the cache directory for the current server.

Source code in openml/_config.py

def get_cache_directory(self) -> str:
    """Get the cache directory for the current server."""
    url_suffix = urlparse(self._config.server).netloc
    url_parts = url_suffix.replace(":", "_").split(".")[::-1]
    reversed_url_suffix = os.sep.join(url_parts)  # noqa: PTH118
    return os.path.join(self._root_cache_directory, reversed_url_suffix)  # noqa: PTH118

get_config_as_dict

get_config_as_dict() -> dict[str, Any]

Get the current configuration as a dictionary.

Source code in openml/_config.py

def get_config_as_dict(self) -> dict[str, Any]:
    """Get the current configuration as a dictionary."""
    return self._config.__dict__.copy()

get_server_base_url

get_server_base_url() -> str

Get the base URL of the OpenML server (i.e., without /api).

Source code in openml/_config.py

def get_server_base_url(self) -> str:
    """Get the base URL of the OpenML server (i.e., without /api)."""
    domain, _ = self._config.server.split("/api", maxsplit=1)
    return domain.replace("api", "www")

overwrite_config_context

overwrite_config_context(config: dict[str, Any]) -> Iterator[dict[str, Any]]

Overwrite the current configuration within a context manager.

Source code in openml/_config.py

@contextmanager
def overwrite_config_context(self, config: dict[str, Any]) -> Iterator[dict[str, Any]]:
    """Overwrite the current configuration within a context manager."""
    existing_config = self.get_config_as_dict()
    merged_config = {**existing_config, **config}

    self._setup(merged_config)
    yield merged_config
    self._setup(existing_config)

set_console_log_level

set_console_log_level(console_output_level: int) -> None

Set the log level for console output.

Source code in openml/_config.py

def set_console_log_level(self, console_output_level: int) -> None:
    """Set the log level for console output."""
    assert self.console_handler is not None
    self._set_level_register_and_store(self.console_handler, console_output_level)

set_field_in_config_file

set_field_in_config_file(field: str, value: Any) -> None

Set a field in the configuration file.

Source code in openml/_config.py

def set_field_in_config_file(self, field: str, value: Any) -> None:
    """Set a field in the configuration file."""
    if not hasattr(OpenMLConfig(), field):
        raise ValueError(
            f"Field '{field}' is not valid and must be one of "
            f"'{OpenMLConfig().__dict__.keys()}'."
        )

    self._config = replace(self._config, **{field: value})
    config_file = self.determine_config_file_path()
    existing = self._parse_config(config_file)
    with config_file.open("w") as fh:
        for f in OpenMLConfig().__dict__:
            v = value if f == field else existing.get(f)
            if v is not None:
                fh.write(f"{f} = {v}\n")

set_file_log_level

set_file_log_level(file_output_level: int) -> None

Set the log level for file output.

Source code in openml/_config.py

def set_file_log_level(self, file_output_level: int) -> None:
    """Set the log level for file output."""
    assert self.file_handler is not None
    self._set_level_register_and_store(self.file_handler, file_output_level)

set_retry_policy

set_retry_policy(value: Literal['human', 'robot'], n_retries: int | None = None) -> None

Set the retry policy for server connections.

Source code in openml/_config.py

def set_retry_policy(
    self, value: Literal["human", "robot"], n_retries: int | None = None
) -> None:
    """Set the retry policy for server connections."""
    default_retries_by_policy = {"human": 5, "robot": 50}

    if value not in default_retries_by_policy:
        raise ValueError(
            f"Detected retry_policy '{value}' but must be one of "
            f"{list(default_retries_by_policy.keys())}",
        )
    if n_retries is not None and not isinstance(n_retries, int):
        raise TypeError(
            f"`n_retries` must be of type `int` or `None` but is `{type(n_retries)}`."
        )

    if isinstance(n_retries, int) and n_retries < 1:
        raise ValueError(f"`n_retries` is '{n_retries}' but must be positive.")

    self._config = replace(
        self._config,
        retry_policy=value,
        connection_n_retries=(
            default_retries_by_policy[value] if n_retries is None else n_retries
        ),
    )

set_root_cache_directory

set_root_cache_directory(root_cache_directory: str | Path) -> None

Set the root cache directory.

Source code in openml/_config.py

def set_root_cache_directory(self, root_cache_directory: str | Path) -> None:
    """Set the root cache directory."""
    self._root_cache_directory = Path(root_cache_directory)
    self._config = replace(self._config, cachedir=self._root_cache_directory)

start_using_configuration_for_example

start_using_configuration_for_example() -> None

Sets the configuration to connect to the test server with valid apikey.

Source code in openml/_config.py

def start_using_configuration_for_example(self) -> None:
    """Sets the configuration to connect to the test server with valid apikey."""
    return self._examples.start_using_configuration_for_example()

stop_using_configuration_for_example

stop_using_configuration_for_example() -> None

Store the configuration as it was before start_use_example_configuration.

Source code in openml/_config.py

def stop_using_configuration_for_example(self) -> None:
    """Store the configuration as it was before `start_use_example_configuration`."""
    return self._examples.stop_using_configuration_for_example()