argtoml


Nameargtoml JSON
Version 0.5.6 PyPI version JSON
download
home_pageNone
SummaryAdd the keys from a .toml file to your CLI as arguments. Their values default to the values in the .toml file.
upload_time2024-06-09 15:12:18
maintainerNone
docs_urlNone
authorNone
requires_python>=3.11
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
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/89/8b/0997d68df237414025281e47298aec08c79be7c96afd6697e99755fb78a2/argtoml-0.5.6.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.6",
    "project_urls": {
        "homepage": "https://github.com/JJJHolscher/argtoml"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c279bf6919a22d267e246b215876c35e9d8337e5e328b8202a60f1664195d570",
                "md5": "70cc4191748440ef367ea3ef6fcad31d",
                "sha256": "870a6212de8fee28540bf6d4d761cda7c3e99819cd4aa1cbd77e8d3cd0bf1334"
            },
            "downloads": -1,
            "filename": "argtoml-0.5.6-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "70cc4191748440ef367ea3ef6fcad31d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 12728,
            "upload_time": "2024-06-09T15:12:17",
            "upload_time_iso_8601": "2024-06-09T15:12:17.297981Z",
            "url": "https://files.pythonhosted.org/packages/c2/79/bf6919a22d267e246b215876c35e9d8337e5e328b8202a60f1664195d570/argtoml-0.5.6-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "898b0997d68df237414025281e47298aec08c79be7c96afd6697e99755fb78a2",
                "md5": "4308241d6a9693b1cc6a985023406cf9",
                "sha256": "df222e0ac792a9dac6faa72127e0ed7c6e3f5870cd9057854479f451c5c76e1d"
            },
            "downloads": -1,
            "filename": "argtoml-0.5.6.tar.gz",
            "has_sig": false,
            "md5_digest": "4308241d6a9693b1cc6a985023406cf9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 12132,
            "upload_time": "2024-06-09T15:12:18",
            "upload_time_iso_8601": "2024-06-09T15:12:18.936136Z",
            "url": "https://files.pythonhosted.org/packages/89/8b/0997d68df237414025281e47298aec08c79be7c96afd6697e99755fb78a2/argtoml-0.5.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-06-09 15:12:18",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "JJJHolscher",
    "github_project": "argtoml",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [],
    "lcname": "argtoml"
}
        
Elapsed time: 0.55531s