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