config

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

ConfigurationForExamples

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

Source code in openml/config.py

class ConfigurationForExamples:
    """Allows easy switching to and from a test configuration, used for examples."""

    _last_used_server = None
    _last_used_key = None
    _start_last_called = False
    _test_server = "https://test.openml.org/api/v1/xml"
    _test_apikey = "c0c42819af31e706efe1f4b88c23c6c1"

    @classmethod
    def start_using_configuration_for_example(cls) -> 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.
        """
        global server  # noqa: PLW0603
        global apikey  # noqa: PLW0603

        if cls._start_last_called and server == cls._test_server and apikey == cls._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

        cls._last_used_server = server
        cls._last_used_key = apikey
        cls._start_last_called = True

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

    @classmethod
    def stop_using_configuration_for_example(cls) -> None:
        """Return to configuration as it was before `start_use_example_configuration`."""
        if not cls._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.",
            )

        global server  # noqa: PLW0603
        global apikey  # noqa: PLW0603

        server = cast(str, cls._last_used_server)
        apikey = cast(str, cls._last_used_key)
        cls._start_last_called = False

start_using_configuration_for_example() classmethod

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

@classmethod
def start_using_configuration_for_example(cls) -> 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.
    """
    global server  # noqa: PLW0603
    global apikey  # noqa: PLW0603

    if cls._start_last_called and server == cls._test_server and apikey == cls._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

    cls._last_used_server = server
    cls._last_used_key = apikey
    cls._start_last_called = True

    # Test server key for examples
    server = cls._test_server
    apikey = cls._test_apikey
    warnings.warn(
        f"Switching to the test server {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() classmethod

Return to configuration as it was before start_use_example_configuration.

Source code in openml/config.py

@classmethod
def stop_using_configuration_for_example(cls) -> None:
    """Return to configuration as it was before `start_use_example_configuration`."""
    if not cls._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.",
        )

    global server  # noqa: PLW0603
    global apikey  # noqa: PLW0603

    server = cast(str, cls._last_used_server)
    apikey = cast(str, cls._last_used_key)
    cls._start_last_called = False

get_cache_directory()

Get the current cache directory.

This gets the cache directory for the current server relative to the root cache directory that can be set via set_root_cache_directory(). The cache directory is the root_cache_directory with additional information on which subdirectory to use based on the server name. By default it is root_cache_directory / org / openml / www for the standard OpenML.org server and is defined as root_cache_directory / top-level domain / second-level domain / hostname ```

Returns

cachedir : string The current cache directory.

Source code in openml/config.py

def get_cache_directory() -> str:
    """Get the current cache directory.

    This gets the cache directory for the current server relative
    to the root cache directory that can be set via
    ``set_root_cache_directory()``. The cache directory is the
    ``root_cache_directory`` with additional information on which
    subdirectory to use based on the server name. By default it is
    ``root_cache_directory / org / openml / www`` for the standard
    OpenML.org server and is defined as
    ``root_cache_directory / top-level domain / second-level domain /
    hostname``
    ```

    Returns
    -------
    cachedir : string
        The current cache directory.

    """
    url_suffix = urlparse(server).netloc
    reversed_url_suffix = os.sep.join(url_suffix.split(".")[::-1])  # noqa: PTH118
    return os.path.join(_root_cache_directory, reversed_url_suffix)  # noqa: PTH118

get_server_base_url()

Return the base URL of the currently configured server.

Turns "https://www.openml.org/api/v1/xml" in "https://www.openml.org/"

Returns:

Type	Description
str

Source code in openml/config.py

def get_server_base_url() -> str:
    """Return the base URL of the currently configured server.

    Turns ``"https://www.openml.org/api/v1/xml"`` in ``"https://www.openml.org/"``

    Returns
    -------
    str
    """
    return server.split("/api")[0]

set_console_log_level(console_output_level)

Set console output to the desired level and register it with openml logger if needed.

Source code in openml/config.py

def set_console_log_level(console_output_level: int) -> None:
    """Set console output to the desired level and register it with openml logger if needed."""
    global console_handler  # noqa: PLW0602
    assert console_handler is not None
    _set_level_register_and_store(console_handler, console_output_level)

set_field_in_config_file(field, value)

Overwrites the field in the configuration file with the new value.

Source code in openml/config.py

def set_field_in_config_file(field: str, value: Any) -> None:
    """Overwrites the `field` in the configuration file with the new `value`."""
    if field not in _defaults:
        raise ValueError(f"Field '{field}' is not valid and must be one of '{_defaults.keys()}'.")

    # TODO(eddiebergman): This use of globals has gone too far
    globals()[field] = value
    config_file = determine_config_file_path()
    config = _parse_config(config_file)
    with config_file.open("w") as fh:
        for f in _defaults:
            # We can't blindly set all values based on globals() because when the user
            # sets it through config.FIELD it should not be stored to file.
            # There doesn't seem to be a way to avoid writing defaults to file with configparser,
            # because it is impossible to distinguish from an explicitly set value that matches
            # the default value, to one that was set to its default because it was omitted.
            value = config.get("FAKE_SECTION", f)  # type: ignore
            if f == field:
                value = globals()[f]
            fh.write(f"{f} = {value}\n")

set_file_log_level(file_output_level)

Set file output to the desired level and register it with openml logger if needed.

Source code in openml/config.py

def set_file_log_level(file_output_level: int) -> None:
    """Set file output to the desired level and register it with openml logger if needed."""
    global file_handler  # noqa: PLW0602
    assert file_handler is not None
    _set_level_register_and_store(file_handler, file_output_level)

set_root_cache_directory(root_cache_directory)

Set module-wide base cache directory.

Sets the root cache directory, wherin the cache directories are created to store content from different OpenML servers. For example, by default, cached data for the standard OpenML.org server is stored at root_cache_directory / org / openml / www, and the general pattern is root_cache_directory / top-level domain / second-level domain / hostname.

Parameters:

Name	Type	Description	Default
root_cache_directory	string	Path to use as cache directory.	required

See Also

get_cache_directory

Source code in openml/config.py

def set_root_cache_directory(root_cache_directory: str | Path) -> None:
    """Set module-wide base cache directory.

    Sets the root cache directory, wherin the cache directories are
    created to store content from different OpenML servers. For example,
    by default, cached data for the standard OpenML.org server is stored
    at ``root_cache_directory / org / openml / www``, and the general
    pattern is ``root_cache_directory / top-level domain / second-level
    domain / hostname``.

    Parameters
    ----------
    root_cache_directory : string
         Path to use as cache directory.

    See Also
    --------
    get_cache_directory
    """
    global _root_cache_directory  # noqa: PLW0603
    _root_cache_directory = Path(root_cache_directory)