| 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 |
+------------------+--------------------------------------------------------------------------------------+ |