man(3)

NAME

xdgenvpy - Python module for accessing XDG Base Directory paths.

SYNOPSIS
    from xdgenvpy import XDG
    from xdgenvpy import XDGPackage
    from xdgenvpy import XDGPedanticPackage

DESCRIPTION

This manual only describes the Python API usage of xdgenvpy. This manual does not describe how to use the CLI options.

xdgenvpy can be used to determine XDG Base Directories as specified by either their environment variable overrides or the defaults as defined by the XDG Base Directory specification from Python code. When xdgenvpy returns values, it first searches for their respective environment variables. If they cannot be found, then xdg-env will revert back to the specification defined default values.

Python API

There are three top level classes that can be used to access the variables, each either properties that mimic the true variable names. The three classes are:

    1) from xdgenvpy import XDG

    2) from xdgenvpy import XDGPackage

    3) from xdgenvpy import XDGPedanticPackage

The first XDG class provides basic access to the variables, strictly as defined by the spec. For example, to access the config home you can access it via:

        from xdgenvpy import XDG
        xdg = XDG()
        print(xdg.XDG_CONFIG_HOME)      # will evaluate to ${HOME}/.config

The second class XDGPackage can be used to get package specific directories. For instance, say your package is named mypkg then you can get the location of the package's config home via:

        from xdgenvpy import XDGPackage
        xdg = XDGPackage()
        print(xdg.XDG_CONFIG_HOME)      # will evaluate to ${HOME}/.config/mypkg

The final, and third class, XDGPedanticPackage is programmatically identical to XDGPackage however it will create any intermediate directories if they do not already exist. This is useful if you want to ensure the full set of directories exist up to your package directory. Particularly if you need to create an initial configuration file, or any other files under package specific XDG Base Directories. To use the pedantic aspect of xdgenvpy, you can use it via:

        from xdgenvpy import XDGPedanticPackage
        xdg = XDGPedanticPackage()
        print(xdg.XDG_CONFIG_HOME)      # will evaluate to ${HOME}/.config/mypkg, but
                                        # recursively creates intermediate directories.

FILES

xdgenvpy does not directly reference directories or files. It does however print the names of directories or files based on the values specified either by the user defined environment variables or the values in the XDG Base Directory specification.

BUGS
For the latest list of known bugs, please refer to the list of open Issues in the code repository's issue tracker. (https://gitlab.com/deliberist/xdgenvpy/-/issues)

HISTORY
A full description of the history is documented in the code repository's CHANGELOG.md. (https://gitlab.com/deliberist/xdgenvpy/-/blob/master/CHANGELOG.md)

AUTHOR
Michael Durso Jr. (rbprogrammer@gmail.com)

SEE ALSO
xdg-env(1), python3(1)

Also refer to the formal XDG Base Directory specification. (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)