DEPRECATION NOTE

qTOML is now deprecated. It will not be updated further.

In replacement for qTOML, I endorse the tomllib standard library module for Python 3.11+, or tomli for earlier versions. In either case, tomli-w is available for writing.

These libraries satisfy the use case I had for writing qTOML to begin with, making this version redundant.

qTOML

qtoml is another Python TOML encoder/decoder. I wrote it because I found uiri/toml too unstable, and PyTOML too slow.

For information concerning the TOML language, see toml-lang/toml.

qtoml currently supports TOML v0.5.0.

Usage

qtoml is available on PyPI. You can install it using pip:

$ pip install qtoml

qtoml supports the standard load/loads/dump/dumps API common to most similar modules. Usage:

>>> import qtoml
>>> toml_string = """
... test_value = 7
... """
>>> qtoml.loads(toml_string)
{'test_value': 7}
>>> print(qtoml.dumps({'a': 4, 'b': 5.0}))
a = 4
b = 5.0

>>> infile = open('filename.toml', 'r')
>>> parsed_structure = qtoml.load(infile)
>>> outfile = open('new_filename.toml', 'w')
>>> qtoml.dump(parsed_structure, outfile)

TOML supports a fairly complete subset of the Python data model, but notably does not include a null or None value. If you have a large dictionary from somewhere else including None values, it can occasionally be useful to substitute them on encode:

>>> print(qtoml.dumps({ 'none': None }))
qtoml.encoder.TOMLEncodeError: TOML cannot encode None
>>> print(qtoml.dumps({ 'none': None }, encode_none='None'))
none = 'None'

The encode_none value must be a replacement encodable by TOML, such as zero or a string.

This breaks reversibility of the encoding, by rendering None values indistinguishable from literal occurrences of whatever sentinel you chose. Thus, it should not be used when exact representations are critical.

Development/testing

qtoml uses the poetry tool for project management. To check out the project for development, run:

$ git clone --recurse-submodules https://github.com/alethiophile/qtoml
$ cd qtoml
$ poetry install

This assumes poetry is already installed. The package and dependencies will be installed in the currently active virtualenv if there is one, or a project-specific new one created if not.

qtoml is tested against the alethiophile/toml-test test suite, forked from uiri's fork of the original by BurntSushi. To run the tests, after checking out the project as shown above, enter the tests directory and run:

$ pytest              # if you already had a virtualenv active
$ poetry run pytest   # if you didn't

License

This project is available under the terms of the MIT license.