| Name | tomli-w JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | |
| Summary | A lil' TOML writer |
| upload_time | 2021-12-01 23:55:11 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
toml
tomli
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/hukkin/tomli-w/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)
[](https://codecov.io/gh/hukkin/tomli-w)
[](https://pypi.org/project/tomli-w)
# Tomli-W
> A lil' TOML writer
**Table of Contents** *generated with [mdformat-toc](https://github.com/hukkin/mdformat-toc)*
<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=2 -->
- [Intro](#intro)
- [Installation](#installation)
- [Usage](#usage)
- [Write to string](#write-to-string)
- [Write to file](#write-to-file)
- [FAQ](#faq)
- [Does Tomli-W sort the document?](#does-tomli-w-sort-the-document)
- [Does Tomli-W support writing documents with comments or custom whitespace?](#does-tomli-w-support-writing-documents-with-comments-or-custom-whitespace)
- [Why does Tomli-W not write a multi-line string if the string value contains newlines?](#why-does-tomli-w-not-write-a-multi-line-string-if-the-string-value-contains-newlines)
- [Is Tomli-W output guaranteed to be valid TOML?](#is-tomli-w-output-guaranteed-to-be-valid-toml)
<!-- mdformat-toc end -->
## Intro<a name="intro"></a>
Tomli-W is a Python library for writing [TOML](https://toml.io).
It is a write-only counterpart to [Tomli](https://github.com/hukkin/tomli),
which is a read-only TOML parser.
Tomli-W is fully compatible with [TOML v1.0.0](https://toml.io/en/v1.0.0).
## Installation<a name="installation"></a>
```bash
pip install tomli-w
```
## Usage<a name="usage"></a>
### Write to string<a name="write-to-string"></a>
```python
import tomli_w
doc = {"table": {"nested": {}, "val3": 3}, "val2": 2, "val1": 1}
expected_toml = """\
val2 = 2
val1 = 1
[table]
val3 = 3
[table.nested]
"""
assert tomli_w.dumps(doc) == expected_toml
```
### Write to file<a name="write-to-file"></a>
```python
import tomli_w
doc = {"one": 1, "two": 2, "pi": 3}
with open("path_to_file/conf.toml", "wb") as f:
tomli_w.dump(doc, f)
```
## FAQ<a name="faq"></a>
### Does Tomli-W sort the document?<a name="does-tomli-w-sort-the-document"></a>
No, but it respects sort order of the input data,
so one could sort the content of the `dict` (recursively) before calling `tomli_w.dumps`.
### Does Tomli-W support writing documents with comments or custom whitespace?<a name="does-tomli-w-support-writing-documents-with-comments-or-custom-whitespace"></a>
No.
### Why does Tomli-W not write a multi-line string if the string value contains newlines?<a name="why-does-tomli-w-not-write-a-multi-line-string-if-the-string-value-contains-newlines"></a>
This default was chosen to achieve lossless parse/write round-trips.
TOML strings can contain newlines where exact bytes matter, e.g.
```toml
s = "here's a newline\r\n"
```
TOML strings also can contain newlines where exact byte representation is not relevant, e.g.
```toml
s = """here's a newline
"""
```
A parse/write round-trip that converts the former example to the latter does not preserve the original newline byte sequence.
This is why Tomli-W avoids writing multi-line strings.
A keyword argument is provided for users who do not need newline bytes to be preserved:
```python
import tomli_w
doc = {"s": "here's a newline\r\n"}
expected_toml = '''\
s = """
here's a newline
"""
'''
assert tomli_w.dumps(doc, multiline_strings=True) == expected_toml
```
### Is Tomli-W output guaranteed to be valid TOML?<a name="is-tomli-w-output-guaranteed-to-be-valid-toml"></a>
No.
If there's a chance that your input data is bad and you need output validation,
parse the output string once with `tomli.loads`.
If the parse is successful (does not raise `tomli.TOMLDecodeError`) then the string is valid TOML.
Raw data
{
"_id": null,
"home_page": "",
"name": "tomli-w",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "toml,tomli",
"author": "",
"author_email": "Taneli Hukkinen <hukkin@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/49/05/6bf21838623186b91aedbda06248ad18f03487dc56fbc20e4db384abde6c/tomli_w-1.0.0.tar.gz",
"platform": "",
"description": "[](https://github.com/hukkin/tomli-w/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)\n[](https://codecov.io/gh/hukkin/tomli-w)\n[](https://pypi.org/project/tomli-w)\n\n# Tomli-W\n\n> A lil' TOML writer\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- [Intro](#intro)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Write to string](#write-to-string)\n - [Write to file](#write-to-file)\n- [FAQ](#faq)\n - [Does Tomli-W sort the document?](#does-tomli-w-sort-the-document)\n - [Does Tomli-W support writing documents with comments or custom whitespace?](#does-tomli-w-support-writing-documents-with-comments-or-custom-whitespace)\n - [Why does Tomli-W not write a multi-line string if the string value contains newlines?](#why-does-tomli-w-not-write-a-multi-line-string-if-the-string-value-contains-newlines)\n - [Is Tomli-W output guaranteed to be valid TOML?](#is-tomli-w-output-guaranteed-to-be-valid-toml)\n\n<!-- mdformat-toc end -->\n\n## Intro<a name=\"intro\"></a>\n\nTomli-W is a Python library for writing [TOML](https://toml.io).\nIt is a write-only counterpart to [Tomli](https://github.com/hukkin/tomli),\nwhich is a read-only TOML parser.\nTomli-W is fully compatible with [TOML v1.0.0](https://toml.io/en/v1.0.0).\n\n## Installation<a name=\"installation\"></a>\n\n```bash\npip install tomli-w\n```\n\n## Usage<a name=\"usage\"></a>\n\n### Write to string<a name=\"write-to-string\"></a>\n\n```python\nimport tomli_w\n\ndoc = {\"table\": {\"nested\": {}, \"val3\": 3}, \"val2\": 2, \"val1\": 1}\nexpected_toml = \"\"\"\\\nval2 = 2\nval1 = 1\n\n[table]\nval3 = 3\n\n[table.nested]\n\"\"\"\nassert tomli_w.dumps(doc) == expected_toml\n```\n\n### Write to file<a name=\"write-to-file\"></a>\n\n```python\nimport tomli_w\n\ndoc = {\"one\": 1, \"two\": 2, \"pi\": 3}\nwith open(\"path_to_file/conf.toml\", \"wb\") as f:\n tomli_w.dump(doc, f)\n```\n\n## FAQ<a name=\"faq\"></a>\n\n### Does Tomli-W sort the document?<a name=\"does-tomli-w-sort-the-document\"></a>\n\nNo, but it respects sort order of the input data,\nso one could sort the content of the `dict` (recursively) before calling `tomli_w.dumps`.\n\n### Does Tomli-W support writing documents with comments or custom whitespace?<a name=\"does-tomli-w-support-writing-documents-with-comments-or-custom-whitespace\"></a>\n\nNo.\n\n### Why does Tomli-W not write a multi-line string if the string value contains newlines?<a name=\"why-does-tomli-w-not-write-a-multi-line-string-if-the-string-value-contains-newlines\"></a>\n\nThis default was chosen to achieve lossless parse/write round-trips.\n\nTOML strings can contain newlines where exact bytes matter, e.g.\n\n```toml\ns = \"here's a newline\\r\\n\"\n```\n\nTOML strings also can contain newlines where exact byte representation is not relevant, e.g.\n\n```toml\ns = \"\"\"here's a newline\n\"\"\"\n```\n\nA parse/write round-trip that converts the former example to the latter does not preserve the original newline byte sequence.\nThis is why Tomli-W avoids writing multi-line strings.\n\nA keyword argument is provided for users who do not need newline bytes to be preserved:\n\n```python\nimport tomli_w\n\ndoc = {\"s\": \"here's a newline\\r\\n\"}\nexpected_toml = '''\\\ns = \"\"\"\nhere's a newline\n\"\"\"\n'''\nassert tomli_w.dumps(doc, multiline_strings=True) == expected_toml\n```\n\n### Is Tomli-W output guaranteed to be valid TOML?<a name=\"is-tomli-w-output-guaranteed-to-be-valid-toml\"></a>\n\nNo.\nIf there's a chance that your input data is bad and you need output validation,\nparse the output string once with `tomli.loads`.\nIf the parse is successful (does not raise `tomli.TOMLDecodeError`) then the string is valid TOML.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A lil' TOML writer",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/hukkin/tomli-w/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/hukkin/tomli-w"
},
"split_keywords": [
"toml",
"tomli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb011da9c66ecb20f31ed5aa5316a957e0b1a5e786a0d9689616ece4ceaf1321",
"md5": "7c0782596359b7e86959c82200a75bc7",
"sha256": "9f2a07e8be30a0729e533ec968016807069991ae2fd921a78d42f429ae5f4463"
},
"downloads": -1,
"filename": "tomli_w-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c0782596359b7e86959c82200a75bc7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5984,
"upload_time": "2021-12-01T23:55:10",
"upload_time_iso_8601": "2021-12-01T23:55:10.364546Z",
"url": "https://files.pythonhosted.org/packages/bb/01/1da9c66ecb20f31ed5aa5316a957e0b1a5e786a0d9689616ece4ceaf1321/tomli_w-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49056bf21838623186b91aedbda06248ad18f03487dc56fbc20e4db384abde6c",
"md5": "2c050134d4842b449ec4129c97d51e62",
"sha256": "f463434305e0336248cac9c2dc8076b707d8a12d019dd349f5c1e382dd1ae1b9"
},
"downloads": -1,
"filename": "tomli_w-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2c050134d4842b449ec4129c97d51e62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6531,
"upload_time": "2021-12-01T23:55:11",
"upload_time_iso_8601": "2021-12-01T23:55:11.890246Z",
"url": "https://files.pythonhosted.org/packages/49/05/6bf21838623186b91aedbda06248ad18f03487dc56fbc20e4db384abde6c/tomli_w-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-12-01 23:55:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hukkin",
"github_project": "tomli-w",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tomli-w"
}
