| Name | argtoml JSON |
| Version |
0.5.7
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 | 2024-06-19 14:20:08 |
| 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/f2/fb/505f6d8e0fa6d135a468c5ae02ccd50e69779c2b43a2758ace570c4e49f2/argtoml-0.5.7.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.7",
"project_urls": {
"homepage": "https://github.com/JJJHolscher/argtoml"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "776bc4f0c2fb51640eb035a502520dc0b0403b02c14b8ea2f448f62aae33a34e",
"md5": "8e366cde5d8c467df7ebdd4ca2116d79",
"sha256": "0fe45f54854d07451ce82cadbd3062cba238fe7c0d8a18d5d7eea1fc4ae53919"
},
"downloads": -1,
"filename": "argtoml-0.5.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e366cde5d8c467df7ebdd4ca2116d79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 12882,
"upload_time": "2024-06-19T14:19:45",
"upload_time_iso_8601": "2024-06-19T14:19:45.416822Z",
"url": "https://files.pythonhosted.org/packages/77/6b/c4f0c2fb51640eb035a502520dc0b0403b02c14b8ea2f448f62aae33a34e/argtoml-0.5.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2fb505f6d8e0fa6d135a468c5ae02ccd50e69779c2b43a2758ace570c4e49f2",
"md5": "87992540e503fae506844f70e2407a62",
"sha256": "b621ad785fc6274d245cd548ae323110fc2a69f642ae4c79c56e7f02361f95a6"
},
"downloads": -1,
"filename": "argtoml-0.5.7.tar.gz",
"has_sig": false,
"md5_digest": "87992540e503fae506844f70e2407a62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 12296,
"upload_time": "2024-06-19T14:20:08",
"upload_time_iso_8601": "2024-06-19T14:20:08.173785Z",
"url": "https://files.pythonhosted.org/packages/f2/fb/505f6d8e0fa6d135a468c5ae02ccd50e69779c2b43a2758ace570c4e49f2/argtoml-0.5.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-19 14:20:08",
"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"
}
