Skip to content

lbt/toml

This branch is 1 commit ahead of, 9 commits behind uiri/toml:master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

a0273ad · Jul 5, 2021
Jul 14, 2018
Oct 27, 2020
Nov 1, 2020
Nov 12, 2017
Oct 27, 2018
Nov 12, 2017
Oct 27, 2020
Jul 3, 2018
May 14, 2020
Nov 1, 2020
Jul 5, 2021
Aug 30, 2018
Aug 30, 2018
Oct 27, 2020
Jan 3, 2020
Oct 27, 2020

Repository files navigation

TOML

https://img.shields.io/pypi/v/toml https://travis-ci.org/uiri/toml.svg?branch=master

A Python library for parsing and creating TOML.

The module passes the TOML test suite.

See also:

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"

Similarly toml.dump() takes a dictionary and a file descriptor and writes a string containing the corresponding TOML-formatted data to the file. The string is also returned.

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

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.

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

About

Python lib for TOML

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 99.7%
  • Shell 0.3%