diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d52242858..7f95b9fc8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -535,6 +535,7 @@ pep-0676.rst @Mariatta pep-0677.rst @gvanrossum pep-0678.rst @iritkatriel pep-0679.rst @pablogsal +pep-0680.rst @encukou # ... # pep-0754.txt # ... diff --git a/pep-0680.rst b/pep-0680.rst index 315af1df1..c8f6647ff 100644 --- a/pep-0680.rst +++ b/pep-0680.rst @@ -1,14 +1,14 @@ PEP: 680 -Title: tomllib: Support for parsing TOML in the Standard Library +Title: tomllib: Support for Parsing TOML in the Standard Library Author: Taneli Hukkinen, Shantanu Jain Sponsor: Petr Viktorin -Discussions-To: https://discuss.python.org/t/adopting-recommending-a-toml-parser/4068 +Discussions-To: https://discuss.python.org/t/13040 Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 01-Jan-2022 Python-Version: 3.11 -Post-History: 1900-01-01 +Post-History: 11-Jan-2022 Abstract @@ -189,35 +189,31 @@ Rejected Ideas Basing on another TOML implementation ------------------------------------- -Potential alternatives include: +Several potential alternative implementations exist: -* ``tomlkit``. - ``tomlkit`` is well established, actively maintained and supports TOML v1. An +* ``tomlkit`` is well established, actively maintained and supports TOML v1. An important difference is that ``tomlkit`` supports style roundtripping. As a result, it has a more complex API and implementation (about 5x as much code as - ``tomli``). The author does not believe that ``tomlkit`` is a good choice for + ``tomli``). Its author does not believe that ``tomlkit`` is a good choice for the standard library. -* ``toml``. - ``toml`` is a widely used library. However, it is not actively maintained, - does not support TOML v1 and has several known bugs. Its API is more complex - than that of ``tomli``. It has some very limited and mostly unused ability to - preserve style through an undocumented decoder API. It has the ability to - customise output style through a complicated encoder API. For more details on - API differences to this PEP, refer to `Appendix A`_. +* ``toml`` is a very widely used library. However, it is not actively + maintained, does not support TOML v1 and has several known bugs. Its API is + more complex than that of ``tomli``. It has some very limited and mostly + unused ability to preserve style through an undocumented decoder API. It has + the ability to customise output style through a complicated encoder API. For + more details on API differences to this PEP, refer to `Appendix A`_. -* ``pytomlpp``. - ``pytomlpp`` is a Python wrapper for the C++ project ``toml++``. Pure Python +* ``pytomlpp`` is a Python wrapper for the C++ project ``toml++``. Pure Python libraries are easier to maintain than extension modules. -* ``rtoml``. - ``rtoml`` is a Python wrapper for the Rust project ``toml-rs`` and hence has +* ``rtoml`` is a Python wrapper for the Rust project ``toml-rs`` and hence has similar shortcomings to ``pytomlpp``. In addition, it does not support TOML v1. -* Writing from scratch. - It's unclear what we would get from this: ``tomli`` meets our needs and the - author is willing to help with its inclusion in the standard library. +* Writing an implementation from scratch. It's unclear what we would get from + this: ``tomli`` meets our needs and the author is willing to help with its + inclusion in the standard library. Including an API for writing TOML --------------------------------- @@ -277,7 +273,7 @@ a text string. This may seem inconsistent at first. Quoting TOML v1.0.0 specification: -> A TOML file must be a valid UTF-8 encoded Unicode document. + A TOML file must be a valid UTF-8 encoded Unicode document. ``tomllib.loads`` does not intend to load a TOML file, but rather the document that the file stores. The most natural representation of @@ -342,9 +338,9 @@ Finally, the ``toml`` package on PyPI is not actively maintained and `we have been unable to contact the author `__, so action here would likely have to be taken without the author's consent. -This PEP proposes ``tomllib``. This mirrors ``plistlib`` (another file format -module in the standard library), as well as several others such as ``pathlib``, -``graphlib``, etc. +This PEP proposes ``tomllib``. This mirrors ``plistlib`` and ``xdrlib`` (two +other file format modules in the standard library), as well as several others +such as ``pathlib``, ``contextlib``, ``graphlib``, etc. Other considered names include: @@ -356,22 +352,14 @@ Other considered names include: ``marshal``, ``html`` etc. would not be included in the namespace. -TODO: Random things +Previous Discussion =================== -Previous discussion: - * https://bugs.python.org/issue40059 -* https://mail.python.org/archives/list/python-ideas@python.org/thread/IWJ3I32A4TY6CIVQ6ONPEBPWP4TOV2V7/ * https://mail.python.org/pipermail/python-dev/2019-May/157405.html -* https://github.com/hukkin/tomli/issues/141 +* https://mail.python.org/archives/list/python-ideas@python.org/thread/IWJ3I32A4TY6CIVQ6ONPEBPWP4TOV2V7/ * https://discuss.python.org/t/adopting-recommending-a-toml-parser/4068/84 - -Useful https://grep.app searches (note, ignore vendored): - -* toml.load[s] usage https://grep.app/search?q=toml.load&filter[lang][0]=Python -* toml.dump[s] usage https://grep.app/search?q=toml.dump&filter[lang][0]=Python -* TomlEncoder subclasses https://grep.app/search?q=TomlEncoder%29%3A&filter[lang][0]=Python +* https://github.com/hukkin/tomli/issues/141 .. _Appendix A: @@ -394,7 +382,9 @@ space. Note that this list might not be exhaustive. code that uses ``toml`` to use the API proposed in this PEP (acknowledging that that is very different from a compatible API). - A significant fraction of ``toml`` users rely on this. + A significant fraction of ``toml`` users rely on this, based on comparing + `occurrences of "toml.load" `__ + to `occurences of "toml.dump" `__. #. Different first argument of ``toml.load`` @@ -422,14 +412,17 @@ space. Note that this list might not be exhaustive. sequences, and hence is simply stricter format than what text file objects represent. - A significant fraction of ``toml`` users rely on this. + A significant fraction of ``toml`` users rely on this, based on manual inspection + of `occurrences of "toml.load" `__. #. Errors ``toml`` raises ``TomlDecodeError`` vs the proposed PEP 8 compliant ``TOMLDecodeError``. - A significant fraction of ``toml`` users rely on this. + A significant fraction of ``toml`` users rely on this, based on `occurrences + of "TomlDecodeError" + `__. #. ``toml.load[s]`` accepts a ``_dict`` argument