Debian Codegraph @

Doc/library/tomllib.rst

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