PEP 680 – tomllib: 표준 라이브러리에서 TOML 파싱 지원

Author:

Taneli Hukkinen, Shantanu Jain <hauntsaninja at gmail.com>

Sponsor:

Petr Viktorin <encukou at gmail.com>

Discussions-To:

Discourse thread

Status:

Final

Type:

Standards Track

Created:

01-Jan-2022

Python-Version:

3.11

Post-History:

09-Dec-2021, 27-Jan-2022

Resolution:

Python-Dev thread

---

Table of Contents

• 초록
• 동기
• 근거
• 명세
• 유지 관리에 미치는 영향
  • TOML의 안정성
  • 제안된 구현의 유지 보수성
  • TOML 지원이 다른 것들을 위한 미끄러운 경사길이 된다는 우려
• 하위 호환성
• 보안 영향
• 교육 방법
• 참조 구현
• 기각된 아이디어
  • 다른 TOML 구현을 기반으로 하는 방안
  • TOML 쓰기 API를 포함하는 방안
  • 기타 API 세부 사항
    • tomllib.load의 첫 번째 인자로 허용되는 타입
    • tomllib.loads의 첫 번째 인자로 허용되는 타입
  • tomllib.load[s]가 반환하는 매핑의 타입 제어
  • tomllib.load[s]에서 parse_float 지원 제거
  • 모듈의 대안 이름
• 이전 논의
• 부록 A: 제안된 API와 toml의 차이점
• Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at tomllib.

×

See PEP 1 for how to propose changes.

초록

이 PEP는 TOML(Tom’s Obvious Minimal Language, https://toml.io)을 파싱하기 위한 tomllib 모듈을 표준 라이브러리에 추가할 것을 제안합니다.

동기

TOML은 PEP 517, PEP 518, PEP 621에서 볼 수 있듯이 Python 패키징에서 선택된 형식입니다. 이로 인해 Python 빌드 도구에는 부트스트래핑 문제가 생기며, 이 도구들은 TOML 파싱 패키지를 벤더링하거나 다른 바람직하지 않은 우회 방법을 써야 합니다. 또한 재패키징하는 사람들과 기타 다운스트림 소비자에게도 심각한 문제가 발생합니다. 표준 라이브러리에 TOML 지원을 포함하면 이 모든 문제를 깔끔하게 해결할 수 있습니다.

또한 이제 black, mypy, pytest, tox, pylint, isort 등 많은 Python 도구를 TOML로 설정할 수 있습니다. flake8 등 그렇지 않은 도구 중 다수는 표준 라이브러리 지원이 없다는 점을 주된 이유로 꼽습니다. TOML이 이미 Python 생태계에서 특별한 위치를 차지하고 있다는 점을 고려하면, TOML을 기본 포함 기능(included battery)으로 제공하는 것이 합리적입니다.

마지막으로, TOML은 (PEP 518에 설명된 이유로) 형식으로서 점점 더 인기를 얻고 있으며, 여러 Python TOML 라이브러리는 PyPI에서 약 2000개의 역의존성을 가지고 있습니다(비교하자면 requests는 약 28000개의 역의존성을 가지고 있습니다). 따라서 Python 패키징과 관련 도구의 필요를 넘어서더라도, 이는 전반적으로 유용한 추가 기능이 될 가능성이 높습니다.

근거

이 PEP는 TOML 읽기를 위한 표준 라이브러리 지원을 서드파티 라이브러리 tomli(github.com/hukkin/tomli)에 기반하여 구현할 것을 제안합니다.

pip, build, pytest, mypy, black, flit, coverage, setuptools-scm, cibuildwheel 등 많은 프로젝트가 최근 tomli로 전환했습니다.

tomli는 활발히 유지 관리되고 있으며 충분히 테스트되었습니다. 약 800줄의 코드로 이루어져 있고 테스트 커버리지는 100%이며, 제안된 공식 TOML 준수 테스트 스위트뿐만 아니라 더 자리 잡은 BurntSushi/toml-test 스위트의 모든 테스트도 통과합니다.

명세

새 모듈 tomllib이 Python 표준 라이브러리에 추가되며, 다음과 같은 공개 함수를 제공합니다:

def load(
    fp: SupportsRead[bytes],
    /,
    *,
    parse_float: Callable[[str], Any] = ...,
 ) -> dict[str, Any]: ...

def loads(
    s: str,
    /,
    *,
    parse_float: Callable[[str], Any] = ...,
) -> dict[str, Any]: ...

tomllib.load는 TOML 문서를 담은 바이너리 파일 형태의 객체를 Python dict로 역직렬화합니다. fp 인자는 io.RawIOBase.read()와 같은 API를 가진 read() 메서드를 가져야 합니다.

tomllib.loads는 TOML 문서를 담은 str 인스턴스를 Python dict로 역직렬화합니다.

parse_float 인자는 TOML float의 원래 문자열 표현을 입력으로 받아 그에 대응하는 Python 객체를 반환하는 호출 가능 객체입니다(json.load의 parse_float와 유사합니다). 예를 들어 정확한 정밀도가 중요한 사용 사례에서는 사용자가 decimal.Decimal을 반환하는 함수를 전달할 수 있습니다. 기본적으로 TOML float는 Python float 타입의 인스턴스로 파싱됩니다.

반환되는 객체에는 기본 Python 객체(str, int, bool, float, datetime.{datetime,date,time}, list, 문자열 키를 가진 dict)와 parse_float의 결과만 포함됩니다.

유효하지 않은 TOML인 경우 tomllib.TOMLDecodeError가 발생합니다.

이 PEP는 tomllib.dump나 tomllib.dumps 함수를 제안하지 않는다는 점에 유의하십시오. 자세한 내용은 Including an API for writing TOML을 참고하십시오.

유지 관리에 미치는 영향

TOML의 안정성

2021년 1월 TOML 1.0.0이 출시되었으므로, 이제 TOML 형식은 공식적으로 안정된 형식으로 간주해야 합니다. 경험적으로 보면 TOML은 TOML 1.0.0이 출시되기 전부터 이미 안정된 형식임이 입증되었습니다. 변경 로그를 보면 TOML은 2020년 4월 이후로 큰 변경이 없었으며, 지난 5년간(2017-2021) 두 차례 릴리스되었음을 알 수 있습니다.

TOML 명세가 변경되는 경우, 사소한 개정은 버그 수정으로 취급하여 구현을 그 자리에서 갱신할 수 있습니다. 호환성을 깨는 큰 변경이 있는 경우에는 TOML 1.x 지원을 유지해야 합니다.

제안된 구현의 유지 보수성

제안된 구현(tomli)은 순수 Python이며, 충분히 테스트되었고, 코드 규모가 1000줄 미만입니다. 최소주의적인 구현으로, 다른 TOML 구현보다 API 표면적이 작습니다.

이 게시물에 따르면 tomli의 저자는 tomli를 표준 라이브러리에 통합하고 유지 보수하는 일을 도울 의향이 있습니다. 또한 이 게시물에 따르면, Python 코어 개발자 Petr Viktorin이 읽기 API를 유지 관리할 의향을 밝혔습니다.

현재로서는 파서를 C로 다시 작성할 필요가 없다고 판단합니다. 애플리케이션에서 TOML 파싱이 병목이 되는 경우는 드물며, 더 높은 성능이 필요한 사용자는 서드파티 라이브러리를 사용할 수 있습니다(Python이 표준 라이브러리 C 확장 모듈을 제공함에도 JSON의 경우 이미 흔히 그렇게 하고 있습니다).

TOML 지원이 다른 것들을 위한 미끄러운 경사길이 된다는 우려

Motivation 절에서 논의했듯이, TOML은 PEP 518 pyproject.toml 패키징 및 도구 설정 파일을 읽는 용도로 Python 생태계에서 특별한 위치를 차지하고 있습니다. TOML을 표준 라이브러리에 포함하는 이 주된 이유는 YAML이나 MessagePack 같은 다른 형식에는 해당하지 않습니다.

게다가 TOML은 단순하다는 점에서 생성과 파싱이 매우 복잡한 YAML 같은 다른 형식과 구별됩니다.

다만 TOML을 쓰기 위한 API는 향후 PEP에서 추가될 수 있습니다.

하위 호환성

이 제안은 새로운 모듈을 기술하므로 표준 라이브러리 내에서 하위 호환성 문제가 없습니다. import tomllib이 표준 라이브러리 모듈을 임포트하게 되므로, tomllib이라는 이름의 기존 서드파티 모듈은 모두 동작하지 않게 됩니다. 그러나 tomllib은 PyPI에 등록되어 있지 않으므로, 이 이름의 모듈이 널리 사용되고 있을 가능성은 낮습니다.

현재 toml PyPI 패키지의 버전을 고정해 둔 사용자에게 하위 호환성 영향을 주지 않도록 더 직관적인 이름인 toml은 사용하지 않는다는 점에 유의하십시오. 자세한 내용은 Alternative names for the module 절을 참조하십시오.

보안 영향

구현의 오류는 잠재적인 보안 문제를 일으킬 수 있습니다. 그러나 파서의 출력은 단순한 데이터 타입으로 제한되며, 임의의 클래스를 로드할 수 없으므로 pickle이나 YAML 같은 더 “강력한” 형식에서 흔히 발생하는 보안 문제를 피할 수 있습니다. 또한 구현은 순수 Python으로 작성되므로, 버퍼 오버플로와 같이 C에 고질적인 보안 문제가 줄어듭니다.

교육 방법

tomllib의 API는 json과 pickle 같은 잘 확립된 다른 파일 형식 라이브러리의 API를 본뜹니다. dump 함수가 없는 이유는 문서에서 설명하며, 관련 서드파티 라이브러리(예: tomlkit, tomli-w, pytomlpp)로의 링크를 함께 제공합니다.

참조 구현

제안된 구현은 https://github.com/hukkin/tomli 에서 찾을 수 있습니다.

기각된 아이디어

다른 TOML 구현을 기반으로 하는 방안

대안이 될 수 있는 구현이 몇 가지 있습니다:

• tomlkit은 널리 자리 잡았고, 활발히 유지 보수되고 있으며, TOML 1.0.0을 지원합니다. 중요한 차이점은 tomlkit이 스타일 라운드트리핑을 지원한다는 것입니다. 그 결과 API와 구현이 더 복잡합니다(코드 양이 tomli의 약 5배입니다). 그 저자는 tomlkit이 표준 라이브러리에 적합한 선택이라고 생각하지 않습니다.
• toml은 매우 널리 사용되는 라이브러리입니다. 그러나 활발히 유지 보수되지 않고, TOML 1.0.0을 지원하지 않으며, 알려진 버그가 여럿 있습니다. 그 API는 tomli의 API보다 더 복잡합니다. 복잡한 인코더 API를 통해 출력 스타일을 사용자 정의할 수 있으며, 문서화되지 않은 디코더 API를 통해 입력 스타일을 보존하는, 매우 제한적이고 거의 사용되지 않는 기능도 일부 제공합니다. 이 PEP와의 API 차이점에 대한 자세한 내용은 부록 A를 참고하십시오.
• pytomlpp는 C++ 프로젝트 toml++의 Python 래퍼입니다. 순수 Python 라이브러리는 확장 모듈보다 유지 보수하기 쉽습니다.
• rtoml은 Rust 프로젝트 toml-rs의 Python 래퍼이므로 pytomlpp와 비슷한 단점이 있습니다. 게다가 TOML 1.0.0을 지원하지 않습니다.
• 구현을 처음부터 새로 작성하는 방안. 이렇게 해서 무엇을 얻을 수 있을지 불분명합니다. tomli는 우리의 요구를 충족하며, 그 저자는 tomli를 표준 라이브러리에 포함하는 일을 기꺼이 돕겠다고 했습니다.

TOML 쓰기 API를 포함하는 방안

TOML 쓰기 API를 포함하지 않는 데에는 몇 가지 이유가 있습니다.

이 PEP의 동기가 된 사용 사례, 즉 핵심 Python 패키징 도구와 TOML 설정 파일을 읽어야 하는 프로젝트에는 TOML을 쓰는 기능이 필요하지 않습니다.

(완전히 새로운 파일을 작성하는 것이 아니라) 기존 TOML 파일을 편집하는 사용 사례에는 스타일을 보존하는 라이브러리가 더 적합합니다. TOML은 사람이 읽고 편집할 수 있는 설정 형식을 목표로 하므로, 주석, 서식 및 기타 마크업을 보존하는 것이 중요합니다. 이를 위해서는 출력에 스타일 관련 메타데이터를 포함하는 파서가 필요하며, 그러면 str이나 dict 같은 일반 Python 타입으로 출력하기가 현실적으로 어려워집니다. 게다가 API 설계가 상당히 복잡해집니다.

스타일 보존을 고려하지 않더라도, 쓰기 API를 설계하는 방식에는 자유도가 너무 많습니다. 예를 들어, 라이브러리는 출력에 어떤 기본 스타일(들여쓰기, 수직 및 수평 간격, 따옴표 등)을 사용해야 하며, 사용자에게 그에 대한 제어 권한을 얼마나 주어야 합니까? 라이브러리는 입력 및 출력 유효성 검사를 어떻게 처리해야 합니까? 사용자 정의 타입의 직렬화를 지원해야 합니까? 그렇다면 어떻게 지원해야 합니까? 이러한 문제를 해결할 합리적인 선택지가 있기는 하지만, 표준 라이브러리의 특성상 “제대로 할 기회는 단 한 번”뿐입니다.

현재 쓰기 API를 유지 관리하거나 쓰기 API를 포함하는 PEP를 후원하겠다는 의향을 밝힌 CPython 코어 개발자는 없습니다. 표준 라이브러리에 있는 것은 변경하거나 제거하기 어려우므로, 지금은 포함하지 않는 쪽을 택하고 추후에 다시 검토할 여지를 남겨 두는 것이 더 안전합니다.

따라서 TOML 쓰기는 서드파티 라이브러리에 맡깁니다. 나중에 좋은 API와 관련 사용 사례가 발견되면, 향후 PEP에서 쓰기 지원을 추가할 수 있습니다.

기타 API 세부 사항

tomllib.load의 첫 번째 인자로 허용되는 타입

PyPI의 toml 라이브러리는 load 함수에 경로(그리고 경로류 객체의 리스트도 허용하며, 이 경우 존재하지 않는 파일은 무시하고 문서들을 하나의 객체로 병합합니다)를 전달할 수 있도록 허용합니다. 그러나 여기서 이를 허용하면 json.load, pickle.load 및 기타 표준 라이브러리 함수의 동작과 일관성이 없게 됩니다. 여기서 일관성이 바람직하다는 데 동의한다면, 경로를 허용하는 것은 이 PEP의 범위를 벗어납니다. 이는 사용자 코드에서, 또는 서드파티 라이브러리를 사용하여 쉽고 명시적으로 우회할 수 있습니다.

제안된 API는 바이너리 파일을 받는 반면, toml.load는 텍스트 파일을 받고 json.load는 둘 다 받습니다. 바이너리 파일을 사용하면 사용되는 인코딩이 UTF-8임을 보장할 수 있고(Windows처럼 기본 인코딩이 다른 플랫폼에서도 올바른 파싱을 보장합니다), 텍스트 모드의 범용 줄바꿈 때문에 단독 캐리지 리턴이 포함된 파일을 유효한 TOML로 잘못 파싱하는 일을 피할 수 있습니다.

tomllib.loads의 첫 번째 인자로 허용되는 타입

tomllib.load는 바이너리 파일을 받는 반면, tomllib.loads는 텍스트 문자열을 받습니다. 이는 처음에는 일관성이 없어 보일 수 있습니다.

TOML v1.0.0 명세를 인용하면 다음과 같습니다:

TOML 파일은 유효한 UTF-8로 인코딩된 유니코드 문서여야 합니다.

tomllib.loads는 TOML 파일을 로드하려는 것이 아니라, 그 파일이 저장하고 있는 문서를 로드하려는 것입니다. Python에서 유니코드 문서를 가장 자연스럽게 표현하는 방식은 bytes가 아니라 str입니다.

필요하다면 향후 bytes 지원을 추가할 수 있지만, 저희는 이에 대한 사용 사례를 알지 못합니다.

tomllib.load[s]가 반환하는 매핑의 타입 제어

PyPI의 toml 라이브러리는 load[s] 함수에서 _dict 인자를 받으며, 이는 json.load[s]의 object_hook 인자와 비슷하게 동작합니다. https://grep.app에서 _dict를 사용하는 사례가 여러 건 발견되지만, 거의 모두 _dict=OrderedDict를 전달하고 있으며, 이는 Python 3.7부터는 불필요합니다. 관련 있는 사용 사례는 두 건 발견되었습니다. 한 경우에는 더 친절한 KeyError를 위해 사용자 정의 클래스를 전달했고, 다른 경우에는 사용자 정의 클래스에 몇 가지 추가적인 조회 및 변경 메서드가 있었습니다(예: 점으로 구분된 키 해석을 돕기 위한 메서드).

이러한 매개변수는 Motivation 섹션에서 설명한 핵심 사용 사례에는 필요하지 않습니다. 이 매개변수가 없다는 점은 래퍼 클래스, 변환 함수 또는 서드파티 라이브러리를 사용하여 꽤 쉽게 우회할 수 있습니다. 마지막으로, 나중에 하위 호환성을 유지하는 방식으로 지원을 추가할 수 있습니다.

tomllib.load[s]에서 parse_float 지원 제거

TOML float는 “IEEE 754 binary64 값”으로 구현되어야 하며, 이는 대부분의 아키텍처에서 Python float와 동일하므로, 이 옵션이 꼭 필요한 것은 아닙니다.

그러나 TOML 명세는 “SHOULD”라는 단어를 사용하며, 이는 타당한 이유가 있으면 무시할 수 있는 권고임을 의미합니다. 부동소수점 수를 decimal.Decimal 등으로 다르게 파싱하면, 사용자는 TOML 형식이 보장하는 것 이상의 추가 정밀도를 얻을 수 있습니다. tomli 저자의 경험에 따르면, 이는 과학 및 금융 애플리케이션에서 특히 유용합니다. 이는 더 높은 정밀도가 필요한 다른 경우나, 최종 사용자 중에 binary64 부동소수점 수의 한계를 알지 못할 수 있는 비개발자가 포함된 경우에도 유용합니다.

또한 Python float가 IEEE 754 binary64 값이 아닌 특수한 아키텍처도 존재합니다. parse_float 인자를 사용하면 이러한 아키텍처에서도 올바른 TOML 의미론을 얻을 수 있습니다.

모듈의 대안 이름

이상적으로는 toml이라는 모듈 이름을 사용할 수 있으면 좋을 것입니다.

그러나 PyPI의 toml 패키지는 널리 사용되고 있으므로 하위 호환성 문제가 있습니다. 표준 라이브러리가 서드파티 패키지보다 우선하므로, 현재 toml 패키지에 의존하는 라이브러리와 애플리케이션은 의존성 버전을 고정하더라도 부록 A에 나열된 여러 API 비호환성 때문에 Python 버전을 업그레이드할 때 동작하지 않을 가능성이 높습니다.

좀 더 명확히 하자면, 여기서 가장 우려되는 것은 의존성을 고정한 애플리케이션입니다. 설령 toml PyPI 패키지 이름의 관리 권한을 얻어 제안된 새 모듈의 백포트 용도로 바꾸어 쓸 수 있다 하더라도, 사용자가 기존 toml 패키지의 이전 버전을 고정했는지와 관계없이 이 모듈을 표준 라이브러리에 포함한 새 Python 버전에서는 여전히 사용자의 코드가 동작하지 않게 됩니다. toml 패키지를 (오늘날의 toml과 호환되지 않는) 백포트로 바꾸면서 생기는 호환성을 깨는 변경에 대해 버전 고정이 흔한 대응 방법이 될 가능성이 높으므로, 이는 안타까운 일입니다.

마지막으로, PyPI의 toml 패키지는 활발히 유지 관리되지 않고 있지만, 작성자에게 다른 유지 관리자를 추가해 달라고 요청하려는 노력은 아직까지 성공하지 못했으므로, 이와 관련된 조치는 작성자의 동의 없이 이루어져야 할 가능성이 높습니다.

대신 이 PEP는 tomllib이라는 이름을 제안합니다. 이는 표준 라이브러리의 다른 두 파일 형식 모듈인 plistlib과 xdrlib을 따르며, pathlib, contextlib, graphlib 같은 다른 모듈과도 일관됩니다.

고려했으나 기각된 다른 이름은 다음과 같습니다:

• tomlparser. 이는 configparser를 따르지만, 향후 쓰기 API를 포함하게 된다면 다소 덜 적절할 수 있습니다.
• tomli. 이는 tomli를 구현의 기반으로 사용한다고 가정합니다.
• parser.toml과 같이 어떤 네임스페이스 아래에 두는 toml. 그러나 이는 어색하며, 특히 json, pickle, xml, html 등 기존의 파싱 라이브러리가 그 네임스페이스에 포함되지 않는다는 점에서 더욱 그렇습니다.

이전 논의

• bpo-40059: 표준 라이브러리에 toml 모듈 제공
• [Python-Dev] 표준 라이브러리에 toml 모듈 추가?
• [Python-Ideas] 파이썬 표준 라이브러리 TOML 모듈
• [Packaging] toml 파서 채택/권장?
• hukkin/tomli#141: tomli를 표준 라이브러리에 넣는 것을 고려해 주십시오

부록 A: 제안된 API와 toml의 차이점

이 부록에서는 이 PEP에서 제안하는 API와 서드파티 패키지 toml의 API 사이의 차이점을 다룹니다. 이러한 차이점은 표준 라이브러리 모듈에 toml이라는 이름을 사용할 경우 예상되는 호환성 파손의 정도를 이해하는 데 관련이 있으며, 설계 공간을 더 잘 이해하는 데에도 도움이 됩니다. 이 목록이 완전하지 않을 수 있다는 점에 유의하십시오.

1. 쓰기 API 포함을 제안하지 않음(toml.dump[s] 없음)

   이 PEP는 현재 쓰기 API를 포함하지 않을 것을 제안합니다. 즉, Including an API for writing TOML에서 논의한 바와 같이 toml.dump나 toml.dumps에 해당하는 기능은 없습니다.

   쓰기 API를 포함한다면 toml을 사용하는 대부분의 코드를 새 표준 라이브러리 모듈로 전환하는 일은 비교적 간단할 것입니다(여전히 코드 변경이 필요하므로 호환되는 API와는 매우 다르다는 점은 인정합니다).

   toml 사용자 중 상당수가 이 동작에 의존합니다. 이는 “toml.load”의 등장 횟수와 “toml.dump”의 등장 횟수를 비교한 결과에 근거합니다.

2. toml.load의 다른 첫 번째 인자

   toml.load의 시그니처는 다음과 같습니다:

   def load(
       f: Union[SupportsRead[str], str, bytes, list[PathLike | str | bytes]],
       _dict: Type[MutableMapping[str, Any]] = ...,
       decoder: TomlDecoder = ...,
   ) -> MutableMapping[str, Any]: ...
   

   이는 이 PEP에서 제안하는 첫 번째 인자인 SupportsRead[bytes]와 상당히 다릅니다.

   앞서 Types accepted as the first argument of tomllib.load에서 언급한 그 이유를 다시 정리하면 다음과 같습니다:

   • 경로(심지어 경로의 리스트까지)를 인자로 허용하는 것은 표준 라이브러리의 다른 유사한 함수들과 일관되지 않습니다.
   • SupportsRead[bytes]를 사용하면 인코딩으로 UTF-8이 사용되도록 보장할 수 있고, 단독 캐리지 리턴을 유효한 TOML로 잘못 파싱하는 일을 피할 수 있습니다.

   toml 사용자 중 상당수가 이 동작에 의존합니다. 이는 “toml.load”의 등장 사례를 직접 살펴본 결과에 근거합니다.

3. 오류

   toml은 TomlDecodeError를 발생시키지만, 이 PEP는 PEP 8을 준수하는 TOMLDecodeError를 제안합니다.

   toml 사용자 중 상당수가 이 동작에 의존합니다. 이는 “TomlDecodeError”의 등장 횟수에 근거합니다.

4. toml.load[s]가 받는 _dict 인자

   Controlling the type of mappings returned by tomllib.load[s]에서 논의했습니다.

   그곳에서 언급했듯이, 거의 모든 사용 사례는 _dict=OrderedDict이며, 이는 Python 3.7 이상에서는 필요하지 않습니다.

5. toml.load[s]가 지원하는 문서화되지 않은 decoder 인자

   의도된 사용 사례는 주석 보존을 구현하는 것으로 보입니다. 기록되는 정보는 스타일을 보존하면서 TOML 문서를 왕복 변환하기에 충분하지 않고, 구현에는 알려진 버그가 있으며, 기능이 문서화되어 있지 않고, https://grep.app 에서 이 기능을 사용하는 사례는 단 하나밖에 찾을 수 없었습니다.

   노출된 toml.TomlDecoder 인터페이스는 아홉 개의 메서드를 포함하고 있어 전혀 단순하지 않습니다.

   사용자에게는 스타일을 보존하는 파싱 및 쓰기를 더 완전하게 구현한 것이 더 도움이 될 것입니다.

6. toml.dump[s]가 지원하는 encoder 인자

   현재로서는 쓰기 API를 포함하지 않을 것을 제안하고 있다는 점에 유의하십시오. 그러나 이것이 바뀐다면 이러한 차이점이 중요해질 가능성이 높습니다.

   encoder 인자는 두 가지 사용 사례를 가능하게 합니다:

   • 사용자 정의 타입을 직렬화하는 방식에 대한 제어, 그리고
   • 출력의 서식을 지정하는 방식에 대한 제어입니다.

   첫 번째는 합리적입니다. 그러나 https://grep.app 에서 이러한 사례는 두 개밖에 찾을 수 없었습니다. 이 둘 중 하나는 이 기능을 사용하여 decimal.Decimal을 덤프하는 기능을 추가했는데, 표준 라이브러리에 구현이 들어간다면 이는 기본으로 지원될 것입니다. 다른 타입에 필요하다면, 이 사용 사례는 json.dump의 default 인자에 해당하는 기능으로 충분히 해결할 수 있습니다.

   두 번째 사용 사례는 사용자가 toml.TomlEncoder의 서브클래스를 지정하고 메서드를 오버라이드하여 TOML 쓰기 과정의 일부를 지정할 수 있게 함으로써 가능해집니다. 이 API는 다섯 개의 메서드로 구성되어 있으며 상당한 구현 세부 사항을 노출합니다.

   https://grep.app 에서 encoder API를 사용하는 사례가 일부 있기는 하지만, toml의 전체 사용량 중 극히 일부에 불과한 것으로 보입니다.

7. 시간대

   toml은 자체 정의한 toml.tz.TomlTz 시간대 객체를 사용하며, 이 객체를 외부에 노출합니다. 제안된 구현은 표준 라이브러리의 datetime.timezone 객체를 사용합니다.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.