mirror of
https://github.com/python/cpython.git
synced 2025-07-24 11:44:31 +00:00
857a161bb8
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>
123 lines
5.5 KiB
ReStructuredText
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 |
|
|
+------------------+--------------------------------------------------------------------------------------+
|