PEP 680 – 표준 라이브러리에서 TOML 구문 분석을 지원하는 tomllib

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은 Python 패키징에서 선택되는 형식이며, PEP 517, PEP 518 및 PEP 621에서 입증됩니다. 이로 인해 Python 빌드 도구에는 부트스트래핑 문제가 발생하여 TOML 구문 분석 패키지를 벤더링하거나 바람직하지 않은 다른 우회 방법을 사용해야 하며, 패키지를 다시 만드는 사람과 기타 다운스트림 사용자에게 심각한 문제가 발생합니다. 표준 라이브러리에 TOML 지원을 포함하면 이러한 모든 문제가 깔끔하게 해결됩니다.

또한 현재 많은 Python 도구를 TOML을 통해 구성할 수 있으며, black, mypy, pytest, tox, pylint 및 isort 등이 그 예입니다. flake8과 같이 그렇지 않은 많은 도구는 표준 라이브러리 지원의 부재를 주된 이유로 언급합니다. Python 생태계에서 TOML이 이미 특별한 위치를 차지하고 있다는 점을 고려하면, 이를 기본 포함 구성 요소로 제공하는 것이 타당합니다.

마지막으로 TOML은 형식으로서 점점 더 인기를 얻고 있으며(PEP 518에 설명된 이유 때문입니다), PyPI에서 다양한 Python TOML 라이브러리가 약 2,000개의 역방향 의존성을 보유하고 있습니다(비교를 위해 requests는 약 28,000개의 역방향 의존성을 보유합니다). 따라서 Python 패키징과 관련 도구의 필요성을 넘어 보더라도 이는 일반적으로 유용한 추가 기능이 될 가능성이 높습니다.

근거

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

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

tomli는 활발하게 유지 관리되고 있으며 충분히 테스트되었습니다. 약 800줄의 코드로 구성되고 테스트 커버리지가 100%이며, proposed official TOML compliance test suite와 더 확립된 the more established BurntSushi/toml-test suite의 모든 테스트를 통과합니다.

사양

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

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 부동 소수점의 원래 문자열 표현을 입력으로 받아 그에 대응하는 Python 객체를 반환하는 호출 가능 객체입니다(json.load의 parse_float와 유사합니다). 예를 들어 정확한 정밀도가 중요한 사용 사례에서는 사용자가 decimal.Decimal을 반환하는 함수를 전달할 수 있습니다. 기본적으로 TOML 부동 소수점은 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이 출시되기 전부터 안정된 형식임이 입증되었습니다. changelog에서 TOML에 2020년 4월 이후 주요 변경 사항이 없었으며, 지난 5년(2017~2021년) 동안 두 차례 출시되었음을 확인할 수 있습니다.

TOML 사양이 변경되는 경우, 사소한 개정은 버그 수정으로 간주하고 구현을 해당 위치에서 업데이트할 수 있습니다. 호환성을 깨뜨리는 중대한 변경이 발생하는 경우에는 TOML 1.x에 대한 지원을 유지해야 합니다.

제안된 구현의 유지 관리성

제안된 구현(tomli)은 순수 Python으로 작성되었고 충분히 테스트되었으며, 코드가 1000줄 미만입니다. 또한 미니멀리즘을 지향하여 다른 TOML 구현보다 작은 API 표면적을 제공합니다.

tomli의 작성자는 표준 라이브러리에 tomli를 통합하고 유지 관리하는 데 기꺼이 협력할 의사가 있으며, 이 게시물에서 밝힌 바와 같습니다. 또한 Python 핵심 개발자인 Petr Viktorin은 읽기 API를 유지 관리할 의향이 있음을 이 게시물에서 밝혔습니다.

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

TOML 지원은 다른 항목으로 이어지는 미끄러운 경사입니다.

Motivation 섹션에서 논의한 것처럼 TOML은 PEP 518 pyproject.toml 패키징 및 도구 구성 파일을 읽기 위해 Python 생태계에서 특별한 위치를 차지합니다. TOML을 표준 라이브러리에 포함해야 하는 이 핵심 이유는 YAML이나 MessagePack과 같은 다른 형식에는 적용되지 않습니다.

또한 TOML의 단순성은 TOML을 구성하고 파싱하기가 매우 복잡한 YAML과 같은 다른 형식과 구별합니다.

그러나 향후 PEP에서 TOML을 작성하기 위한 API가 추가될 수 있습니다.

하위 호환성

이 제안은 새로운 모듈을 설명하므로 표준 라이브러리 내에서 하위 호환성 문제가 없습니다. tomllib라는 이름의 기존 서드파티 모듈은 import 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 차이에 대한 자세한 내용은 Appendix A 를 참조하십시오.
• pytomlpp는 C++ 프로젝트 toml++를 위한 Python 래퍼입니다. 순수 Python 라이브러리는 확장 모듈보다 유지 관리하기 쉽습니다.
• rtoml은 Rust 프로젝트 toml-rs를 위한 Python 래퍼이므로 pytomlpp와 유사한 단점이 있습니다. 또한 TOML 1.0.0을 지원하지 않습니다.
• 처음부터 구현 작성하기 이를 통해 무엇을 얻게 될지는 불분명합니다. tomli는 우리의 요구를 충족하며 작성자는 이를 표준 라이브러리에 포함하는 일을 기꺼이 돕고자 합니다.

TOML 작성을 위한 API 포함하기

TOML 작성을 위한 API를 포함하지 않을 이유가 몇 가지 있습니다.

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

기존 TOML 파일을 편집하는 사용 사례는 (새 파일을 처음부터 작성하는 것과 달리) 스타일을 보존하는 라이브러리를 사용하는 편이 더 적합합니다. TOML은 사람이 읽고 편집할 수 있는 구성 형식이므로 주석, 서식 및 기타 마크업을 보존하는 것이 중요합니다. 이를 위해서는 출력에 스타일 관련 메타데이터가 포함되는 파서가 필요하므로 str및 dict같은 일반 Python 타입을 출력하기가 어렵습니다. 또한 API 설계가 상당히 복잡해집니다.

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

현재 어떤 CPython 핵심 개발자도 쓰기 API를 유지 관리하거나 이를 포함하는 PEP를 후원하겠다는 의사를 표명하지 않았습니다. 표준 라이브러리의 무언가를 변경하거나 제거하기는 어려우므로, 지금은 일단 제외하는 쪽으로 신중하게 판단하고 나중에 이를 다시 검토하는 편이 더 안전합니다.

따라서 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 specification에서 인용하면 다음과 같습니다.

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

tomllib.loads는 TOML 파일을 로드하려는 것이 아니라 파일에 저장된 문서를 로드하려는 것입니다. Python에서 유니코드 문서의 가장 자연스러운 표현은 str이며 bytes가 아닙니다.

필요하다면 향후 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 부동 소수점 수는 “IEEE 754 binary64 values”로 구현되어야 하며, 이는 대부분의 아키텍처에서 Python float와 동등하기 때문입니다.

그러나 TOML 사양은 “SHOULD”라는 단어를 사용하므로, 정당한 이유가 있으면 무시할 수 있는 권고임을 의미합니다. 부동 소수점 수를 다르게, 예를 들어 decimal.Decimal로 구문 분석하면 사용자가 TOML 형식이 보장하는 것보다 더 높은 정밀도를 사용할 수 있습니다. tomli의 작성자 경험상 이는 과학 및 금융 애플리케이션에서 특히 유용합니다. 더 높은 정밀도가 필요한 다른 경우나 최종 사용자 중 이진64 부동 소수점 수의 한계를 인지하지 못할 수 있는 비개발자가 포함된 경우에도 유용합니다.

Python float가 IEEE 754 binary64 값이 아닌 틈새 아키텍처도 있습니다. parse_float 인자를 사용하면 이러한 아키텍처에서도 사용자가 올바른 TOML 의미 체계를 구현할 수 있습니다.

모듈의 대체 이름

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

그러나 PyPI의 toml 패키지는 널리 사용되고 있으므로 하위 호환성 문제가 있습니다. 표준 라이브러리가 서드파티 패키지보다 우선하므로, 현재 toml 패키지에 의존하는 라이브러리와 애플리케이션은 종속성 버전을 고정하더라도 Appendix 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] Python 표준 라이브러리 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 사용자 중 상당수가 occurrences of “toml.load”와 occurrences of “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 사용자 중 상당수가 occurrences of “toml.load”를 수동으로 검사한 결과에 근거하여 이 기능에 의존합니다.

3. 오류

   toml은 제안된 PEP 8-compliant TOMLDecodeError와 달리 TomlDecodeError를 발생시킵니다.

   toml 사용자 중 상당수가 occurrences of “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 interface은 메서드가 9개나 포함되어 있어 결코 단순하지 않습니다.

   사용자는 스타일을 보존하는 구문 분석 및 쓰기를 보다 완전하게 구현한 방식으로 더 나은 지원을 받을 가능성이 높습니다.

6. toml.dump[s]는 encoder 인자를 지원합니다.

   현재는 쓰기 API를 포함하지 않을 것을 제안하고 있다는 점에 유의하십시오. 그러나 이것이 변경된다면 이러한 차이가 관련성을 갖게 될 가능성이 높습니다.

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

   • 사용자 정의 형식을 직렬화하는 방법을 제어하는 것과
   • 출력 형식을 지정하는 방법을 제어하는 것입니다.

   첫 번째 방식은 합리적이지만, https://grep.app에서 이에 해당하는 사례를 두 개만 찾을 수 있었습니다. 이 두 사례 중 하나는 이 기능을 사용하여 decimal.Decimal 덤핑 지원을 추가했지만, 잠재적인 표준 라이브러리 구현에서는 이를 기본적으로 지원할 것입니다. 다른 형식에 필요한 경우에는 json.dump의 default 인자에 해당하는 기능으로 이 사용 사례를 충분히 지원할 수 있습니다.

   두 번째 사용 사례는 사용자가 toml.TomlEncoder의 서브클래스를 지정하고 메서드를 재정의하여 TOML 쓰기 과정의 일부를 지정하도록 허용함으로써 가능합니다. API는 5개의 메서드로 구성되며 구현 세부 사항을 상당 부분 노출합니다.

   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.