1:mod:`tomllib` --- Parse TOML files
2===================================
3
4.. module:: tomllib
5   :synopsis: Parse TOML files.
6
7.. versionadded:: 3.11
8
9.. moduleauthor:: Taneli Hukkinen
10.. sectionauthor:: Taneli Hukkinen
11
12**Source code:** :source:`Lib/tomllib`
13
14--------------
15
16This module provides an interface for parsing TOML (Tom's Obvious Minimal
17Language, `https://toml.io <https://toml.io/en/>`_). This module does not
18support writing TOML.
19
20.. seealso::
21
22    The `Tomli-W package <https://pypi.org/project/tomli-w/>`__
23    is a TOML writer that can be used in conjunction with this module,
24    providing a write API familiar to users of the standard library
25    :mod:`marshal` and :mod:`pickle` modules.
26
27.. seealso::
28
29    The `TOML Kit package <https://pypi.org/project/tomlkit/>`__
30    is a style-preserving TOML library with both read and write capability.
31    It is a recommended replacement for this module for editing already
32    existing TOML files.
33
34
35This module defines the following functions:
36
37.. function:: load(fp, /, *, parse_float=float)
38
39   Read a TOML file. The first argument should be a readable and binary file object.
40   Return a :class:`dict`. Convert TOML types to Python using this
41   :ref:`conversion table <toml-to-py-table>`.
42
43   *parse_float* will be called with the string of every TOML
44   float to be decoded.  By default, this is equivalent to ``float(num_str)``.
45   This can be used to use another datatype or parser for TOML floats
46   (e.g. :class:`decimal.Decimal`). The callable must not return a
47   :class:`dict` or a :class:`list`, else a :exc:`ValueError` is raised.
48
49   A :exc:`TOMLDecodeError` will be raised on an invalid TOML document.
50
51
52.. function:: loads(s, /, *, parse_float=float)
53
54   Load TOML from a :class:`str` object. Return a :class:`dict`. Convert TOML
55   types to Python using this :ref:`conversion table <toml-to-py-table>`. The
56   *parse_float* argument has the same meaning as in :func:`load`.
57
58   A :exc:`TOMLDecodeError` will be raised on an invalid TOML document.
59
60
61The following exceptions are available:
62
63.. exception:: TOMLDecodeError
64
65   Subclass of :exc:`ValueError`.
66
67
68Examples
69--------
70
71Parsing a TOML file::
72
73    import tomllib
74
75    with open("pyproject.toml", "rb") as f:
76        data = tomllib.load(f)
77
78Parsing a TOML string::
79
80    import tomllib
81
82    toml_str = """
83    python-version = "3.11.0"
84    python-implementation = "CPython"
85    """
86
87    data = tomllib.loads(toml_str)
88
89
90Conversion Table
91----------------
92
93.. _toml-to-py-table:
94
95+------------------+--------------------------------------------------------------------------------------+
96| TOML             | Python                                                                               |
97+==================+======================================================================================+
98| table            | dict                                                                                 |
99+------------------+--------------------------------------------------------------------------------------+
100| string           | str                                                                                  |
101+------------------+--------------------------------------------------------------------------------------+
102| integer          | int                                                                                  |
103+------------------+--------------------------------------------------------------------------------------+
104| float            | float (configurable with *parse_float*)                                              |
105+------------------+--------------------------------------------------------------------------------------+
106| boolean          | bool                                                                                 |
107+------------------+--------------------------------------------------------------------------------------+
108| offset date-time | datetime.datetime (``tzinfo`` attribute set to an instance of ``datetime.timezone``) |
109+------------------+--------------------------------------------------------------------------------------+
110| local date-time  | datetime.datetime (``tzinfo`` attribute set to ``None``)                             |
111+------------------+--------------------------------------------------------------------------------------+
112| local date       | datetime.date                                                                        |
113+------------------+--------------------------------------------------------------------------------------+
114| local time       | datetime.time                                                                        |
115+------------------+--------------------------------------------------------------------------------------+
116| array            | list                                                                                 |
117+------------------+--------------------------------------------------------------------------------------+
118