iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 680: link discuss post, minor edits (#2226) 

Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Shantanu 2022-01-12 02:57:51 -08:00 committed by GitHub
parent 57c9a36dca
commit 6714cfed8a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 33 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/CODEOWNERS vendored
View File

@ -535,6 +535,7 @@ pep-0676.rst @Mariatta
pep-0677.rst @gvanrossum pep-0677.rst @gvanrossum
pep-0678.rst @iritkatriel pep-0678.rst @iritkatriel
pep-0679.rst @pablogsal pep-0679.rst @pablogsal
pep-0680.rst @encukou
# ... # ...
# pep-0754.txt # pep-0754.txt
# ... # ...

71
pep-0680.rst
View File

@ -1,14 +1,14 @@
PEP: 680 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 <hauntsaninja at gmail.com> Author: Taneli Hukkinen, Shantanu Jain <hauntsaninja at gmail.com>
Sponsor: Petr Viktorin <encukou@gmail.com> Sponsor: Petr Viktorin <encukou@gmail.com>
Discussions-To: https://discuss.python.org/t/adopting-recommending-a-toml-parser/4068 Discussions-To: https://discuss.python.org/t/13040
Status: Draft Status: Draft
Type: Standards Track Type: Standards Track
Content-Type: text/x-rst Content-Type: text/x-rst
Created: 01-Jan-2022 Created: 01-Jan-2022
Python-Version: 3.11 Python-Version: 3.11
Post-History: 1900-01-01 Post-History: 11-Jan-2022
Abstract Abstract
@ -189,35 +189,31 @@ Rejected Ideas
Basing on another TOML implementation 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 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 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. the standard library.
* ``toml``. * ``toml`` is a very widely used library. However, it is not actively
``toml`` is a widely used library. However, it is not actively maintained, maintained, does not support TOML v1 and has several known bugs. Its API is
does not support TOML v1 and has several known bugs. Its API is more complex more complex than that of ``tomli``. It has some very limited and mostly
than that of ``tomli``. It has some very limited and mostly unused ability to unused ability to preserve style through an undocumented decoder API. It has
preserve style through an undocumented decoder API. It has the ability to the ability to customise output style through a complicated encoder API. For
customise output style through a complicated encoder API. For more details on more details on API differences to this PEP, refer to `Appendix A`_.
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. 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``. similar shortcomings to ``pytomlpp``.
In addition, it does not support TOML v1. In addition, it does not support TOML v1.
* Writing from scratch. * Writing an implementation from scratch. It's unclear what we would get from
It's unclear what we would get from this: ``tomli`` meets our needs and the this: ``tomli`` meets our needs and the author is willing to help with its
author is willing to help with its inclusion in the standard library. inclusion in the standard library.
Including an API for writing TOML 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: 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 ``tomllib.loads`` does not intend to load a TOML file, but rather the
document that the file stores. The most natural representation of 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 <https://github.com/uiri/toml/issues/361>`__, been unable to contact the author <https://github.com/uiri/toml/issues/361>`__,
so action here would likely have to be taken without the author's consent. so action here would likely have to be taken without the author's consent.
This PEP proposes ``tomllib``. This mirrors ``plistlib`` (another file format This PEP proposes ``tomllib``. This mirrors ``plistlib`` and ``xdrlib`` (two
module in the standard library), as well as several others such as ``pathlib``, other file format modules in the standard library), as well as several others
``graphlib``, etc. such as ``pathlib``, ``contextlib``, ``graphlib``, etc.
Other considered names include: Other considered names include:
@ -356,22 +352,14 @@ Other considered names include:
``marshal``, ``html`` etc. would not be included in the namespace. ``marshal``, ``html`` etc. would not be included in the namespace.
TODO: Random things Previous Discussion
=================== ===================
Previous discussion:
* https://bugs.python.org/issue40059 * 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://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 * https://discuss.python.org/t/adopting-recommending-a-toml-parser/4068/84
* https://github.com/hukkin/tomli/issues/141
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
.. _Appendix A: .. _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 code that uses ``toml`` to use the API proposed in this PEP (acknowledging
that that is very different from a compatible API). 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" <https://grep.app/search?q=toml.load&filter[lang][0]=Python>`__
to `occurences of "toml.dump" <https://grep.app/search?q=toml.dump&filter[lang][0]=Python>`__.
#. Different first argument of ``toml.load`` #. 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 sequences, and hence is simply stricter format than what text file objects
represent. 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" <https://grep.app/search?q=toml.load&filter[lang][0]=Python>`__.
#. Errors #. Errors
``toml`` raises ``TomlDecodeError`` vs the proposed PEP 8 compliant ``toml`` raises ``TomlDecodeError`` vs the proposed PEP 8 compliant
``TOMLDecodeError``. ``TOMLDecodeError``.
A significant fraction of ``toml`` users rely on this. A significant fraction of ``toml`` users rely on this, based on `occurrences
of "TomlDecodeError"
<https://grep.app/search?q=TomlDecodeError&case=true&filter[lang][0]=Python>`__.
#. ``toml.load[s]`` accepts a ``_dict`` argument #. ``toml.load[s]`` accepts a ``_dict`` argument