:mod:`!tomllib` --- Parse TOML files

فهرست فصل‌ها دانلود آرشیوناشر

Python 3.14 Docs · نسخهٔ 3.14.10 · PSF License

:mod:!tomllib --- Parse TOML files

:synopsis: Parse TOML files.

Source code: 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.

Be cautious when parsing data from untrusted sources. A malicious TOML string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended.

The 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 marshal and pickle modules.

The 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:

Read a TOML file. The first argument should be a readable and binary file object. Return a dict. Convert TOML types to Python using this 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. decimal.Decimal). The callable must not return a dict or a list, else a ValueError` is raised.

A TOMLDecodeError will be raised on an invalid TOML document.

Load TOML from a str object. Return a dict. Convert TOML types to Python using this conversion table <toml-to-py-table>. The *parse_float* argument has the same meaning as in load.

A TOMLDecodeError will be raised on an invalid TOML document.

The following exceptions are available:

Subclass of ValueError with the following additional attributes:

The unformatted error message.

The TOML document being parsed.

The index of *doc* where parsing failed.

The line corresponding to *pos*.

The column corresponding to *pos*.

Added the *msg*, *doc* and *pos* parameters. Added the msg, doc, pos, lineno and colno attributes.

Passing free-form positional arguments is deprecated.

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

+------------------+--------------------------------------------------------------------------------------+

TOMLPython

+==================+======================================================================================+

TOML documentdict

+------------------+--------------------------------------------------------------------------------------+

stringstr

+------------------+--------------------------------------------------------------------------------------+

integerint

+------------------+--------------------------------------------------------------------------------------+

floatfloat (configurable with *parse_float*)

+------------------+--------------------------------------------------------------------------------------+

booleanbool

+------------------+--------------------------------------------------------------------------------------+

offset date-timedatetime.datetime (`tzinfo attribute set to an instance of datetime.timezone`)

+------------------+--------------------------------------------------------------------------------------+

local date-timedatetime.datetime (`tzinfo attribute set to None`)

+------------------+--------------------------------------------------------------------------------------+

local datedatetime.date

+------------------+--------------------------------------------------------------------------------------+

local timedatetime.time

+------------------+--------------------------------------------------------------------------------------+

arraylist

+------------------+--------------------------------------------------------------------------------------+

tabledict

+------------------+--------------------------------------------------------------------------------------+

inline tabledict

+------------------+--------------------------------------------------------------------------------------+

array of tableslist of dicts

+------------------+--------------------------------------------------------------------------------------+