Metadata-Version: 2.4
Name: xtoml
Version: 1.0.1
Summary: Quick access to TOML files
Author-email: "M.P. van de Weerd" <michael@parcifal.dev>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://scm.parcifal.dev/parcifal/xtoml
Project-URL: Source, https://scm.parcifal.dev/parcifal/xtoml
Project-URL: Issues, https://scm.parcifal.dev/parcifal/xtoml/issues
Project-URL: Releases, https://scm.parcifal.dev/parcifal/xtoml/releases
Keywords: toml,pyproject
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: File Formats
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# xtoml

[![release](https://img.shields.io/gitea/v/release/parcifal/xtoml?gitea_url=https%3A%2F%2Fscm.parcifal.dev&label=latest+release)][release]
[![pypi](https://img.shields.io/pypi/v/xtoml?label=pypi+release)][pypi]
[![develop](https://scm.parcifal.dev/parcifal/xtoml/badges/workflows/push.yml/badge.svg?label=develop&branch=develop)][develop]
[![master](https://scm.parcifal.dev/parcifal/xtoml/badges/workflows/push.yml/badge.svg?label=master&branch=master)][master]
[![gitlab](https://img.shields.io/gitlab/last-commit/parcifal%2Fxtoml?label=gitlab+mirror)][gitlab]
[![github](https://img.shields.io/github/last-commit/parcifal%2Fxtoml?label=github+mirror)][github]

![xtoml Logo](https://scm.parcifal.dev/parcifal/xtoml/raw/branch/master/assets/xtoml.png)

Quick access to values in TOML files, from the command line or from Python.

> Licensed under [GPL-3.0-only][license].

## Installation

```sh
pip install xtoml
```

## Command line

```sh
xtoml [-h] [-f FILE] [-s SEPARATOR] [-F FALLBACK] PATH
```

`PATH` is a key path into the TOML document, such as `project.version`. By 
default, it is read from `pyproject.toml` in the current directory.

```sh
$ xtoml project.version
1.0.0

$ xtoml -f config.toml server.port
8080

$ xtoml -s / tool/setuptools/packages/find/include
["xtoml"]

$ xtoml -F 0.0.0 tool.missing.key
0.0.0
```

| Option              | Description                                     |
|---------------------|-------------------------------------------------|
| `-f`, `--file`      | TOML file to read (default: `pyproject.toml`)   |
| `-s`, `--separator` | Separator between keys in `PATH` (default: `.`) |
| `-F`, `--fallback`  | Value to print if `PATH` is not found           |
| `-V`, `--version`   | Show the version and exit                       |

## Python

```python
from xtoml import get

version = get("project.version")
port = get("server.port", file="config.toml", fallback=8080)
```

`get()` raises `KeyError` if the path is not found and no `fallback` is given, 
and `FileNotFoundError` if the file does not exist.

[license]: https://scm.parcifal.dev/parcifal/xtoml/src/branch/master/LICENSE


[release]: https://scm.parcifal.dev/parcifal/xtoml/releases/latest
[pypi]: https://pypi.org/project/xtoml/
[gitlab]: https://gitlab.com/parcifal/xtoml
[github]: https://github.com/parcifal/xtoml
[develop]: https://scm.parcifal.dev/parcifal/xtoml/src/branch/develop
[master]: https://scm.parcifal.dev/parcifal/xtoml/src/branch/master
