| Name | spanned-toml JSON |
| Version |
2.0.1.1
JSON |
| download |
| home_page | |
| Summary | A lil' TOML parser, but with span |
| upload_time | 2022-12-11 13:38:52 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
toml
spanned
tomli
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/jeertmans/spanned-toml/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)
[](https://codecov.io/gh/jeertmans/spanned-toml)
[](https://pypi.org/project/spanned-toml)
# Spanned-Toml
> A lil' TOML parser, but with span
This project is an extension of
[@hukkin's Tomli](https://github.com/hukkin/tomli) libray, but with span.
A span is simply a Python `slice` that helps to retrieve where a given object
was parsed from.
## Motivation<a name="motivation"></a>
TOML has become a popular format for configuration files, and many tools now
rely on parsing such files. However, most parsers error on invalid TOML syntax,
not configuration specific errors. E.g., what happens with the following file?
```toml
age = -45 # age should be a positive integer
```
First, you parse the TOML file, which is valid, then you invalidate the `age`
value because it is negative. But how to pinpoint the location of where `age`
was defined to the user?
There is where Spanned-Toml comes into play. For every key / value, you can
obtain the span information about where it was define. The span is simple a
Python `slice`, that can be used to index the original TOML string.
**Table of Contents** *generated with [mdformat-toc](https://github.com/hukkin/mdformat-toc)*
<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=2 -->
- [Motivation](#motivation)
- [Intro](#intro)
- [Installation](#installation)
- [Usage](#usage)
- [Why choosing Spanned-Toml over others?](#why-choosing-spanned-toml-over-others)
- [Versions](#versions)
<!-- mdformat-toc end -->
## Intro<a name="intro"></a>
Spanned-Toml is a Python library for parsing [TOML](https://toml.io), with the
**only** addition of span information for every object (both keys and values).
It is fully compatible with [TOML v1.0.0](https://toml.io/en/v1.0.0), and its
goal is to provide span information with minimal overhead over Tomli.
As such, Spanned-Toml provides the same features and API as Tomli, with the only
difference is that it returns a `Spanned[dict]`, instead of `dict`.
If you whish to get the same output as with Tomli, you can always call `.unspan()`
on a `Spanned` object.
## Installation<a name="installation"></a>
```bash
pip install spanned-toml
```
## Usage<a name="usage"></a>
Toml-Spanned has the **exact** same interface as Tomli. Therefore, I recommend
you checking [Tomli's usage](https://github.com/hukkin/tomli#usage).
The only addition is that, instead of returning an object `T`, it returns
`Spanned[T]`, and nested objects are also `Spanned`, i.e., array and dictionnary
values are also spanned.
From `Spanned[T]`, you can always obtain the inner value `T` with `.inner()`:
```python
import spanned_toml as toml
toml_dict = toml.loads("age = 10")
assert toml_dict["age"].inner() == 10
```
> NOTE: for convenience, `Spanned[T]` inherits most attributes from `T`.
If you have nested `Spanned` objects, then you can call `.unspan()` to remove
all span information, and obtain the same object as if you used Tomli.
```python
toml_str = """
[[players]]
name = "Lehtinen"
number = 26
[[players]]
name = "Numminen"
number = 27
"""
toml_dict = toml.loads(toml_str).unspan()
assert toml_dict == {
"players": [{"name": "Lehtinen", "number": 26}, {"name": "Numminen", "number": 27}]
}
```
Last, but not least, you can retrieve the exact part of the string that was used
to parse a given key or value.
```python
player_span = toml_dict["players"][0]["name"].span()
assert toml_str[player_span] == '"Lehtinen"' # Quotes are included in span
```
> NOTE: arrays of tables have an empty span, since then can be defined in
> multiple parts of a given file.
## Why choosing Spanned-Toml over others?<a name="why-choosing-spanned-toml-over-others"></a>
Spanned-Toml was mainly built for another project I am working on.
You should use this package whenever you care about where specific parts in a
TOML config file are coming from. This might be useful, e.g., if you want to
have a validation layer, on top of the default TOML, and that you want to exactly
pinpoint where an error originated.
Otherwise, if you just care about parsing TOML file or speed, then directly use
Tomli (or other faster alternatives).
## Versions<a name="versions"></a>
Toml-Spanned follows the same versions as Tomli, and tries to be in sync with it.
Therefore, Tomli-Spanned's version `X.Y.Z.P` matches Tomli's version `X.Y.Z`.
The `P` number of for patches, and is only intended to fix issues related to span.
Raw data
{
"_id": null,
"home_page": "",
"name": "spanned-toml",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "toml,spanned,tomli",
"author": "",
"author_email": "J\u00e9rome Eertmans <jeertmans@icloud.com>, Taneli Hukkinen <hukkin@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/23/e3/12eb1f49ef10755251cb6037c9da0964feb90cd4f75a3b9021e592e84456/spanned-toml-2.0.1.1.tar.gz",
"platform": null,
"description": "[](https://github.com/jeertmans/spanned-toml/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)\n[](https://codecov.io/gh/jeertmans/spanned-toml)\n[](https://pypi.org/project/spanned-toml)\n\n# Spanned-Toml\n\n> A lil' TOML parser, but with span\n\nThis project is an extension of\n[@hukkin's Tomli](https://github.com/hukkin/tomli) libray, but with span.\n\nA span is simply a Python `slice` that helps to retrieve where a given object\nwas parsed from.\n\n## Motivation<a name=\"motivation\"></a>\n\nTOML has become a popular format for configuration files, and many tools now\nrely on parsing such files. However, most parsers error on invalid TOML syntax,\nnot configuration specific errors. E.g., what happens with the following file?\n\n```toml\nage = -45 # age should be a positive integer\n```\n\nFirst, you parse the TOML file, which is valid, then you invalidate the `age`\nvalue because it is negative. But how to pinpoint the location of where `age`\nwas defined to the user?\n\nThere is where Spanned-Toml comes into play. For every key / value, you can\nobtain the span information about where it was define. The span is simple a\nPython `slice`, that can be used to index the original TOML string.\n\n**Table of Contents** *generated with [mdformat-toc](https://github.com/hukkin/mdformat-toc)*\n\n<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=2 -->\n\n- [Motivation](#motivation)\n- [Intro](#intro)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Why choosing Spanned-Toml over others?](#why-choosing-spanned-toml-over-others)\n- [Versions](#versions)\n\n<!-- mdformat-toc end -->\n\n## Intro<a name=\"intro\"></a>\n\nSpanned-Toml is a Python library for parsing [TOML](https://toml.io), with the\n**only** addition of span information for every object (both keys and values).\nIt is fully compatible with [TOML v1.0.0](https://toml.io/en/v1.0.0), and its\ngoal is to provide span information with minimal overhead over Tomli.\n\nAs such, Spanned-Toml provides the same features and API as Tomli, with the only\ndifference is that it returns a `Spanned[dict]`, instead of `dict`.\n\nIf you whish to get the same output as with Tomli, you can always call `.unspan()`\non a `Spanned` object.\n\n## Installation<a name=\"installation\"></a>\n\n```bash\npip install spanned-toml\n```\n\n## Usage<a name=\"usage\"></a>\n\nToml-Spanned has the **exact** same interface as Tomli. Therefore, I recommend\nyou checking [Tomli's usage](https://github.com/hukkin/tomli#usage).\n\nThe only addition is that, instead of returning an object `T`, it returns\n`Spanned[T]`, and nested objects are also `Spanned`, i.e., array and dictionnary\nvalues are also spanned.\n\nFrom `Spanned[T]`, you can always obtain the inner value `T` with `.inner()`:\n\n```python\nimport spanned_toml as toml\n\ntoml_dict = toml.loads(\"age = 10\")\n\nassert toml_dict[\"age\"].inner() == 10\n```\n\n> NOTE: for convenience, `Spanned[T]` inherits most attributes from `T`.\n\nIf you have nested `Spanned` objects, then you can call `.unspan()` to remove\nall span information, and obtain the same object as if you used Tomli.\n\n```python\ntoml_str = \"\"\"\n[[players]]\nname = \"Lehtinen\"\nnumber = 26\n\n[[players]]\nname = \"Numminen\"\nnumber = 27\n\"\"\"\n\ntoml_dict = toml.loads(toml_str).unspan()\nassert toml_dict == {\n \"players\": [{\"name\": \"Lehtinen\", \"number\": 26}, {\"name\": \"Numminen\", \"number\": 27}]\n}\n```\n\nLast, but not least, you can retrieve the exact part of the string that was used\nto parse a given key or value.\n\n```python\nplayer_span = toml_dict[\"players\"][0][\"name\"].span()\n\nassert toml_str[player_span] == '\"Lehtinen\"' # Quotes are included in span\n```\n\n> NOTE: arrays of tables have an empty span, since then can be defined in\n> multiple parts of a given file.\n\n## Why choosing Spanned-Toml over others?<a name=\"why-choosing-spanned-toml-over-others\"></a>\n\nSpanned-Toml was mainly built for another project I am working on.\n\nYou should use this package whenever you care about where specific parts in a\nTOML config file are coming from. This might be useful, e.g., if you want to\nhave a validation layer, on top of the default TOML, and that you want to exactly\npinpoint where an error originated.\n\nOtherwise, if you just care about parsing TOML file or speed, then directly use\nTomli (or other faster alternatives).\n\n## Versions<a name=\"versions\"></a>\n\nToml-Spanned follows the same versions as Tomli, and tries to be in sync with it.\n\nTherefore, Tomli-Spanned's version `X.Y.Z.P` matches Tomli's version `X.Y.Z`.\nThe `P` number of for patches, and is only intended to fix issues related to span.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A lil' TOML parser, but with span",
"version": "2.0.1.1",
"split_keywords": [
"toml",
"spanned",
"tomli"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "fe7155aa0cddf2d8958f925e6a338d63",
"sha256": "cf962412aad749c840bc65f5d0ee7d720f00d15c2ee720c776af3236a6b0d0b2"
},
"downloads": -1,
"filename": "spanned_toml-2.0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe7155aa0cddf2d8958f925e6a338d63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13408,
"upload_time": "2022-12-11T13:38:50",
"upload_time_iso_8601": "2022-12-11T13:38:50.865055Z",
"url": "https://files.pythonhosted.org/packages/14/26/988a772d03fa5385edc1e3481c69b4e471309fef99928f9a1031ecbe4728/spanned_toml-2.0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "501d905e1f45b09ca1b099c24859df97",
"sha256": "4de893e1ec7a01cb023392affbab040b3da9afb7e4a886fc478ac52ff2158753"
},
"downloads": -1,
"filename": "spanned-toml-2.0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "501d905e1f45b09ca1b099c24859df97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 14957,
"upload_time": "2022-12-11T13:38:52",
"upload_time_iso_8601": "2022-12-11T13:38:52.495998Z",
"url": "https://files.pythonhosted.org/packages/23/e3/12eb1f49ef10755251cb6037c9da0964feb90cd4f75a3b9021e592e84456/spanned-toml-2.0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-11 13:38:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "spanned-toml"
}
