TOML

.. image:: https://img.shields.io/pypi/v/toml
:target: https://pypi.org/project/toml/

.. image:: https://travis-ci.org/uiri/toml.svg?branch=master
:target: https://travis-ci.org/uiri/toml

.. image:: https://img.shields.io/pypi/pyversions/toml.svg
:target: https://pypi.org/project/toml/

A Python library for parsing and creating TOML <https://en.wikipedia.org/wiki/TOML>_.

The module passes the TOML test suite <https://github.com/BurntSushi/toml-test>_.

See also:

The TOML Standard <https://github.com/toml-lang/toml>_
The currently supported TOML specification <https://github.com/toml-lang/toml/blob/v0.5.0/README.md>_

Installation

To install the latest release on PyPI <https://pypi.org/project/toml/>_,
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.

.. code:: pycon

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.

.. code:: pycon

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"

toml.dump takes a dictionary and a file descriptor and returns a string containing the
corresponding TOML-formatted data.

.. code:: pycon

with open('new_toml_file.toml', 'w') as f:
... new_toml_string = toml.dump(parsed_toml, f)

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.

Note

For Numpy users, by default the data types np.floatX will not be translated to floats by toml, but will instead be encoded as strings. To get around this, specify the TomlNumpyEncoder when saving your data.

.. code:: pycon

import toml
import numpy as np
a = np.arange(0, 10, dtype=np.double)
output = {'a': a}
toml.dumps(output)
'a = [ "0.0", "1.0", "2.0", "3.0", "4.0", "5.0", "6.0", "7.0", "8.0", "9.0",]\n'

toml.dumps(output, encoder=toml.TomlNumpyEncoder())
'a = [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0,]\n'

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, encoder=None)
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
* encoder: An instance of TomlEncoder (or subclass) for encoding the object. If None, will default to TomlEncoder

: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, encoder=None)
Create a TOML-formatted string from an input object

:Args:
* o: An object to be converted into TOML
* encoder: An instance of TomlEncoder (or subclass) for encoding the object. If None, will default to TomlEncoder

: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.

Package profile

toml

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description