| single |
[Build Status]
[![codecov.io]](https://codecov.io/gh/hukkin/tomli)
[PyPI version]
# Tomli
> A lil' TOML parser
**Table of Contents** *generated with [mdformat-toc]*
- [Intro]
- [Installation]
- [Usage]
- [Parse a TOML string]
- [Parse a TOML file]
- [Handle invalid TOML]
- [Construct `decimal.Decimal`s from TOML floats]
- [Building a `tomli`/`tomllib` compatibility layer]
- [FAQ]
- [Why this parser?]
- [Is comment preserving round-trip parsing supported?]
- [Is there a `dumps`, `write` or `encode` function?]
- [How do TOML types map into Python types?]
- [Performance]
- [Pure Python]
- [Mypyc generated wheel]
## Intro
Tomli is a Python library for parsing [TOML].
It is fully compatible with [TOML v1.0.0].
A version of Tomli, the `tomllib` module,
was added to the standard library in Python 3.11
via [PEP 680].
Tomli continues to provide a backport on PyPI for Python versions
where the standard library module is not available
and that have not yet reached their end-of-life.
Tomli uses [mypyc]
to generate binary wheels for most of the widely used platforms,
so Python 3.11+ users may prefer it over `tomllib` for improved
performance.
Pure Python wheels are available on any platform and should perform the
same as `tomllib`.
## Installation
`bash
pip install tomli
`
## Usage
### Parse a TOML string
```python
import tomli
toml_str = """
[[players]]
name = "Lehtinen"
number = 26
[[players]]
name = "Numminen"
number = 27
"""
toml_dict = tomli.loads(toml_str)
assert toml_dict == {
"players": [{"name": "Lehtinen", "number": 26}, {"name": "Numminen",
"number": 27}]
}
```
### Parse a TOML file
```python
import tomli
with open("path_to_file/conf.toml", "rb") as f:
toml_dict = tomli.load(f)
```
The file must be opened in binary mode (with the `"rb"` flag).
Binary mode will enforce decoding the file as UTF-8 with universal newlines
disabled,
both of which are required to correctly parse TOML.
### Handle invalid TOML
```python
import tomli
try:
|