Metadata-Version: 2.1
Name: xdgenvpy
Version: 1.0.0
Summary: Another XDG Base Directory Specification utility.
Home-page: https://gitlab.com/rbprogrammer/xdgenvpy
Author: Mike Durso
Author-email: rbprogrammer@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown

# xdg-env-py

`xdg-env-py` is yet another Python utility for the 
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).

## How to use

### Python

There are three main ways to use xdg-env-py as a Python package,

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

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

```python
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.

```python
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.

```python
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

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

The `xdg-env-py` command essentially takes a list of XDG variables, and an optional
package name.  For each XDG variable specified, `xdg-env-py` 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?

```bash
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-py` command will *always* return a value.  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-py` command 
will not change the file system.  Even if a package name is supplied and the 
directories do not exist, `xdg-env-py` will not create any files/directories.

## How to install

Install locally as a normal user:
```bash
pip install --user xdgenvpy
```

Or install globally as the all powerful, root:
```bash
sudo pip install xdgenvpy
```


