Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/uiri/toml

Python lib for TOML
https://github.com/uiri/toml

hacktoberfest hacktoberfest2020

Last synced: 28 days ago
JSON representation

Python lib for TOML

Awesome Lists containing this project

README 

        
****

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



The module passes `the TOML test suite `_.



See also:



* `The TOML Standard `_

* `The currently supported 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.



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