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
71
72 Subclass of :exc:`ValueError`.
73
74
75 Examples
76 --------
77
78 Parsing a TOML file::
79
80 import tomllib
81
82 with open("pyproject.toml", "rb") as f:
83 data = tomllib.load(f)
84
85 Parsing a TOML string::
86
87 import tomllib
88
89 toml_str = """
90 python-version = "3.11.0"
91 python-implementation = "CPython"
92 """
93
94 data = tomllib.loads(toml_str)
95
96
97 Conversion Table
98 ----------------
99
100 .. _toml-to-py-table:
101
102 +------------------+--------------------------------------------------------------------------------------+
103 | TOML | Python |
104 +==================+======================================================================================+
105 | TOML document | dict |
106 +------------------+--------------------------------------------------------------------------------------+
107 | string | str |
108 +------------------+--------------------------------------------------------------------------------------+
109 | integer | int |
110 +------------------+--------------------------------------------------------------------------------------+
111 | float | float (configurable with *parse_float*) |
112 +------------------+--------------------------------------------------------------------------------------+
113 | boolean | bool |
114 +------------------+--------------------------------------------------------------------------------------+
115 | offset date-time | datetime.datetime (``tzinfo`` attribute set to an instance of ``datetime.timezone``) |
116 +------------------+--------------------------------------------------------------------------------------+
117 | local date-time | datetime.datetime (``tzinfo`` attribute set to ``None``) |
118 +------------------+--------------------------------------------------------------------------------------+
119 | local date | datetime.date |
120 +------------------+--------------------------------------------------------------------------------------+
121 | local time | datetime.time |
122 +------------------+--------------------------------------------------------------------------------------+
123 | array | list |
124 +------------------+--------------------------------------------------------------------------------------+
125 | table | dict |
126 +------------------+--------------------------------------------------------------------------------------+
127 | inline table | dict |
128 +------------------+--------------------------------------------------------------------------------------+
129 | array of tables | list of dicts |
130 +------------------+--------------------------------------------------------------------------------------+