tomli-w


Nametomli-w JSON
Version 1.1.0 PyPI version JSON
download
home_pageNone
SummaryA lil' TOML writer
upload_time2024-10-08 11:13:29
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseNone
keywords toml tomli
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            [![Build Status](https://github.com/hukkin/tomli-w/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/hukkin/tomli-w/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)
[![codecov.io](https://codecov.io/gh/hukkin/tomli-w/branch/master/graph/badge.svg)](https://codecov.io/gh/hukkin/tomli-w)
[![PyPI version](https://img.shields.io/pypi/v/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?](#does-tomli-w-support-writing-documents-with-comments)
  - [Can I customize insignificant whitespace?](#can-i-customize-insignificant-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?<a name="does-tomli-w-support-writing-documents-with-comments"></a>

No.

### Can I customize insignificant whitespace?<a name="can-i-customize-insignificant-whitespace"></a>

Indent width of array content can be configured via the `indent` keyword argument.
`indent` takes a non-negative integer, defaulting to 4.

```python
import tomli_w

doc = {"fruits": ["orange", "kiwi", "papaya"]}
expected_toml = """\
fruits = [
 "orange",
 "kiwi",
 "papaya",
]
"""
assert tomli_w.dumps(doc, indent=1) == expected_toml
```

### 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.

Examples of bad input data that can lead to writing invalid TOML without an error being raised include:

- A mapping where keys behave very much like strings, but aren't. E.g. a tuple of strings of length 1.
- A mapping where a value is a subclass of a supported type, but which overrides the `__str__` method.

Given proper input (a mapping consisting of non-subclassed [types returned by Tomli](https://github.com/hukkin/tomli?tab=readme-ov-file#how-do-toml-types-map-into-python-types))
the output should be valid TOML.


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "tomli-w",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "toml, tomli",
    "author": null,
    "author_email": "Taneli Hukkinen <hukkin@users.noreply.github.com>",
    "download_url": "https://files.pythonhosted.org/packages/d4/19/b65f1a088ee23e37cdea415b357843eca8b1422a7b11a9eee6e35d4ec273/tomli_w-1.1.0.tar.gz",
    "platform": null,
    "description": "[![Build Status](https://github.com/hukkin/tomli-w/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/hukkin/tomli-w/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)\n[![codecov.io](https://codecov.io/gh/hukkin/tomli-w/branch/master/graph/badge.svg)](https://codecov.io/gh/hukkin/tomli-w)\n[![PyPI version](https://img.shields.io/pypi/v/tomli-w)](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?](#does-tomli-w-support-writing-documents-with-comments)\n  - [Can I customize insignificant whitespace?](#can-i-customize-insignificant-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?<a name=\"does-tomli-w-support-writing-documents-with-comments\"></a>\n\nNo.\n\n### Can I customize insignificant whitespace?<a name=\"can-i-customize-insignificant-whitespace\"></a>\n\nIndent width of array content can be configured via the `indent` keyword argument.\n`indent` takes a non-negative integer, defaulting to 4.\n\n```python\nimport tomli_w\n\ndoc = {\"fruits\": [\"orange\", \"kiwi\", \"papaya\"]}\nexpected_toml = \"\"\"\\\nfruits = [\n \"orange\",\n \"kiwi\",\n \"papaya\",\n]\n\"\"\"\nassert tomli_w.dumps(doc, indent=1) == expected_toml\n```\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\nExamples of bad input data that can lead to writing invalid TOML without an error being raised include:\n\n- A mapping where keys behave very much like strings, but aren't. E.g. a tuple of strings of length 1.\n- A mapping where a value is a subclass of a supported type, but which overrides the `__str__` method.\n\nGiven proper input (a mapping consisting of non-subclassed [types returned by Tomli](https://github.com/hukkin/tomli?tab=readme-ov-file#how-do-toml-types-map-into-python-types))\nthe output should be valid TOML.\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A lil' TOML writer",
    "version": "1.1.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": "c4acce90573ba446a9bbe65838ded066a805234d159b4446ae9f8ec5bbd36cbd",
                "md5": "0fd3a1c93129acb21bbd3359a12209dd",
                "sha256": "1403179c78193e3184bfaade390ddbd071cba48a32a2e62ba11aae47490c63f7"
            },
            "downloads": -1,
            "filename": "tomli_w-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0fd3a1c93129acb21bbd3359a12209dd",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 6440,
            "upload_time": "2024-10-08T11:13:27",
            "upload_time_iso_8601": "2024-10-08T11:13:27.897805Z",
            "url": "https://files.pythonhosted.org/packages/c4/ac/ce90573ba446a9bbe65838ded066a805234d159b4446ae9f8ec5bbd36cbd/tomli_w-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d419b65f1a088ee23e37cdea415b357843eca8b1422a7b11a9eee6e35d4ec273",
                "md5": "8a074845fdcbb1fb6855bec753f0f94e",
                "sha256": "49e847a3a304d516a169a601184932ef0f6b61623fe680f836a2aa7128ed0d33"
            },
            "downloads": -1,
            "filename": "tomli_w-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "8a074845fdcbb1fb6855bec753f0f94e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 6929,
            "upload_time": "2024-10-08T11:13:29",
            "upload_time_iso_8601": "2024-10-08T11:13:29.279109Z",
            "url": "https://files.pythonhosted.org/packages/d4/19/b65f1a088ee23e37cdea415b357843eca8b1422a7b11a9eee6e35d4ec273/tomli_w-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-10-08 11:13:29",
    "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"
}
        
Elapsed time: 0.36830s