17db96d56Sopenharmony_ci:mod:`tomllib` --- Parse TOML files 27db96d56Sopenharmony_ci=================================== 37db96d56Sopenharmony_ci 47db96d56Sopenharmony_ci.. module:: tomllib 57db96d56Sopenharmony_ci :synopsis: Parse TOML files. 67db96d56Sopenharmony_ci 77db96d56Sopenharmony_ci.. versionadded:: 3.11 87db96d56Sopenharmony_ci 97db96d56Sopenharmony_ci.. moduleauthor:: Taneli Hukkinen 107db96d56Sopenharmony_ci.. sectionauthor:: Taneli Hukkinen 117db96d56Sopenharmony_ci 127db96d56Sopenharmony_ci**Source code:** :source:`Lib/tomllib` 137db96d56Sopenharmony_ci 147db96d56Sopenharmony_ci-------------- 157db96d56Sopenharmony_ci 167db96d56Sopenharmony_ciThis module provides an interface for parsing TOML (Tom's Obvious Minimal 177db96d56Sopenharmony_ciLanguage, `https://toml.io <https://toml.io/en/>`_). This module does not 187db96d56Sopenharmony_cisupport writing TOML. 197db96d56Sopenharmony_ci 207db96d56Sopenharmony_ci.. seealso:: 217db96d56Sopenharmony_ci 227db96d56Sopenharmony_ci The `Tomli-W package <https://pypi.org/project/tomli-w/>`__ 237db96d56Sopenharmony_ci is a TOML writer that can be used in conjunction with this module, 247db96d56Sopenharmony_ci providing a write API familiar to users of the standard library 257db96d56Sopenharmony_ci :mod:`marshal` and :mod:`pickle` modules. 267db96d56Sopenharmony_ci 277db96d56Sopenharmony_ci.. seealso:: 287db96d56Sopenharmony_ci 297db96d56Sopenharmony_ci The `TOML Kit package <https://pypi.org/project/tomlkit/>`__ 307db96d56Sopenharmony_ci is a style-preserving TOML library with both read and write capability. 317db96d56Sopenharmony_ci It is a recommended replacement for this module for editing already 327db96d56Sopenharmony_ci existing TOML files. 337db96d56Sopenharmony_ci 347db96d56Sopenharmony_ci 357db96d56Sopenharmony_ciThis module defines the following functions: 367db96d56Sopenharmony_ci 377db96d56Sopenharmony_ci.. function:: load(fp, /, *, parse_float=float) 387db96d56Sopenharmony_ci 397db96d56Sopenharmony_ci Read a TOML file. The first argument should be a readable and binary file object. 407db96d56Sopenharmony_ci Return a :class:`dict`. Convert TOML types to Python using this 417db96d56Sopenharmony_ci :ref:`conversion table <toml-to-py-table>`. 427db96d56Sopenharmony_ci 437db96d56Sopenharmony_ci *parse_float* will be called with the string of every TOML 447db96d56Sopenharmony_ci float to be decoded. By default, this is equivalent to ``float(num_str)``. 457db96d56Sopenharmony_ci This can be used to use another datatype or parser for TOML floats 467db96d56Sopenharmony_ci (e.g. :class:`decimal.Decimal`). The callable must not return a 477db96d56Sopenharmony_ci :class:`dict` or a :class:`list`, else a :exc:`ValueError` is raised. 487db96d56Sopenharmony_ci 497db96d56Sopenharmony_ci A :exc:`TOMLDecodeError` will be raised on an invalid TOML document. 507db96d56Sopenharmony_ci 517db96d56Sopenharmony_ci 527db96d56Sopenharmony_ci.. function:: loads(s, /, *, parse_float=float) 537db96d56Sopenharmony_ci 547db96d56Sopenharmony_ci Load TOML from a :class:`str` object. Return a :class:`dict`. Convert TOML 557db96d56Sopenharmony_ci types to Python using this :ref:`conversion table <toml-to-py-table>`. The 567db96d56Sopenharmony_ci *parse_float* argument has the same meaning as in :func:`load`. 577db96d56Sopenharmony_ci 587db96d56Sopenharmony_ci A :exc:`TOMLDecodeError` will be raised on an invalid TOML document. 597db96d56Sopenharmony_ci 607db96d56Sopenharmony_ci 617db96d56Sopenharmony_ciThe following exceptions are available: 627db96d56Sopenharmony_ci 637db96d56Sopenharmony_ci.. exception:: TOMLDecodeError 647db96d56Sopenharmony_ci 657db96d56Sopenharmony_ci Subclass of :exc:`ValueError`. 667db96d56Sopenharmony_ci 677db96d56Sopenharmony_ci 687db96d56Sopenharmony_ciExamples 697db96d56Sopenharmony_ci-------- 707db96d56Sopenharmony_ci 717db96d56Sopenharmony_ciParsing a TOML file:: 727db96d56Sopenharmony_ci 737db96d56Sopenharmony_ci import tomllib 747db96d56Sopenharmony_ci 757db96d56Sopenharmony_ci with open("pyproject.toml", "rb") as f: 767db96d56Sopenharmony_ci data = tomllib.load(f) 777db96d56Sopenharmony_ci 787db96d56Sopenharmony_ciParsing a TOML string:: 797db96d56Sopenharmony_ci 807db96d56Sopenharmony_ci import tomllib 817db96d56Sopenharmony_ci 827db96d56Sopenharmony_ci toml_str = """ 837db96d56Sopenharmony_ci python-version = "3.11.0" 847db96d56Sopenharmony_ci python-implementation = "CPython" 857db96d56Sopenharmony_ci """ 867db96d56Sopenharmony_ci 877db96d56Sopenharmony_ci data = tomllib.loads(toml_str) 887db96d56Sopenharmony_ci 897db96d56Sopenharmony_ci 907db96d56Sopenharmony_ciConversion Table 917db96d56Sopenharmony_ci---------------- 927db96d56Sopenharmony_ci 937db96d56Sopenharmony_ci.. _toml-to-py-table: 947db96d56Sopenharmony_ci 957db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 967db96d56Sopenharmony_ci| TOML | Python | 977db96d56Sopenharmony_ci+==================+======================================================================================+ 987db96d56Sopenharmony_ci| table | dict | 997db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1007db96d56Sopenharmony_ci| string | str | 1017db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1027db96d56Sopenharmony_ci| integer | int | 1037db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1047db96d56Sopenharmony_ci| float | float (configurable with *parse_float*) | 1057db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1067db96d56Sopenharmony_ci| boolean | bool | 1077db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1087db96d56Sopenharmony_ci| offset date-time | datetime.datetime (``tzinfo`` attribute set to an instance of ``datetime.timezone``) | 1097db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1107db96d56Sopenharmony_ci| local date-time | datetime.datetime (``tzinfo`` attribute set to ``None``) | 1117db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1127db96d56Sopenharmony_ci| local date | datetime.date | 1137db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1147db96d56Sopenharmony_ci| local time | datetime.time | 1157db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 1167db96d56Sopenharmony_ci| array | list | 1177db96d56Sopenharmony_ci+------------------+--------------------------------------------------------------------------------------+ 118