# xdgenvpy
[](https://gitlab.com/deliberist/xdgenvpy/pipelines)
[](https://ci.appveyor.com/project/rbprogrammer/xdgenvpy-uuvxv)
[](https://codecov.io/gl/deliberist/xdgenvpy)
[](https://pypi.org/project/xdgenvpy)
`xdgenvpy` is yet another Python utility for the
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
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.
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 xdgenvpy 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
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?
```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` 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](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
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:
```bash
pip3 install --user xdgenvpy
```
## A Word About Windows
The
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
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.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/deliberist/xdgenvpy",
"name": "xdgenvpy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Mike Durso",
"author_email": "rbprogrammer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1e/3d/700b94ffa97b3669b83dbc38833191433a560a982d831a2801873ca38065/xdgenvpy-3.0.0.tar.gz",
"platform": null,
"description": "# xdgenvpy\n\n[](https://gitlab.com/deliberist/xdgenvpy/pipelines)\n[](https://ci.appveyor.com/project/rbprogrammer/xdgenvpy-uuvxv)\n[](https://codecov.io/gl/deliberist/xdgenvpy)\n[](https://pypi.org/project/xdgenvpy)\n\n`xdgenvpy` is yet another Python utility for the\n[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),\nbut one that provides Pythonic access as well as a CLI utility. `xdgenvpy`\nadheres to the XDG Base Directory spec on Unix systems, and also provides\nsimilar for Windows-based systems.\n\n## How to use\n\n### Python\n\nThere are three main ways to use xdgenvpy as a Python package,\n\n1. Retrieve XDG environment variables, or the specification defaults.\n1. Determine _package_ specific directories based on the XDG spec.\n1. Or pedantically create _package_ specific directories before attempting to\n use the directory.\n\nTo use xdgenvpy as a simple XDG base directory getter, simply create a new\n`xdgenvpy.XDG` object and use the properties it exposes.\n\n```python\nfrom xdgenvpy import XDG\nxdg = XDG()\nprint(xdg.XDG_DATA_HOME) # /home/user/.local/share\nprint(xdg.XDG_CONFIG_HOME) # /home/user/.config\nprint(xdg.XDG_CACHE_HOME) # /home/user/.cache\nprint(xdg.XDG_RUNTIME_DIR) # /run/user/1000\nprint(xdg.XDG_DATA_DIRS) # /home/user/.local/share:/usr/local/share/:/usr/share/\nprint(xdg.XDG_CONFIG_DIRS) # /home/user/.config:/etc/xdg\n```\n\nBut sometimes you want to use package specific directories derived from the XDG\nbase directories. This can be done with the `xdgenvpy.XDGPackage` class.\n\n```python\nfrom xdgenvpy import XDGPackage\nxdg = XDGPackage('mypackage')\nprint(xdg.XDG_DATA_HOME) # /home/user/.local/share/mypackage\nprint(xdg.XDG_CONFIG_HOME) # /home/user/.config/mypackage\nprint(xdg.XDG_CACHE_HOME) # /home/user/.cache/mypackage\nprint(xdg.XDG_RUNTIME_DIR) # /run/user/1000/mypackage\nprint(xdg.XDG_DATA_DIRS) # /home/user/.local/share/mypackage:/usr/local/share/:/usr/share/\nprint(xdg.XDG_CONFIG_DIRS) # /home/user/.config/mypackage:/etc/xdg')\n```\n\nLastly, you could also use `xdgenvpy.XDGPedanticPackage` to ensure each of the\npackage specific directories exist before the calling code attempts to use the\ndirectory. Instances of the `xdgenvpy.XDGPedanticPackage` class will not create\nsystem level directories, only package directories on the DATA, CONFIG, CACHE,\nand RUNTIME variables.\n\n```python\nfrom xdgenvpy import XDGPedanticPackage\nxdg = XDGPedanticPackage('mypackage')\nprint(xdg.XDG_DATA_HOME) # /home/user/.local/share/mypackage\nprint(xdg.XDG_CONFIG_HOME) # /home/user/.config/mypackage\nprint(xdg.XDG_CACHE_HOME) # /home/user/.cache/mypackage\nprint(xdg.XDG_RUNTIME_DIR) # /run/user/1000/mypackage\nprint(xdg.XDG_DATA_DIRS) # /home/user/.local/share/mypackage:/usr/local/share/:/usr/share/\nprint(xdg.XDG_CONFIG_DIRS) # /home/user/.config/mypackage:/etc/xdg\n```\n\n### CLI\n\nxdgenvpy also includes a runnable module, which is easily accessible via the\nscript `xdg-env`. Pip will normally install scripts under something like:\n`~/.local/bin`\n\nThe installed `xdg-env` command essentially takes a list of XDG variables, and\nan optional package name. For each XDG variable specified, `xdg-env` will\nprint its corresponding value based on the specification. It can optionally\ntake the name of a package and include that into the variable's values.\n\nBut can't we just `echo` the XDG variables like so?\n\n```bash\necho ${XDG_DATA_HOME}\necho ${XDG_CONFIG_HOME}\necho ${XDG_CACHE_HOME}\necho ${XDG_RUNTIME_DIR}\necho ${XDG_DATA_DIRS}\necho ${XDG_CONFIG_DIRS}\n```\n\nWell, yes. But there is a problem when the variables are not defined. The\n`xdg-env` command will _always_ print a value that adheres to the spec. If the\nenvironment variable does not exist, then the default value will be returned, as\ndefined by the\n[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).\n\nAlthough the Python package supports a _pedantic_ mode, the `xdg-env` command\nwill not change the file system. Even if a package name is supplied and the\ndirectories do not exist, `xdg-env` will not create any files/directories. This\nwas simply a design decision to keep the shell command as file-system safe as\npossible.\n\n## How to install\n\nInstall locally as a normal user:\n\n```bash\npip3 install --user xdgenvpy\n```\n\n## A Word About Windows\n\nThe\n[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).\ndoes not mention how the spec should be implemented on Windows-based platforms.\nThat said, many applications on Windows still follow a very similar convention\nto the XDG base directory spec. And that is to generally place config files\nunder `%APPDATA%/MyPackage/configs`.\n\nIf we squint, it kind of looks like we can simply replace the POSIX tilde `~`\nwith the Windows `%APPDATA%` variable. Then there's a directory that is the\napplication's name. And finally, any configs or data files the application\nneeds to save is under that directory.\n\nGenerally, xdgenvpy works in this way on Windows-based platforms. Though this\nis not a perfect solution as Windows applications can put configs and data files\nunder any of the directories `Local`, `LocalLow`, and `Roaming` (where the\n`Roaming` directory typically is pointed to by `%APPDATA%`). Additionally, some\nXDG variables do not make much sense on Windows-based platforms.\n`XDG_RUNTIME_DIR` is one such example. On Unix systems it defaults to\n`/run/user/USERID`. There is no close equivalent to a Windows-based directory.\nAs such, xdgenvpy does not do anything fancy other than prepend `%APPDATA%` to\nmost directories and drop any `.` prefixes for hidden directories/files.\n\nThat said, if you use xdgenvpy extensively on Windows platforms and would like\nbetter support, create GitLab issues on the project or submit Merge Requests.\nLet's all make xdgenvpy as useful as possible, even if it needs to implement XDG\nbase directory spec-like features on non-Unix platforms.\n",
"bugtrack_url": null,
"license": null,
"summary": "Another XDG Base Directory Specification utility.",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://gitlab.com/deliberist/xdgenvpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "68ddecf934e832eb4eff314aaefb0d2dc29f1de76918f68670c63179f220db82",
"md5": "b07928a7c836aa2b7c2376e7e467cbf5",
"sha256": "2d4991f380cab1288e62a47e19fc7bc1490ea82b4e796989695ceb2c5f702f51"
},
"downloads": -1,
"filename": "xdgenvpy-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b07928a7c836aa2b7c2376e7e467cbf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16918,
"upload_time": "2024-09-15T21:46:04",
"upload_time_iso_8601": "2024-09-15T21:46:04.890798Z",
"url": "https://files.pythonhosted.org/packages/68/dd/ecf934e832eb4eff314aaefb0d2dc29f1de76918f68670c63179f220db82/xdgenvpy-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1e3d700b94ffa97b3669b83dbc38833191433a560a982d831a2801873ca38065",
"md5": "22d42f6399c51a341462a751fcfc99e7",
"sha256": "c03ff979fa8002618d1e4f777bd62797d629e0dc599cf23d4dc6f536c64bc340"
},
"downloads": -1,
"filename": "xdgenvpy-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "22d42f6399c51a341462a751fcfc99e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21286,
"upload_time": "2024-09-15T21:46:06",
"upload_time_iso_8601": "2024-09-15T21:46:06.376254Z",
"url": "https://files.pythonhosted.org/packages/1e/3d/700b94ffa97b3669b83dbc38833191433a560a982d831a2801873ca38065/xdgenvpy-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-15 21:46:06",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "deliberist",
"gitlab_project": "xdgenvpy",
"lcname": "xdgenvpy"
}
JSON