In [ ]:

#|hide
#|default_exp xdg

XDG¶

XDG Base Directory Specification helpers.

See the XDG Base Directory Specification for more information.

In [ ]:

#|export
from fastcore.utils import *

Overview¶

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.

Helpers¶

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

In [ ]:

from contextlib import contextmanager

In [ ]:

@contextmanager
def env(variable, value):
    old = os.environ.get(variable, None)
    try:
        os.environ[variable] = value
        yield
    finally:
        if old is None: del os.environ[variable]
        else: os.environ[variable] = old

In [ ]:

#|export
def _path_from_env(variable, default):
    value = os.environ.get(variable)
    if value and os.path.isabs(value): return Path(value)
    return default

In [ ]:

#|export
def _paths_from_env(variable, default):
    value = os.environ.get(variable)
    if value:
        paths = [Path(o) for o in value.split(":") if os.path.isabs(o)]
        if paths: return paths
    return default

In [ ]:

#|export
def xdg_cache_home():
    "Path corresponding to `XDG_CACHE_HOME`"
    return _path_from_env("XDG_CACHE_HOME", Path.home()/".cache")

In [ ]:

from fastcore.test import *

In [ ]:

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'))

In [ ]:

#|export
def xdg_config_dirs():
    "Paths corresponding to `XDG_CONFIG_DIRS`"
    return _paths_from_env("XDG_CONFIG_DIRS", [Path("/etc/xdg")])

In [ ]:

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')])

In [ ]:

#|export
def xdg_config_home():
    "Path corresponding to `XDG_CONFIG_HOME`"
    return _path_from_env("XDG_CONFIG_HOME", Path.home()/".config")

In [ ]:

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'))

In [ ]:

#|export
def xdg_data_dirs():
    "Paths corresponding to XDG_DATA_DIRS`"
    return _paths_from_env( "XDG_DATA_DIRS", [Path(o) for o in "/usr/local/share/:/usr/share/".split(":")])

In [ ]:

#|export
def xdg_data_home():
    "Path corresponding to `XDG_DATA_HOME`"
    return _path_from_env("XDG_DATA_HOME", Path.home()/".local"/"share")

In [ ]:

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'))

In [ ]:

#|export
def xdg_runtime_dir():
    "Path corresponding to `XDG_RUNTIME_DIR`"
    value = os.getenv("XDG_RUNTIME_DIR")
    return Path(value) if value and os.path.isabs(value) else None

In [ ]:

#|export
def xdg_state_home():
    "Path corresponding to `XDG_STATE_HOME`"
    return _path_from_env("XDG_STATE_HOME", Path.home()/".local"/"state")

In [ ]:

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'))

Export -¶

In [ ]:

#|hide
#|eval: false
from nbdev import nbdev_export
nbdev_export()