project-paths
=============
[](https://github.com/eddieantonio/project-paths/actions?query=workflow%3A%22Lint+and+Test%22)
[](https://codecov.io/gh/eddieantonio/project-paths)
[](https://pypi.org/project/project-paths/)
Access file paths from `pyproject.toml`
> Thanks to [@Madoshakalaka](https://github.com/madoshakalaka) for the idea!
```toml
# pyproject.toml
[tool.project-paths]
readme = "README.md"
```
```python
# app.py
from project_paths import paths
# paths.readme is a pathlib.Path object:
print(paths.readme.read_text())
```
Install
-------
pip install project-paths
Usage
-----
Does your application have a bunch of configurable file paths? Do you
wish you just had one place to configure list them all?
### Add paths to `[tool.project-paths]`
With this module, define your paths in your `pyproject.toml` file under
the `[tool.project-paths]` table:
```toml
[tool.project-paths]
docs = "path/to/my/docs"
settings = "path/to/my/settings.py"
config = "/opt/path/to/my/config
# Add as many paths as you want!
```
Anything string defined with `[tool.project-paths]` will be made
available. Relative paths are relative to `pyproject.toml`.
### Access paths using `project_paths.paths.<path name>`
Now you can access all the paths listed in `pyproject.toml` with
`project_paths.paths`. Every path is returned as
a [`pathlib.Path`][pathlib] object:
```python
from project_paths import paths
print(paths.docs.glob("*.md"))
assert paths.config.exists()
exec(paths.settings.read_text())
# Or anything you want!
```
### Access your project root directory using `project_root`
You can access the project root directory (assumed to be the directory
that contains `pyproject.toml`) using `project_root`, which acts like
a `pathlib.Path` object:
```python
from project_paths import project_root
assert project_root.is_dir()
assert (project_root / "pyproject.toml").is_file()
print((project_root / "README.md").read_text())
```
> **Note**: `project_root` is not a true `Path` object. Use
> `Path(project_root)` to obtain a true `Path` object.
### Caveats
Names in `[tool.project-paths]` should be a valid Python identifier
and the names **cannot** have a leading underscore. If a name has
a leading underscore, a warning is issued and the name is inaccessible:
```toml
[tool.project-paths]
# BAD: paths that start with a '_' cannot be used
_my_path = "path/to/wherever"
# GOOD: path is a valid Python identifier!
my_path = "path/to/wherever"
```
[pathlib]: https://docs.python.org/3/library/pathlib.html
[tool-table]: https://www.python.org/dev/peps/pep-0518/#tool-table
### Errors
All intentional errors inherit from `project_paths.ProjectPathError`.
#### `PyProjectNotFoundError`
Raised when `project_paths` cannot find an appropriate `pyproject.toml`
for the caller. This can happen if the caller simply does not have
a `pyproject.toml` file, or when it's not possible to determine the
caller's filename.
> **NOTE**: if accessing paths from the interactive console,
> `project_paths` will find the appropriate `pyproject.toml` relative to
> the current working directory!
#### `ConfigurationNotFoundError`
Raised when `project_paths` cannot find the `[tool.project-paths]` table
within the `pyproject.toml` file. Perhaps there is a typo or perhaps the
`project_paths` inferred the incorrect module path.
License
-------
2021 © Eddie Antonio Santos. MIT Licensed.
Raw data
{
"_id": null,
"home_page": "https://github.com/eddieantonio/project-paths",
"name": "project-paths",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "pathlib,pyproject.toml,paths,configuration",
"author": "Eddie Antonio Santos",
"author_email": "eddieantonio@hey.com",
"download_url": "https://files.pythonhosted.org/packages/c7/08/53040f2005ce8dd4229018b4026d3a0de0636d8745f32e67ace1e3a19998/project-paths-1.1.1.tar.gz",
"platform": "",
"description": "project-paths\n=============\n\n[](https://github.com/eddieantonio/project-paths/actions?query=workflow%3A%22Lint+and+Test%22)\n[](https://codecov.io/gh/eddieantonio/project-paths)\n[](https://pypi.org/project/project-paths/)\n\nAccess file paths from `pyproject.toml`\n\n> Thanks to [@Madoshakalaka](https://github.com/madoshakalaka) for the idea!\n\n```toml\n# pyproject.toml\n[tool.project-paths]\nreadme = \"README.md\"\n```\n\n```python\n# app.py\nfrom project_paths import paths\n\n# paths.readme is a pathlib.Path object:\nprint(paths.readme.read_text())\n```\n\nInstall\n-------\n\n pip install project-paths\n\n\nUsage\n-----\n\nDoes your application have a bunch of configurable file paths? Do you\nwish you just had one place to configure list them all?\n\n### Add paths to `[tool.project-paths]`\n\nWith this module, define your paths in your `pyproject.toml` file under\nthe `[tool.project-paths]` table:\n\n```toml\n[tool.project-paths]\ndocs = \"path/to/my/docs\"\nsettings = \"path/to/my/settings.py\"\nconfig = \"/opt/path/to/my/config\n# Add as many paths as you want!\n```\n\nAnything string defined with `[tool.project-paths]` will be made\navailable. Relative paths are relative to `pyproject.toml`.\n\n### Access paths using `project_paths.paths.<path name>`\n\nNow you can access all the paths listed in `pyproject.toml` with\n`project_paths.paths`. Every path is returned as\na [`pathlib.Path`][pathlib] object:\n\n```python\nfrom project_paths import paths\n\nprint(paths.docs.glob(\"*.md\"))\nassert paths.config.exists()\nexec(paths.settings.read_text())\n# Or anything you want!\n```\n\n### Access your project root directory using `project_root`\n\nYou can access the project root directory (assumed to be the directory\nthat contains `pyproject.toml`) using `project_root`, which acts like\na `pathlib.Path` object:\n\n```python\nfrom project_paths import project_root\n\nassert project_root.is_dir()\nassert (project_root / \"pyproject.toml\").is_file()\nprint((project_root / \"README.md\").read_text())\n```\n\n> **Note**: `project_root` is not a true `Path` object. Use\n> `Path(project_root)` to obtain a true `Path` object.\n\n\n### Caveats\n\nNames in `[tool.project-paths]` should be a valid Python identifier\nand the names **cannot** have a leading underscore. If a name has\na leading underscore, a warning is issued and the name is inaccessible:\n\n```toml\n[tool.project-paths]\n# BAD: paths that start with a '_' cannot be used\n_my_path = \"path/to/wherever\"\n# GOOD: path is a valid Python identifier!\nmy_path = \"path/to/wherever\"\n```\n\n[pathlib]: https://docs.python.org/3/library/pathlib.html\n[tool-table]: https://www.python.org/dev/peps/pep-0518/#tool-table\n\n\n### Errors\n\nAll intentional errors inherit from `project_paths.ProjectPathError`.\n\n#### `PyProjectNotFoundError`\n\nRaised when `project_paths` cannot find an appropriate `pyproject.toml`\nfor the caller. This can happen if the caller simply does not have\na `pyproject.toml` file, or when it's not possible to determine the\ncaller's filename.\n\n> **NOTE**: if accessing paths from the interactive console,\n> `project_paths` will find the appropriate `pyproject.toml` relative to\n> the current working directory!\n\n\n#### `ConfigurationNotFoundError`\n\nRaised when `project_paths` cannot find the `[tool.project-paths]` table\nwithin the `pyproject.toml` file. Perhaps there is a typo or perhaps the\n`project_paths` inferred the incorrect module path.\n\n\nLicense\n-------\n\n2021 \u00a9 Eddie Antonio Santos. MIT Licensed.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Access file paths from pyproject.toml",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/eddieantonio/project-paths",
"Repository": "https://github.com/eddieantonio/project-paths"
},
"split_keywords": [
"pathlib",
"pyproject.toml",
"paths",
"configuration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c23191bf70c5f2cdfedf4e23621ac5d6fd4761ccb74f3cae7ba751b9c3a4eda",
"md5": "9fe281a9a6995eae66a3f79c7b51da09",
"sha256": "5e93b759772f47d79f86ad5482c55ef1cc9566de6a4108aab939b6e0e602cf2d"
},
"downloads": -1,
"filename": "project_paths-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9fe281a9a6995eae66a3f79c7b51da09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 6874,
"upload_time": "2021-06-16T19:55:04",
"upload_time_iso_8601": "2021-06-16T19:55:04.254679Z",
"url": "https://files.pythonhosted.org/packages/3c/23/191bf70c5f2cdfedf4e23621ac5d6fd4761ccb74f3cae7ba751b9c3a4eda/project_paths-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c70853040f2005ce8dd4229018b4026d3a0de0636d8745f32e67ace1e3a19998",
"md5": "324a2dd38df05533fc8825af3a795f53",
"sha256": "b040f701fcdd550e7fa6ea85fa8a82ae047da755b4d639a1b278da7c959fdada"
},
"downloads": -1,
"filename": "project-paths-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "324a2dd38df05533fc8825af3a795f53",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 7043,
"upload_time": "2021-06-16T19:55:02",
"upload_time_iso_8601": "2021-06-16T19:55:02.905388Z",
"url": "https://files.pythonhosted.org/packages/c7/08/53040f2005ce8dd4229018b4026d3a0de0636d8745f32e67ace1e3a19998/project-paths-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-06-16 19:55:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eddieantonio",
"github_project": "project-paths",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "project-paths"
}
JSON
