Files
FootPrint/Python/pythoncore-3.15-64/Doc/html/library/tomllib.html
T

577 lines
34 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="tomllib — Parse TOML files" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/tomllib.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Source code: Lib/tomllib This module provides an interface for parsing TOML 1.1.0 (Tom’s Obvious Minimal Language, https://toml.io). This module does not support writing TOML. This module defines t..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Source code: Lib/tomllib This module provides an interface for parsing TOML 1.1.0 (Tom’s Obvious Minimal Language, https://toml.io). This module does not support writing TOML. This module defines t..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>tomllib — Parse TOML files &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="netrc — netrc file processing" href="netrc.html" />
<link rel="prev" title="configparser — Configuration file parser" href="configparser.html" />
<link rel="canonical" href="https://docs.python.org/3/library/tomllib.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files</a><ul>
<li><a class="reference internal" href="#examples">Examples</a></li>
<li><a class="reference internal" href="#conversion-table">Conversion Table</a></li>
<li><a class="reference internal" href="#limits-and-interoperability-considerations">Limits and interoperability considerations</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="configparser.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="netrc.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">netrc</span></code> — netrc file processing</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/tomllib.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/tomllib.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="netrc.html" title="netrc — netrc file processing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="configparser.html" title="configparser — Configuration file parser"
accesskey="P">previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">File Formats</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-tomllib">
<span id="tomllib-parse-toml-files"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files<a class="headerlink" href="#module-tomllib" title="Link to this heading"></a></h1>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/tomllib">Lib/tomllib</a></p>
<hr class="docutils" />
<p>This module provides an interface for parsing TOML 1.1.0 (Tom’s Obvious Minimal
Language, <a class="reference external" href="https://toml.io/en/">https://toml.io</a>). This module does not
support writing TOML.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11: </span>The module was added with support for TOML 1.0.0.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Added TOML 1.1.0 support.
See the <a class="reference internal" href="../whatsnew/3.15.html#whatsnew315-tomllib-1-1-0"><span class="std std-ref">What’s New</span></a> for details.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>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.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>The <a class="extlink-pypi reference external" href="https://pypi.org/project/tomli-w/">Tomli-W package</a>
is a TOML writer that can be used in conjunction with this module,
providing a write API familiar to users of the standard library
<a class="reference internal" href="marshal.html#module-marshal" title="marshal: Convert Python objects to streams of bytes and back (with different constraints)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">marshal</span></code></a> and <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickle</span></code></a> modules.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>The <a class="extlink-pypi reference external" href="https://pypi.org/project/tomlkit/">TOML Kit package</a>
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.</p>
</div>
<p>This module defines the following functions:</p>
<dl class="py function">
<dt class="sig sig-object py" id="tomllib.load">
<span class="sig-prename descclassname"><span class="pre">tomllib.</span></span><span class="sig-name descname"><span class="pre">load</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fp</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">parse_float</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">float</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tomllib.load" title="Link to this definition"></a></dt>
<dd><p>Read a TOML file. The first argument should be a readable and binary file object.
Return a <a class="reference internal" href="../builtins/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>. Convert TOML types to Python using this
<a class="reference internal" href="#toml-to-py-table"><span class="std std-ref">conversion table</span></a>.</p>
<p><em>parse_float</em> will be called with the string of every TOML
float to be decoded. By default, this is equivalent to <code class="docutils literal notranslate"><span class="pre">float(num_str)</span></code>.
This can be used to use another datatype or parser for TOML floats
(e.g. <a class="reference internal" href="decimal.html#decimal.Decimal" title="decimal.Decimal"><code class="xref py py-class docutils literal notranslate"><span class="pre">decimal.Decimal</span></code></a>). The callable must not return a
<a class="reference internal" href="../builtins/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> or a <a class="reference internal" href="../builtins/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>, else a <a class="reference internal" href="../builtins/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
<p>A <a class="reference internal" href="#tomllib.TOMLDecodeError" title="tomllib.TOMLDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TOMLDecodeError</span></code></a> will be raised on an invalid TOML document.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="tomllib.loads">
<span class="sig-prename descclassname"><span class="pre">tomllib.</span></span><span class="sig-name descname"><span class="pre">loads</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">parse_float</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">float</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tomllib.loads" title="Link to this definition"></a></dt>
<dd><p>Load TOML from a <a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> object. Return a <a class="reference internal" href="../builtins/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>. Convert TOML
types to Python using this <a class="reference internal" href="#toml-to-py-table"><span class="std std-ref">conversion table</span></a>. The
<em>parse_float</em> argument has the same meaning as in <a class="reference internal" href="#tomllib.load" title="tomllib.load"><code class="xref py py-func docutils literal notranslate"><span class="pre">load()</span></code></a>.</p>
<p>A <a class="reference internal" href="#tomllib.TOMLDecodeError" title="tomllib.TOMLDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TOMLDecodeError</span></code></a> will be raised on an invalid TOML document.</p>
</dd></dl>
<p>The following exceptions are available:</p>
<dl class="py exception">
<dt class="sig sig-object py" id="tomllib.TOMLDecodeError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tomllib.</span></span><span class="sig-name descname"><span class="pre">TOMLDecodeError</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">doc</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pos</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tomllib.TOMLDecodeError" title="Link to this definition"></a></dt>
<dd><p>Subclass of <a class="reference internal" href="../builtins/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> with the following additional attributes:</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="tomllib.TOMLDecodeError.msg">
<span class="sig-name descname"><span class="pre">msg</span></span><a class="headerlink" href="#tomllib.TOMLDecodeError.msg" title="Link to this definition"></a></dt>
<dd><p>The unformatted error message.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="tomllib.TOMLDecodeError.doc">
<span class="sig-name descname"><span class="pre">doc</span></span><a class="headerlink" href="#tomllib.TOMLDecodeError.doc" title="Link to this definition"></a></dt>
<dd><p>The TOML document being parsed.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="tomllib.TOMLDecodeError.pos">
<span class="sig-name descname"><span class="pre">pos</span></span><a class="headerlink" href="#tomllib.TOMLDecodeError.pos" title="Link to this definition"></a></dt>
<dd><p>The index of <em>doc</em> where parsing failed.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="tomllib.TOMLDecodeError.lineno">
<span class="sig-name descname"><span class="pre">lineno</span></span><a class="headerlink" href="#tomllib.TOMLDecodeError.lineno" title="Link to this definition"></a></dt>
<dd><p>The line corresponding to <em>pos</em>.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="tomllib.TOMLDecodeError.colno">
<span class="sig-name descname"><span class="pre">colno</span></span><a class="headerlink" href="#tomllib.TOMLDecodeError.colno" title="Link to this definition"></a></dt>
<dd><p>The column corresponding to <em>pos</em>.</p>
</dd></dl>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>Added the <em>msg</em>, <em>doc</em> and <em>pos</em> parameters.
Added the <a class="reference internal" href="#tomllib.TOMLDecodeError.msg" title="tomllib.TOMLDecodeError.msg"><code class="xref py py-attr docutils literal notranslate"><span class="pre">msg</span></code></a>, <a class="reference internal" href="#tomllib.TOMLDecodeError.doc" title="tomllib.TOMLDecodeError.doc"><code class="xref py py-attr docutils literal notranslate"><span class="pre">doc</span></code></a>, <a class="reference internal" href="#tomllib.TOMLDecodeError.pos" title="tomllib.TOMLDecodeError.pos"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pos</span></code></a>, <a class="reference internal" href="#tomllib.TOMLDecodeError.lineno" title="tomllib.TOMLDecodeError.lineno"><code class="xref py py-attr docutils literal notranslate"><span class="pre">lineno</span></code></a> and <a class="reference internal" href="#tomllib.TOMLDecodeError.colno" title="tomllib.TOMLDecodeError.colno"><code class="xref py py-attr docutils literal notranslate"><span class="pre">colno</span></code></a> attributes.</p>
</div>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>Passing free-form positional arguments is deprecated.</p>
</div>
</dd></dl>
<section id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
<p>Parsing a TOML file:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">tomllib</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"pyproject.toml"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">tomllib</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
</pre></div>
</div>
<p>Parsing a TOML string:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">tomllib</span>
<span class="n">toml_str</span> <span class="o">=</span> <span class="s2">"""</span>
<span class="s2">python-version = "3.11.0"</span>
<span class="s2">python-implementation = "CPython"</span>
<span class="s2">"""</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">tomllib</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">toml_str</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="conversion-table">
<h2>Conversion Table<a class="headerlink" href="#conversion-table" title="Link to this heading"></a></h2>
<table class="docutils align-default" id="toml-to-py-table">
<thead>
<tr class="row-odd"><th class="head"><p>TOML</p></th>
<th class="head"><p>Python</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>TOML document</p></td>
<td><p>dict</p></td>
</tr>
<tr class="row-odd"><td><p>string</p></td>
<td><p>str</p></td>
</tr>
<tr class="row-even"><td><p>integer</p></td>
<td><p>int</p></td>
</tr>
<tr class="row-odd"><td><p>float</p></td>
<td><p>float (configurable with <em>parse_float</em>)</p></td>
</tr>
<tr class="row-even"><td><p>boolean</p></td>
<td><p>bool</p></td>
</tr>
<tr class="row-odd"><td><p>offset date-time</p></td>
<td><p>datetime.datetime (<code class="docutils literal notranslate"><span class="pre">tzinfo</span></code> attribute set to an instance of <code class="docutils literal notranslate"><span class="pre">datetime.timezone</span></code>)</p></td>
</tr>
<tr class="row-even"><td><p>local date-time</p></td>
<td><p>datetime.datetime (<code class="docutils literal notranslate"><span class="pre">tzinfo</span></code> attribute set to <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></td>
</tr>
<tr class="row-odd"><td><p>local date</p></td>
<td><p>datetime.date</p></td>
</tr>
<tr class="row-even"><td><p>local time</p></td>
<td><p>datetime.time</p></td>
</tr>
<tr class="row-odd"><td><p>array</p></td>
<td><p>list</p></td>
</tr>
<tr class="row-even"><td><p>table</p></td>
<td><p>dict</p></td>
</tr>
<tr class="row-odd"><td><p>inline table</p></td>
<td><p>dict</p></td>
</tr>
<tr class="row-even"><td><p>array of tables</p></td>
<td><p>list of dicts</p></td>
</tr>
</tbody>
</table>
</section>
<section id="limits-and-interoperability-considerations">
<h2>Limits and interoperability considerations<a class="headerlink" href="#limits-and-interoperability-considerations" title="Link to this heading"></a></h2>
<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> places some limits on the documents it can handle,
and it preserves details that other TOML parsers are allowed to ignore.
When writing portable TOML files, only use features that are
guaranteed or recommended by the standard.</p>
<p>The implementation details listed here may change in future versions of Python.</p>
<dl>
<dt>Tables/dicts</dt><dd><p>The TOML spec does not guarantee key/value pairs in TOML documents and
tables to be in any specific order.</p>
<div class="impl-detail compound">
<p><strong>CPython implementation detail:</strong> <code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> loads dictionary entries in the order they appear in
the source.</p>
</div>
</dd>
<dt>Integers</dt><dd><p>TOML recommends supporting integers in <code class="docutils literal notranslate"><span class="pre">range(−2**63,</span> <span class="pre">2**63)</span></code>.</p>
<div class="impl-detail compound">
<p><strong>CPython implementation detail:</strong> <code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> uses <a class="reference internal" href="../builtins/stdtypes.html#int-max-str-digits"><span class="std std-ref">Python’s limit on integer string conversion</span></a> (4300 digits by default).</p>
</div>
</dd>
<dt>Floats</dt><dd><p>TOML recommends supporting at least IEEE 754 binary64 values,
which means that numbers with more than 15 significant decimal digits
are likely to be rounded.</p>
<div class="impl-detail compound">
<p><strong>CPython implementation detail:</strong> <code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> uses Python <a class="reference internal" href="../builtins/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> by default;
on many common platforms this is the recommended binary64.
See <a class="reference internal" href="sys.html#sys.float_info" title="sys.float_info"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.float_info</span></code></a> for details.</p>
</div>
</dd>
<dt>Nesting limit</dt><dd><p>TOML 1.1.0 does not recommend a limit on how deeply arrays and tables
may be nested inside one another.
(A limit of 100 has been proposed for a future version of TOML.)</p>
<div class="impl-detail compound">
<p><strong>CPython implementation detail:</strong> In <code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code>, the nesting level is mainly limited by Python’s
<a class="reference internal" href="sys.html#sys.getrecursionlimit" title="sys.getrecursionlimit"><code class="xref py py-func docutils literal notranslate"><span class="pre">recursion</span> <span class="pre">limit</span></code></a>.
Note that code that calls <code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> may contribute to the limit.</p>
</div>
</dd>
</dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files</a><ul>
<li><a class="reference internal" href="#examples">Examples</a></li>
<li><a class="reference internal" href="#conversion-table">Conversion Table</a></li>
<li><a class="reference internal" href="#limits-and-interoperability-considerations">Limits and interoperability considerations</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="configparser.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="netrc.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">netrc</span></code> — netrc file processing</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/tomllib.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/tomllib.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="netrc.html" title="netrc — netrc file processing"
>next</a> |</li>
<li class="right" >
<a href="configparser.html" title="configparser — Configuration file parser"
>previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="fileformats.html" >File Formats</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>