"tomllib" --- Parse TOML files
******************************

**Código fuente:** 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.

Added in version 3.11: The module was added with support for TOML
1.0.0.

Distinto en la versión 3.15: Added TOML 1.1.0 support. See the What's
New for details.

Advertencia:

  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.

Ver también:

  The Tomli-W package 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.

Ver también:

  The TOML Kit package 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.

Este módulo define las siguientes funciones:

tomllib.load(fp, /, *, parse_float=float)

   Lee un archivo TOML. El primer argumento debe ser un objeto de
   archivo legible y binario. Retorna un "dict". Convierte los tipos
   TOML a Python utilizando esta tabla de conversión.

   *parse_float* se llamará con la cadena de cada TOML flotante que se
   decodificará.  Por defecto, esto es equivalente a "float(num_str)".
   Esto se puede utilizar para usar otro tipo de datos o analizador
   para flotantes TOML (por ejemplo, "decimal.Decimal"). La llamada no
   debe devolver un "dict" o un "list", de lo contrario se lanza un
   "ValueError".

   Un "TOMLDecodeError" se levantará en un documento TOML inválido.

tomllib.loads(s, /, *, parse_float=float)

   Carga TOML de un objeto "str". Retorna un "dict". Convierte los
   tipos TOML a Python utilizando esta tabla de conversión. El
   argumento *parse_float* tiene el mismo significado que en "load()".

   Un "TOMLDecodeError" se levantará en un documento TOML inválido.

Las siguientes excepciones están disponibles:

exception tomllib.TOMLDecodeError(msg, doc, pos)

   Subclass of "ValueError" with the following additional attributes:

   msg

      The unformatted error message.

   doc

      The TOML document being parsed.

   pos

      The index of *doc* where parsing failed.

   lineno

      The line corresponding to *pos*.

   colno

      The column corresponding to *pos*.

   Distinto en la versión 3.14: Added the *msg*, *doc* and *pos*
   parameters. Added the "msg", "doc", "pos", "lineno" and "colno"
   attributes.

   Obsoleto desde la versión 3.14: Passing free-form positional
   arguments is deprecated.


Ejemplos
========

Analiza un TOML file:

   import tomllib

   with open("pyproject.toml", "rb") as f:
       data = tomllib.load(f)

Analiza un TOML string:

   import tomllib

   toml_str = """
   python-version = "3.11.0"
   python-implementation = "CPython"
   """

   data = tomllib.loads(toml_str)


Tabla de conversión
===================

+--------------------+----------------------------------------------------------------------------------------+
| TOML               | Python                                                                                 |
|====================|========================================================================================|
| TOML document      | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| cadena             | str                                                                                    |
+--------------------+----------------------------------------------------------------------------------------+
| integer            | int                                                                                    |
+--------------------+----------------------------------------------------------------------------------------+
| flotante           | flotante (configurable con *parse_float*)                                              |
+--------------------+----------------------------------------------------------------------------------------+
| boolean            | bool                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| offset date-time   | datetime.datetime (atributo "tzinfo" establecido en una instancia de                   |
|                    | "datetime.timezone")                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| local date-time    | datetime.datetime (atributo "tzinfo" establecido en "None")                            |
+--------------------+----------------------------------------------------------------------------------------+
| local date         | datetime.date                                                                          |
+--------------------+----------------------------------------------------------------------------------------+
| local time         | datetime.time                                                                          |
+--------------------+----------------------------------------------------------------------------------------+
| array              | list                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| tabla              | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| inline table       | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| array of tables    | list of dicts                                                                          |
+--------------------+----------------------------------------------------------------------------------------+


Limits and interoperability considerations
==========================================

"tomllib" 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.

The implementation details listed here may change in future versions
of Python.

Tables/dicts
   The TOML spec does not guarantee key/value pairs in TOML documents
   and tables to be in any specific order.

   **Detalles de implementación de CPython:** "tomllib" loads
   dictionary entries in the order they appear in the source.

Integers
   TOML recommends supporting integers in "range(−2**63, 2**63)".

   **Detalles de implementación de CPython:** "tomllib" uses Python's
   limit on integer string conversion (4300 digits by default).

Floats
   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.

   **Detalles de implementación de CPython:** "tomllib" uses Python
   "float" by default; on many common platforms this is the
   recommended binary64. See "sys.float_info" for details.

Nesting limit
   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.)

   **Detalles de implementación de CPython:** In "tomllib", the
   nesting level is mainly limited by Python's "recursion limit". Note
   that code that calls "tomllib" may contribute to the limit.
