rtoml0.12.0
rtoml0.12.0
Published
pip install rtoml
Package Downloads
Authors
Requires Python
>=3.9
Dependencies
rtoml
A better TOML library for python implemented in rust.
Why Use rtoml
- Correctness: rtoml is based on the widely used and very stable toml-rs library, it passes all the standard TOML tests as well as having 100% coverage on python code. Other TOML libraries for python I tried all failed to parse some valid TOML.
- Performance: see github.com/pwwang/toml-bench - rtoml is the fastest Python TOML libraries at the time of writing.
None
-value handling: rtoml has flexible support forNone
values, instead of simply ignoring them.
Install
Requires python>=3.9
, binaries are available from PyPI for Linux, macOS and Windows,
see here.
pip install rtoml
If no binary is available on pypi for you system configuration; you'll need rust stable installed before you can install rtoml.
Usage
load
def load(toml: Union[str, Path, TextIO], *, none_value: Optional[str] = None) -> Dict[str, Any]: ...
Parse TOML via a string or file and return a python dictionary.
toml
: astr
,Path
or file object fromopen()
.none_value
: controlling which value intoml
is loaded asNone
in python. By default,none_value
isNone
, which means nothing is loaded asNone
loads
def loads(toml: str, *, none_value: Optional[str] = None) -> Dict[str, Any]: ...
Parse a TOML string and return a python dictionary. (provided to match the interface of json
and similar libraries)
toml
: astr
containing TOML.none_value
: controlling which value intoml
is loaded asNone
in python. By default,none_value
isNone
, which means nothing is loaded asNone
dumps
def dumps(obj: Any, *, pretty: bool = False, none_value: Optional[str] = "null") -> str: ...
Serialize a python object to TOML.
obj
: a python object to be serialized.pretty
: ifTrue
the output has a more "pretty" format.none_value
: controlling howNone
values inobj
are serialized.none_value=None
meansNone
values are ignored.
dump
def dump(
obj: Any, file: Union[Path, TextIO], *, pretty: bool = False, none_value: Optional[str] = "null"
) -> int: ...
Serialize a python object to TOML and write it to a file.
obj
: a python object to be serialized.file
: aPath
or file object fromopen()
.pretty
: ifTrue
the output has a more "pretty" format.none_value
: controlling howNone
values inobj
are serialized.none_value=None
meansNone
values are ignored.
Examples
from datetime import datetime, timezone, timedelta
import rtoml
obj = {
'title': 'TOML Example',
'owner': {
'dob': datetime(1979, 5, 27, 7, 32, tzinfo=timezone(timedelta(hours=-8))),
'name': 'Tom Preston-Werner',
},
'database': {
'connection_max': 5000,
'enabled': True,
'ports': [8001, 8001, 8002],
'server': '192.168.1.1',
},
}
loaded_obj = rtoml.load("""\
# This is a TOML document.
title = "TOML Example"
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates
[database]
server = "192.168.1.1"
ports = [8001, 8001, 8002]
connection_max = 5000
enabled = true
""")
assert loaded_obj == obj
assert rtoml.dumps(obj) == """\
title = "TOML Example"
[owner]
dob = 1979-05-27T07:32:00-08:00
name = "Tom Preston-Werner"
[database]
connection_max = 5000
enabled = true
server = "192.168.1.1"
ports = [8001, 8001, 8002]
"""
An example of None
-value handling:
obj = {
'a': None,
'b': 1,
'c': [1, 2, None, 3],
}
# Ignore None values
assert rtoml.dumps(obj, none_value=None) == """\
b = 1
c = [1, 2, 3]
"""
# Serialize None values as '@None'
assert rtoml.dumps(obj, none_value='@None') == """\
a = "@None"
b = 1
c = [1, 2, "@None", 3]
"""
# Deserialize '@None' back to None
assert rtoml.load("""\
a = "@None"
b = 1
c = [1, 2, "@None", 3]
""", none_value='@None') == obj