cpython/Doc/library/tomllib.rst
Miss Islington (bot) 857a161bb8
[3.13] gh-123905: Update TOML description to include version number (GH-123906) (#123908)
gh-123905: Update TOML description to include version number (GH-123906)

Update TOML description to include version number

There is some movement, currently blocked, that would update the TOML spec to 1.1.0; this would include breaking changes to what characters are allowed. Thus, it is worthwhile for the library page to be clear which version is implemented here.

(cherry picked from commit 1b29f4144c)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Paul Hoffman <phoffman@proper.com>
2024-09-24 11:15:30 -07:00

123 lines
5.5 KiB
ReStructuredText

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