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