| Name | argtoml JSON |
| Version |
0.5.9
JSON |
| download |
| home_page | None |
| Summary | Add the keys from a .toml file to your CLI as arguments. Their values default to the values in the .toml file. |
| upload_time | 2025-01-09 12:31:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
build
debugpy
tomli-w
twine
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# README
The `argtoml` package wraps around `argparse`.
It adds the content of a toml file to the cli options.
After parsing, it creates a `types.SimpleNameSpace` object.
## install
Argtoml has no mandatory dependencies outside of pythons standard library.
```sh
pip install argtoml
```
You can optionally install `tomli_w` if you want to save your configuration at runtime.
```sh
pip install 'argtoml[save]'
```
## usage
If there's a `src/config.toml`
```toml
debug = true
home = "~"
[project]
author = "Jono"
name = "argconfig"
pyproject = "./pyproject.toml"
```
and a `src/__main__.py`
```python
from argtoml import parse_args # , ArgumentParser
args = parse_args(path=True)
print(args.debug)
print(args.home)
print(args.project.author)
print(args.project.name)
print(args.project.pyproject)
```
then the shell can look like
```sh
$ pwd
/home/jono/project
$ python src/__main__.py --project.name argtoml --no-debug
False
/home/jono
Jono
argtoml
/home/jono/project/pyproject.toml
```
## documentation
There is none, the code is not that large, but I expect you to only use:
```python
parse_args(
# An argparse parser for adding extra arguments not present in the toml.
parser: Optional[argparse.ArumentParser] = None,
# An extra help message.
description: str = "",
# The location of the toml file.
toml_path: pathlib.Path = Path("config.toml"),
# The dictionary in which to look for the toml file.
toml_dir: Optional[TPath] = None,
# Whether to try to interpret strings as paths.
base_path: Union[Path, bool] = True,
# Whether to look for the toml file in the parent of the toml_dir folder.
grandparent: bool = True
) -> SimpleNamespace
save(args: Union[SimpleNamespace, dict], path: pathlib.Path):
with open(path, "wb") as f:
tomli_w.dump(args, f)
```
## toml file location
You are encouraged to specify the location of the toml file when calling `parse_args` with an absolute path like this:
```python
parse_args(toml_path="/home/user/dir/my_config.toml")
```
If you provide a relative path, `argtoml` will look for `my_config.toml` in the package directory if the main file using `argtoml` is from a package, otherwise `argtoml` will look for `my_config.toml` in the same directory as the main file.
This automatic toml-finding function might change in the future, so probably just provide absolute paths.
### packaging
If you want to ship a toml file with your package, make sure to [add the toml file to your package](https://setuptools.pypa.io/en/latest/userguide/datafiles.html).
You should also call `parse_args` with a relative `toml_path`.
## notes
This is a personal tool thus far, some idiosyncrasies remain:
- Adding dotted arguments not present in the toml might break everything I didn't even test this.
- I don't feel like adding other formats but toml.
- I don't know if, in the above example, the user can do something like `python __main__.py --project {author="jo3"} --project.author jjj`, but it should crash if they do this.
- Interpreting strings as paths _probably_ only works with unix style paths.
## todos
- Add toml comments as argument descriptions.
- Pretty-print the output of parse_args.
- Load and merge multiple toml files
Raw data
{
"_id": null,
"home_page": null,
"name": "argtoml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Jochem H\u00f6lscher <a.fake@e.mail>",
"download_url": "https://files.pythonhosted.org/packages/13/e4/2f190408d6e13a2e3a11b89094338f29f5caa7fb88ca917c5ea8a2f6e50e/argtoml-0.5.9.tar.gz",
"platform": null,
"description": "# README\n\nThe `argtoml` package wraps around `argparse`.\nIt adds the content of a toml file to the cli options.\nAfter parsing, it creates a `types.SimpleNameSpace` object.\n\n## install\n\nArgtoml has no mandatory dependencies outside of pythons standard library.\n```sh\npip install argtoml\n```\nYou can optionally install `tomli_w` if you want to save your configuration at runtime.\n```sh\npip install 'argtoml[save]'\n```\n\n## usage\n\nIf there's a `src/config.toml`\n\n```toml\ndebug = true\nhome = \"~\"\n\n[project]\nauthor = \"Jono\"\nname = \"argconfig\"\npyproject = \"./pyproject.toml\"\n```\n\nand a `src/__main__.py`\n\n```python\nfrom argtoml import parse_args # , ArgumentParser\n\nargs = parse_args(path=True)\nprint(args.debug)\nprint(args.home)\nprint(args.project.author)\nprint(args.project.name)\nprint(args.project.pyproject)\n```\n\nthen the shell can look like\n\n```sh\n$ pwd\n/home/jono/project\n$ python src/__main__.py --project.name argtoml --no-debug\nFalse\n/home/jono\nJono\nargtoml\n/home/jono/project/pyproject.toml\n```\n\n## documentation\n\nThere is none, the code is not that large, but I expect you to only use:\n```python\nparse_args(\n # An argparse parser for adding extra arguments not present in the toml.\n parser: Optional[argparse.ArumentParser] = None,\n # An extra help message.\n description: str = \"\",\n # The location of the toml file.\n toml_path: pathlib.Path = Path(\"config.toml\"),\n # The dictionary in which to look for the toml file.\n toml_dir: Optional[TPath] = None,\n # Whether to try to interpret strings as paths.\n base_path: Union[Path, bool] = True,\n # Whether to look for the toml file in the parent of the toml_dir folder.\n grandparent: bool = True\n) -> SimpleNamespace\n\nsave(args: Union[SimpleNamespace, dict], path: pathlib.Path):\n with open(path, \"wb\") as f:\n tomli_w.dump(args, f)\n```\n\n\n## toml file location\n\nYou are encouraged to specify the location of the toml file when calling `parse_args` with an absolute path like this:\n\n```python\nparse_args(toml_path=\"/home/user/dir/my_config.toml\")\n```\n\nIf you provide a relative path, `argtoml` will look for `my_config.toml` in the package directory if the main file using `argtoml` is from a package, otherwise `argtoml` will look for `my_config.toml` in the same directory as the main file.\nThis automatic toml-finding function might change in the future, so probably just provide absolute paths.\n\n### packaging\n\nIf you want to ship a toml file with your package, make sure to [add the toml file to your package](https://setuptools.pypa.io/en/latest/userguide/datafiles.html).\nYou should also call `parse_args` with a relative `toml_path`.\n\n## notes\n\nThis is a personal tool thus far, some idiosyncrasies remain:\n\n- Adding dotted arguments not present in the toml might break everything I didn't even test this.\n- I don't feel like adding other formats but toml.\n- I don't know if, in the above example, the user can do something like `python __main__.py --project {author=\"jo3\"} --project.author jjj`, but it should crash if they do this.\n- Interpreting strings as paths _probably_ only works with unix style paths.\n\n## todos\n\n- Add toml comments as argument descriptions.\n- Pretty-print the output of parse_args.\n- Load and merge multiple toml files\n",
"bugtrack_url": null,
"license": null,
"summary": "Add the keys from a .toml file to your CLI as arguments. Their values default to the values in the .toml file.",
"version": "0.5.9",
"project_urls": {
"homepage": "https://github.com/JJJHolscher/argtoml"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e72d51db290daa82357731ba187f8646176b6a7b9de0f32c9f654c6c2fb5b491",
"md5": "18e2cdb0e2713e9cd82de23209942d3a",
"sha256": "73056ee51d1298d2614e1992565952e187da1d5952059f180911b17fffe9b8f1"
},
"downloads": -1,
"filename": "argtoml-0.5.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18e2cdb0e2713e9cd82de23209942d3a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 11804,
"upload_time": "2025-01-09T12:31:09",
"upload_time_iso_8601": "2025-01-09T12:31:09.293425Z",
"url": "https://files.pythonhosted.org/packages/e7/2d/51db290daa82357731ba187f8646176b6a7b9de0f32c9f654c6c2fb5b491/argtoml-0.5.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13e42f190408d6e13a2e3a11b89094338f29f5caa7fb88ca917c5ea8a2f6e50e",
"md5": "ec9de54e48b71a6f48cc7c1ad47025b4",
"sha256": "4c9c595ae8901f9c3683f645d94202cefba5c4f71e1dc010b75245ad3ab372f5"
},
"downloads": -1,
"filename": "argtoml-0.5.9.tar.gz",
"has_sig": false,
"md5_digest": "ec9de54e48b71a6f48cc7c1ad47025b4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11901,
"upload_time": "2025-01-09T12:31:11",
"upload_time_iso_8601": "2025-01-09T12:31:11.401971Z",
"url": "https://files.pythonhosted.org/packages/13/e4/2f190408d6e13a2e3a11b89094338f29f5caa7fb88ca917c5ea8a2f6e50e/argtoml-0.5.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-09 12:31:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JJJHolscher",
"github_project": "argtoml",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "build",
"specs": []
},
{
"name": "debugpy",
"specs": []
},
{
"name": "tomli-w",
"specs": []
},
{
"name": "twine",
"specs": []
}
],
"lcname": "argtoml"
}
