`tomllib` — TOML 파일 파싱¶

소스 코드: Lib/tomllib

이 모듈은 TOML 1.1.0(Tom’s Obvious Minimal Language, https://toml.io)을 파싱하기 위한 인터페이스를 제공합니다. 이 모듈은 TOML 작성을 지원하지 않습니다.

Added in version 3.11: 이 모듈은 TOML 1.0.0 지원과 함께 추가되었습니다.

버전 3.15에서 변경: TOML 1.1.0 지원이 추가되었습니다. 자세한 내용은 What’s New 를 참조하십시오.

경고

신뢰할 수 없는 소스에서 데이터를 파싱할 때 주의하십시오. 악의적인 TOML 문자열은 디코더가 상당한 CPU 및 메모리 리소스를 소모하게 만들 수 있습니다. 파싱할 데이터의 크기를 제한하는 것을 권장합니다.

Tomli-W 패키지 는 이 모듈과 함께 사용할 수 있는 TOML 작성기이며, 표준 라이브러리 marshal 및 pickle 모듈 사용자에게 익숙한 쓰기 API를 제공합니다.

TOML Kit 패키지 는 읽기와 쓰기 기능이 모두 있는 스타일 유지형 TOML 라이브러리입니다. 이미 존재하는 TOML 파일을 편집하는 경우 이 모듈을 대체할 수 있는 권장되는 도구입니다.

모듈은 다음 함수들을 정의합니다:

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

TOML 파일을 읽습니다. 첫 번째 인자는 읽기 가능하고 바이너리인 파일 객체여야 합니다. dict 를 반환합니다. TOML 타입을 파이썬으로 변환하려면 이 변환표 를 사용하십시오.

parse_float 는 디코딩될 모든 TOML 플로트의 문자열과 함께 호출됩니다. 기본적으로 이는 float(num_str) 와 동일합니다. 이 기능을 사용하여 TOML 플로트에 대해 다른 데이터 타입이나 파서(예: decimal.Decimal)를 사용할 수 있습니다. 호출 가능한 함수는 dict 나 list 를 반환해서는 안 되며, 그렇지 않으면 ValueError 가 발생합니다.

유효하지 않은 TOML 문서에 대해서는 TOMLDecodeError 가 발생합니다.

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

str 객체에서 TOML을 로드합니다. dict 를 반환합니다. TOML 타입을 파이썬으로 변환하려면 이 변환표 를 사용하십시오. parse_float 인자는 load() 에서와 동일한 의미를 가집니다.

유효하지 않은 TOML 문서에 대해서는 TOMLDecodeError 가 발생합니다.

다음과 같은 예외를 사용할 수 있습니다:

exception tomllib.TOMLDecodeError(msg, doc, pos)¶

다음 추가 어트리뷰트를 가진 ValueError 의 서브 클래스입니다.

msg¶: 포맷되지 않은 에러 메시지입니다.

doc¶: 파싱 중인 TOML 문서입니다.

pos¶: 구문 분석에 실패한 doc 의 인덱스입니다.

lineno¶: pos 에 해당하는 줄입니다.

colno¶: pos 에 해당하는 열입니다.

버전 3.14에서 변경: msg, doc, pos 매개변수가 추가되었습니다. msg, doc, pos, lineno, colno 어트리뷰트가 추가되었습니다.

버전 3.14부터 폐지됨: 자유 형식의 위치 인자를 전달하는 방식은 폐지되었습니다.

예시¶

TOML 파일 파싱:

import tomllib

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

TOML 문자열 파싱:

import tomllib

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

data = tomllib.loads(toml_str)

변환표¶

TOML	Python
TOML 문서	dict
문자열(String)	str
정수	int 자료형은 정수 값을 표현하며, 크기 예측에 사용됩니다.
플로트	플로트 (parse_float 로 설정 가능)
불리언	bool
오프셋 날짜/시간	datetime.datetime (`tzinfo` 어트리뷰트가 `datetime.timezone` 인스턴스로 설정됨)
로컬 날짜/시간	datetime.datetime (`tzinfo` 어트리뷰트가 `None` 으로 설정됨)
로컬 날짜	datetime.date
로컬 시간	datetime.time
배열(array)	리스트(list)
테이블	dict
인라인 테이블	dict
테이블 배열	딕셔너리 리스트

제한 사항 및 상호 운용성 고려 사항¶

tomllib 은 처리할 수 있는 문서에 몇 가지 제한을 두며, 다른 TOML 파서가 무시해도 되는 세부 정보를 유지합니다. 이식 가능한 TOML 파일을 작성할 때는 표준에서 보장하거나 권장하는 기능만 사용하십시오.

여기에 나열된 구현 세부 사항은 향후 파이썬 버전에서 변경될 수 있습니다.

테이블/딕셔너리: TOML 사양은 TOML 문서 및 테이블의 키/값 쌍이 특정 순서로 배치되는 것을 보장하지 않습니다.

tomllib 은 소스에 나타나는 순서대로 딕셔너리 항목을 로드합니다.
정수: TOML은 range(−2**63, 2**63) 범위의 정수를 지원할 것을 권장합니다.

tomllib 은 Python’s limit on integer string conversion (기본값 4,300자리)를 사용합니다.
부동 소수점: TOML은 최소한 IEEE 754 binary64 값을 지원할 것을 권장하며, 이는 의미 있는 10진수 자릿수가 15자를 초과하는 숫자는 반올림될 가능성이 있음을 의미합니다.

tomllib 은 기본적으로 파이썬 float 를 사용합니다. 많은 일반적인 플랫폼에서 이는 권장되는 binary64입니다. 자세한 내용은 sys.float_info 를 참조하십시오.
중첩 제한: TOML 1.1.0은 배열과 테이블이 서로 얼마나 깊게 중첩될 수 있는지에 대한 제한을 권장하지 않습니다. (향후 TOML 버전에서는 100의 제한이 제안되었습니다.)

tomllib 에서 중첩 수준은 주로 파이썬의 recursion limit 에 의해 제한됩니다. tomllib 을 호출하는 코드가 이 제한에 영향을 줄 수 있음에 유의하십시오.

tomllib — TOML 파일 파싱¶

예시¶

변환표¶

제한 사항 및 상호 운용성 고려 사항¶

`tomllib` — TOML 파일 파싱¶