blob: 918576eb37eaee7b70c16d489d1a5e4a69c151ca (
plain)
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
|
: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 (Tom's Obvious Minimal
Language, `https://toml.io <https://toml.io/en/>`_). This module does not
support writing TOML.
.. seealso::
The `Tomli-W package <https://pypi.org/project/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 `TOML Kit package <https://pypi.org/project/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
Subclass of :exc:`ValueError`.
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 |
+==================+======================================================================================+
| table | 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 |
+------------------+--------------------------------------------------------------------------------------+
|
