# xdg-base-dirs
`xdg-base-dirs` is a Python module that provides functions to return paths to
the directories defined by the [XDG Base Directory Specification][spec], to save
you from duplicating the same snippet of logic in every Python utility you write
that deals with user cache, configuration, or data files. It has no external
dependencies.
`xdg-base-dirs` currently implements version 0.8 of the specification, released
on 8th May 2021.
> [!NOTE]
>
> `xdg-base-dirs` was previously named `xdg`, and was renamed due to an import
> collision with [`PyXDG`](https://pypi.org/project/pyxdg/). If you used `xdg`
> prior to the rename, update by changing the dependency name from `xdg` to
> `xdg-base-dirs` and the import from `xdg` to `xdg_base_dirs`.
## Installation
`xdg-base-dirs` requires Python 3.10 or later. To install the latest release
from [PyPI] with [pip], use:
```bash
python3 -m pip install xdg-base-dirs
```
Alternatively, since `xdg-base-dirs` is only a single file you may prefer to
just copy `src/xdg_base_dirs/__init__.py` from the source distribution into your
project.
## Usage
```python
from xdg_base_dirs import (
xdg_cache_home,
xdg_config_dirs,
xdg_config_home,
xdg_data_dirs,
xdg_data_home,
xdg_runtime_dir,
xdg_state_home,
)
```
`xdg_cache_home()`, `xdg_config_home()`, `xdg_data_home()`, and
`xdg_state_home()` return [`pathlib.Path` objects][path] 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 an absolute path.
## Copyright
Copyright © Scott Stevenson.
`xdg-base-dirs` is distributed under the terms of the [ISC license].
[isc license]: https://opensource.org/licenses/ISC
[path]: https://docs.python.org/3/library/pathlib.html#pathlib.Path
[pip]: https://pip.pypa.io/en/stable/
[pypi]: https://pypi.org/project/xdg-base-dirs/
[spec]:
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
Raw data
{
"_id": null,
"home_page": "https://github.com/srstevenson/xdg-base-dirs",
"name": "xdg-base-dirs",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "xdg, base, directory, specification",
"author": "Scott Stevenson",
"author_email": "scott@stevenson.io",
"download_url": "https://files.pythonhosted.org/packages/bf/d0/bbe05a15347538aaf9fa5b51ac3b97075dfb834931fcb77d81fbdb69e8f6/xdg_base_dirs-6.0.2.tar.gz",
"platform": null,
"description": "# xdg-base-dirs\n\n`xdg-base-dirs` is a Python module that provides functions to return paths to\nthe directories defined by the [XDG Base Directory Specification][spec], to save\nyou from duplicating the same snippet of logic in every Python utility you write\nthat deals with user cache, configuration, or data files. It has no external\ndependencies.\n\n`xdg-base-dirs` currently implements version 0.8 of the specification, released\non 8th May 2021.\n\n> [!NOTE]\n>\n> `xdg-base-dirs` was previously named `xdg`, and was renamed due to an import\n> collision with [`PyXDG`](https://pypi.org/project/pyxdg/). If you used `xdg`\n> prior to the rename, update by changing the dependency name from `xdg` to\n> `xdg-base-dirs` and the import from `xdg` to `xdg_base_dirs`.\n\n## Installation\n\n`xdg-base-dirs` requires Python 3.10 or later. To install the latest release\nfrom [PyPI] with [pip], use:\n\n```bash\npython3 -m pip install xdg-base-dirs\n```\n\nAlternatively, since `xdg-base-dirs` is only a single file you may prefer to\njust copy `src/xdg_base_dirs/__init__.py` from the source distribution into your\nproject.\n\n## Usage\n\n```python\nfrom xdg_base_dirs import (\n xdg_cache_home,\n xdg_config_dirs,\n xdg_config_home,\n xdg_data_dirs,\n xdg_data_home,\n xdg_runtime_dir,\n xdg_state_home,\n)\n```\n\n`xdg_cache_home()`, `xdg_config_home()`, `xdg_data_home()`, and\n`xdg_state_home()` return [`pathlib.Path` objects][path] containing the value of\nthe environment variable named `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`,\n`XDG_DATA_HOME`, and `XDG_STATE_HOME` respectively, or the default defined in\nthe specification if the environment variable is unset, empty, or contains a\nrelative path rather than absolute path.\n\n`xdg_config_dirs()` and `xdg_data_dirs()` return a list of `pathlib.Path`\nobjects containing the value, split on colons, of the environment variable named\n`XDG_CONFIG_DIRS` and `XDG_DATA_DIRS` respectively, or the default defined in\nthe specification if the environment variable is unset or empty. Relative paths\nare ignored, as per the specification.\n\n`xdg_runtime_dir()` returns a `pathlib.Path` object containing the value of the\n`XDG_RUNTIME_DIR` environment variable, or `None` if the environment variable is\nnot set, or contains a relative path rather than an absolute path.\n\n## Copyright\n\nCopyright \u00a9 Scott Stevenson.\n\n`xdg-base-dirs` is distributed under the terms of the [ISC license].\n\n[isc license]: https://opensource.org/licenses/ISC\n[path]: https://docs.python.org/3/library/pathlib.html#pathlib.Path\n[pip]: https://pip.pypa.io/en/stable/\n[pypi]: https://pypi.org/project/xdg-base-dirs/\n[spec]:\n https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Variables defined by the XDG Base Directory Specification",
"version": "6.0.2",
"project_urls": {
"Homepage": "https://github.com/srstevenson/xdg-base-dirs",
"Repository": "https://github.com/srstevenson/xdg-base-dirs"
},
"split_keywords": [
"xdg",
" base",
" directory",
" specification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc03030b47fd46b60fc87af548e57ff59c2ca84b2a1dadbe721bb0ce33896b2e",
"md5": "820a70c0fd112d6b70d974c97511b66f",
"sha256": "3c01d1b758ed4ace150ac960ac0bd13ce4542b9e2cdf01312dcda5012cfebabe"
},
"downloads": -1,
"filename": "xdg_base_dirs-6.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "820a70c0fd112d6b70d974c97511b66f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 4747,
"upload_time": "2024-10-19T14:35:05",
"upload_time_iso_8601": "2024-10-19T14:35:05.931407Z",
"url": "https://files.pythonhosted.org/packages/fc/03/030b47fd46b60fc87af548e57ff59c2ca84b2a1dadbe721bb0ce33896b2e/xdg_base_dirs-6.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bfd0bbe05a15347538aaf9fa5b51ac3b97075dfb834931fcb77d81fbdb69e8f6",
"md5": "765ee006d59cc023b28a36505ebcd9d4",
"sha256": "950504e14d27cf3c9cb37744680a43bf0ac42efefc4ef4acf98dc736cab2bced"
},
"downloads": -1,
"filename": "xdg_base_dirs-6.0.2.tar.gz",
"has_sig": false,
"md5_digest": "765ee006d59cc023b28a36505ebcd9d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 4085,
"upload_time": "2024-10-19T14:35:08",
"upload_time_iso_8601": "2024-10-19T14:35:08.114912Z",
"url": "https://files.pythonhosted.org/packages/bf/d0/bbe05a15347538aaf9fa5b51ac3b97075dfb834931fcb77d81fbdb69e8f6/xdg_base_dirs-6.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-19 14:35:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "srstevenson",
"github_project": "xdg-base-dirs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xdg-base-dirs"
}
JSON
