Skip to main content

Python Library for Tom's Obvious, Minimal Language

Project description

https://badge.fury.io/py/toml.svg https://travis-ci.org/uiri/toml.svg?branch=master https://img.shields.io/pypi/pyversions/toml.svg

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"

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

toml-0.10.1.tar.gz (19.5 kB view details)

Uploaded Source

Built Distribution

toml-0.10.1-py2.py3-none-any.whl (19.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file toml-0.10.1.tar.gz.

File metadata

  • Download URL: toml-0.10.1.tar.gz
  • Upload date:
  • Size: 19.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.9.1 pkginfo/1.4.1 requests/2.18.4 setuptools/5.5.1 requests-toolbelt/0.8.0 tqdm/4.17.1 CPython/3.4.2

File hashes

Hashes for toml-0.10.1.tar.gz
Algorithm Hash digest
SHA256 926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f
MD5 743131c431419fe42f854cff02ad3abe
BLAKE2b-256 da2484d5c108e818ca294efe7c1ce237b42118643ce58a14d2462b3b2e3800d5

See more details on using hashes here.

File details

Details for the file toml-0.10.1-py2.py3-none-any.whl.

File metadata

  • Download URL: toml-0.10.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 19.5 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.9.1 pkginfo/1.4.1 requests/2.18.4 setuptools/5.5.1 requests-toolbelt/0.8.0 tqdm/4.17.1 CPython/3.4.2

File hashes

Hashes for toml-0.10.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88
MD5 a9373bcb6b5f5605370e27b6dcbbd9f6
BLAKE2b-256 9fe11b40b80f2e1663a6b9f497123c11d7d988c0919abbf3c3f2688e448c5363

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page