XDG Base Directory Specification helpers.

See the XDG Base Directory Specification for more information.


xdg_cache_home, xdg_config_home, xdg_data_home, and xdg_state_home return pathlib.Path objects containing the value of the environment variable named XDG_CACHE_HOME, XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_STATE_HOME respectively, or the default defined in the specification if the environment variable is unset, empty, or contains a relative path rather than absolute path.

xdg_config_dirs and xdg_data_dirs return a list of pathlib.Path objects containing the value, split on colons, of the environment variable named XDG_CONFIG_DIRS and XDG_DATA_DIRS respectively, or the default defined in the specification if the environment variable is unset or empty. Relative paths are ignored, as per the specification.

xdg_runtime_dir returns a pathlib.Path object containing the value of the XDG_RUNTIME_DIR environment variable, or None if the environment variable is not set, or contains a relative path rather than absolute path.


We’ll start by defining a context manager that temporarily sets an environment variable to demonstrate the behaviour of each helper function:

from contextlib import contextmanager
def env(variable, value):
    old = os.environ.get(variable, None)
        os.environ[variable] = value
        if old is None: del os.environ[variable]
        else: os.environ[variable] = old


 xdg_cache_home ()

Path corresponding to XDG_CACHE_HOME

from fastcore.test import *
test_eq(xdg_cache_home(), Path.home()/'.cache')
with env('XDG_CACHE_HOME', '/home/fastai/.cache'):
    test_eq(xdg_cache_home(), Path('/home/fastai/.cache'))


 xdg_config_dirs ()

Paths corresponding to XDG_CONFIG_DIRS

test_eq(xdg_config_dirs(), [Path('/etc/xdg')])
with env('XDG_CONFIG_DIRS', '/home/fastai/.xdg:/home/fastai/.config'):
    test_eq(xdg_config_dirs(), [Path('/home/fastai/.xdg'), Path('/home/fastai/.config')])


 xdg_config_home ()

Path corresponding to XDG_CONFIG_HOME

test_eq(xdg_config_home(), Path.home()/'.config')
with env('XDG_CONFIG_HOME', '/home/fastai/.config'):
    test_eq(xdg_config_home(), Path('/home/fastai/.config'))


 xdg_data_dirs ()

Paths corresponding to XDG_DATA_DIRS`

test_eq(xdg_data_dirs(), [Path('/usr/local/share'), Path('/usr/share')])
with env('XDG_DATA_DIRS', '/home/fastai/.xdg:/home/fastai/.data'):
    test_eq(xdg_data_dirs(), [Path('/home/fastai/.xdg'), Path('/home/fastai/.data')])


 xdg_data_home ()

Path corresponding to XDG_DATA_HOME

test_eq(xdg_data_home(), Path.home()/'.local/share')
with env('XDG_DATA_HOME', '/home/fastai/.data'):
    test_eq(xdg_data_home(), Path('/home/fastai/.data'))


 xdg_runtime_dir ()

Path corresponding to XDG_RUNTIME_DIR

assert (xdg_runtime_dir() is None # macos
        or xdg_runtime_dir().parent == Path('/run/user/')) # ubuntu
with env('XDG_RUNTIME_DIR', '/home/fastai/.data'):
    test_eq(xdg_runtime_dir(), Path('/home/fastai/.data'))


 xdg_state_home ()

Path corresponding to XDG_STATE_HOME

test_eq(xdg_state_home(), Path.home()/'.local/state')
with env('XDG_STATE_HOME', '/home/fastai/.state'):
    test_eq(xdg_state_home(), Path('/home/fastai/.state'))

Copyright © 2016-2021 Scott Stevenson

Modifications copyright © 2022 onwards Jeremy Howard