TOML

A Python library for parsing and creating TOML.

The module passes the TOML test suite which is a fork of BurntSushi's TOML test suite.

See also:

• The TOML Standard
• The current TOML specification

Installation

To install the latest release on PyPi, simply run:

pip install toml

Or to install the latest development version, run:

git clone https://github.com/uiri/toml.git
cd toml
python setup.py install

Quick Tutorial

toml.loads takes in a string containing standard TOML-formatted data and returns a dictionary containing the parsed data.

>>> import toml
>>> toml_string = """
... # 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
...
... [servers]
...
...   # Indentation (tabs and/or spaces) is allowed but not required
...   [servers.alpha]
...   ip = "10.0.0.1"
...   dc = "eqdc10"
...
...   [servers.beta]
...   ip = "10.0.0.2"
...   dc = "eqdc10"
...
... [clients]
... data = [ ["gamma", "delta"], [1, 2] ]
...
... # Line breaks are OK when inside arrays
... hosts = [
...   "alpha",
...   "omega"
... ]
... """
>>> parsed_toml = toml.loads(toml_string)

toml.dumps takes a dictionary and returns a string containing the corresponding TOML-formatted data.

>>> new_toml_string = toml.dumps(parsed_toml)
>>> print(new_toml_string)
title = "TOML Example"
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00Z
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002,]
connection_max = 5000
enabled = true
[clients]
data = [ [ "gamma", "delta",], [ 1, 2,],]
hosts = [ "alpha", "omega",]
[servers.alpha]
ip = "10.0.0.1"
dc = "eqdc10"
[servers.beta]
ip = "10.0.0.2"
dc = "eqdc10"

For more functions, view the API Reference below.

API Reference

toml.load(f, _dict=dict)

Parse a file or a list of files as TOML and return a dictionary.

Args:	f: A path to a file, list of filepaths (to be read into single object) or a file descriptor _dict: The class of the dictionary object to be returned
Returns:	A dictionary (or object _dict) containing parsed TOML data
Raises:	TypeError: When f is an invalid type or is a list containing invalid types TomlDecodeError: When an error occurs while decoding the file(s)

toml.loads(s, _dict=dict)

Parse a TOML-formatted string to a dictionary.

Args:	s: The TOML-formatted string to be parsed _dict: Specifies the class of the returned toml dictionary
Returns:	A dictionary (or object _dict) containing parsed TOML data
Raises:	TypeError: When a non-string object is passed TomlDecodeError: When an error occurs while decoding the TOML-formatted string

toml.dump(o, f)

Write a dictionary to a file containing TOML-formatted data

Args:	o: An object to be converted into TOML f: A File descriptor where the TOML-formatted output should be stored
Returns:	A string containing the TOML-formatted data corresponding to object o
Raises:	TypeError: When anything other than file descriptor is passed

toml.dumps(o)

Create a TOML-formatted string from an input object

Args:	o: An object to be converted into TOML
Returns:	A string containing the TOML-formatted data corresponding to object o

Licensing

This project is released under the terms of the MIT Open Source License. View LICENSE.txt for more information.