Skip to main content

A lil' TOML writer

Project description

Build Status codecov.io PyPI version

Tomli-W

A lil' TOML writer

Table of Contents generated with mdformat-toc

Intro

Tomli-W is a Python library for writing TOML. It is a write-only counterpart to Tomli, which is a read-only TOML parser. Tomli-W is fully compatible with TOML v1.0.0.

Installation

pip install tomli-w

Usage

Write to string

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

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

Does Tomli-W sort the document?

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?

No.

Why does Tomli-W not write a multi-line string if the string value contains newlines?

This default was chosen to achieve lossless parse/write round-trips.

TOML strings can contain newlines where exact bytes matter, e.g.

s = "here's a newline\r\n"

TOML strings also can contain newlines where exact byte representation is not relevant, e.g.

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:

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?

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tomli-w, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size tomli_w-1.0.0.tar.gz (6.5 kB) File type Source Python version None Upload date Hashes View
Filename, size tomli_w-1.0.0-py3-none-any.whl (6.0 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page