Skip to main content

Another XDG Base Directory Specification utility.

Project description

xdgenvpy

pipeline Build status codecov pypi

xdgenvpy is yet another Python utility for the XDG Base Directory Specification, but one that provides Pythonic access as well as a CLI utility. xdgenvpy adheres to the XDG Base Directory spec on Unix systems, and also provides similar for Windows-based systems.

How to use

Python

There are three main ways to use xdgenvpy as a Python package,

  1. Retrieve XDG environment variables, or the specification defaults.
  2. Determine package specific directories based on the XDG spec.
  3. Or pedantically create package specific directories before attempting to use the directory.

To use xdgenvpy as a simple XDG base directory getter, simply create a new xdgenvpy.XDG object and use the properties it exposes.

from xdgenvpy import XDG
xdg = XDG()
print(xdg.XDG_DATA_HOME)        # /home/user/.local/share
print(xdg.XDG_CONFIG_HOME)      # /home/user/.config
print(xdg.XDG_CACHE_HOME)       # /home/user/.cache
print(xdg.XDG_RUNTIME_DIR)      # /run/user/1000
print(xdg.XDG_DATA_DIRS)        # /home/user/.local/share:/usr/local/share/:/usr/share/
print(xdg.XDG_CONFIG_DIRS)      # /home/user/.config:/etc/xdg

But sometimes you want to use package specific directories derived from the XDG base directories. This can be done with the xdgenvpy.XDGPackage class.

from xdgenvpy import XDGPackage
xdg = XDGPackage('mypackage')
print(xdg.XDG_DATA_HOME)        # /home/user/.local/share/mypackage
print(xdg.XDG_CONFIG_HOME)      # /home/user/.config/mypackage
print(xdg.XDG_CACHE_HOME)       # /home/user/.cache/mypackage
print(xdg.XDG_RUNTIME_DIR)      # /run/user/1000/mypackage
print(xdg.XDG_DATA_DIRS)        # /home/user/.local/share/mypackage:/usr/local/share/:/usr/share/
print(xdg.XDG_CONFIG_DIRS)      # /home/user/.config/mypackage:/etc/xdg')

Lastly, you could also use xdgenvpy.XDGPedanticPackage to ensure each of the package specific directories exist before the calling code attempts to use the directory. Instances of the xdgenvpy.XDGPedanticPackage class will not create system level directories, only package directories on the DATA, CONFIG, CACHE, and RUNTIME variables.

from xdgenvpy import XDGPedanticPackage
xdg = XDGPedanticPackage('mypackage')
print(xdg.XDG_DATA_HOME)        # /home/user/.local/share/mypackage
print(xdg.XDG_CONFIG_HOME)      # /home/user/.config/mypackage
print(xdg.XDG_CACHE_HOME)       # /home/user/.cache/mypackage
print(xdg.XDG_RUNTIME_DIR)      # /run/user/1000/mypackage
print(xdg.XDG_DATA_DIRS)        # /home/user/.local/share/mypackage:/usr/local/share/:/usr/share/
print(xdg.XDG_CONFIG_DIRS)      # /home/user/.config/mypackage:/etc/xdg

CLI

xdgenvpy also includes a runnable module, which is easily accessible via the script xdg-env. Pip will normally install scripts under something like: ~/.local/bin

The installed xdg-env command essentially takes a list of XDG variables, and an optional package name. For each XDG variable specified, xdg-env will print its corresponding value based on the specification. It can optionally take the name of a package and include that into the variable's values.

But can't we just echo the XDG variables like so?

echo ${XDG_DATA_HOME}
echo ${XDG_CONFIG_HOME}
echo ${XDG_CACHE_HOME}
echo ${XDG_RUNTIME_DIR}
echo ${XDG_DATA_DIRS}
echo ${XDG_CONFIG_DIRS}

Well, yes. But there is a problem when the variables are not defined. The xdg-env command will always print a value that adheres to the spec. If the environment variable does not exist, then the default value will be returned, as defined by the XDG Base Directory Specification.

Although the Python package supports a pedantic mode, the xdg-env command will not change the file system. Even if a package name is supplied and the directories do not exist, xdg-env will not create any files/directories. This was simply a design decision to keep the shell command as file-system safe as possible.

How to install

Install locally as a normal user:

pip3 install --user xdgenvpy

A Word About Windows

The XDG Base Directory Specification. does not mention how the spec should be implemented on Windows-based platforms. That said, many applications on Windows still follow a very similar convention to the XDG base directory spec. And that is to generally place config files under %APPDATA%/MyPackage/configs.

If we squint, it kind of looks like we can simply replace the POSIX tilde ~ with the Windows %APPDATA% variable. Then there's a directory that is the application's name. And finally, any configs or data files the application needs to save is under that directory.

Generally, xdgenvpy works in this way on Windows-based platforms. Though this is not a perfect solution as Windows applications can put configs and data files under any of the directories Local, LocalLow, and Roaming (where the Roaming directory typically is pointed to by %APPDATA%). Additionally, some XDG variables do not make much sense on Windows-based platforms. XDG_RUNTIME_DIR is one such example. On Unix systems it defaults to /run/user/USERID. There is no close equivalent to a Windows-based directory. As such, xdgenvpy does not do anything fancy other than prepend %APPDATA% to most directories and drop any . prefixes for hidden directories/files.

That said, if you use xdgenvpy extensively on Windows platforms and would like better support, create GitLab issues on the project or submit Merge Requests. Let's all make xdgenvpy as useful as possible, even if it needs to implement XDG base directory spec-like features on non-Unix platforms.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xdgenvpy-3.0.0.tar.gz (21.3 kB view details)

Uploaded Source

Built Distribution

xdgenvpy-3.0.0-py3-none-any.whl (16.9 kB view details)

Uploaded Python 3

File details

Details for the file xdgenvpy-3.0.0.tar.gz.

File metadata

  • Download URL: xdgenvpy-3.0.0.tar.gz
  • Upload date:
  • Size: 21.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for xdgenvpy-3.0.0.tar.gz
Algorithm Hash digest
SHA256 c03ff979fa8002618d1e4f777bd62797d629e0dc599cf23d4dc6f536c64bc340
MD5 22d42f6399c51a341462a751fcfc99e7
BLAKE2b-256 1e3d700b94ffa97b3669b83dbc38833191433a560a982d831a2801873ca38065

See more details on using hashes here.

File details

Details for the file xdgenvpy-3.0.0-py3-none-any.whl.

File metadata

  • Download URL: xdgenvpy-3.0.0-py3-none-any.whl
  • Upload date:
  • Size: 16.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.9

File hashes

Hashes for xdgenvpy-3.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2d4991f380cab1288e62a47e19fc7bc1490ea82b4e796989695ceb2c5f702f51
MD5 b07928a7c836aa2b7c2376e7e467cbf5
BLAKE2b-256 68ddecf934e832eb4eff314aaefb0d2dc29f1de76918f68670c63179f220db82

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page