marshal — 내부 Python 객체 직렬화

---

이 모듈에는 Python 값을 이진 형식으로 읽고 쓸 수 있는 함수가 들어 있습니다. 이 형식은 Python 전용이지만, 머신 아키텍처 문제와는 무관합니다(예를 들어 PC의 파일에 Python 값을 기록한 뒤 그 파일을 Mac으로 옮겨 այնտեղ에서 다시 읽을 수 있습니다). 형식의 세부 사항은 의도적으로 문서화되어 있지 않습니다. Python 버전 사이에서 변경될 수 있기 때문입니다(드물기는 하지만). [1]

이것은 일반적인 “영속성” 모듈이 아닙니다. RPC 호출을 통한 Python 객체의 일반적인 영속성과 전송에는 pickle 및 shelve 모듈을 참조하세요. marshal 모듈은 주로 Python 모듈의 .pyc 파일에 대한 “의사 컴파일된” 코드를 읽고 쓰는 기능을 지원하기 위해 존재합니다. 따라서 필요가 생기면 Python 유지관리자는 하위 호환되지 않는 방식으로 marshal 형식을 수정할 권리를 보유합니다. 코드 객체의 형식은 형식 버전이 같더라도 Python 버전 간에 호환되지 않습니다. 잘못된 Python 버전에서 코드 객체를 역직렬화하면 동작이 정의되어 있지 않습니다. Python 객체를 직렬화하고 역직렬화하려는 경우에는 대신 pickle 모듈을 사용하세요. 성능은 비슷하고, 버전 독립성이 보장되며, pickle은 marshal보다 훨씬 더 넓은 범위의 객체를 지원합니다.

Warning

marshal 모듈은 잘못되었거나 악의적으로 구성된 데이터에 대해 안전하도록 설계되지 않았습니다. 신뢰할 수 없거나 인증되지 않은 출처에서 받은 데이터는 절대 unmarshal하지 마세요.

파일을 읽고 쓰는 함수와 bytes류 객체에서 동작하는 함수가 모두 있습니다.

모든 Python 객체 타입이 지원되는 것은 아닙니다. 일반적으로 특정 Python 실행과 무관한 값만 이 모듈로 쓰고 읽을 수 있습니다. 다음 타입이 지원됩니다:

• 숫자형 타입: int, bool, float, complex.

• 문자열(str)과 bytes. bytearray 같은 bytes류 객체는 bytes로 marshal됩니다.

• 컨테이너: tuple, list, set, frozenset, 그리고 (version 5부터) slice. 여기에 포함된 값 자체도 지원되는 경우에만 이들이 지원된다는 점을 이해해야 합니다. 재귀적 컨테이너는 version 3부터 지원됩니다.

• 싱글턴 None, Ellipsis, StopIteration.

• allow_code 가 참이면 code 객체. 버전 의존성에 대한 위의 참고를 보세요.

Changed in version 3.4:

• 재귀적 리스트, 집합, 딕셔너리의 marshal을 지원하는 형식 버전 3이 추가되었습니다.

• 짧은 문자열의 효율적인 표현을 지원하는 형식 버전 4가 추가되었습니다.

Changed in version 3.14: slice의 marshal을 허용하는 형식 버전 5가 추가되었습니다.

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

marshal.dump(value, file, version=version, /, *, allow_code=True)¶ 열린 파일에 값을 씁니다. 값은 지원되는 타입이어야 합니다. 파일은 쓰기 가능한 바이너리 파일이어야 합니다.

값이 지원되지 않는 타입이거나(또는 그런 객체를 포함하고 있으면) ValueError 예외가 발생합니다. 하지만 쓰레기 데이터도 파일에 기록됩니다. 그러면 객체를 load()로 올바르게 다시 읽어올 수 없습니다. 코드 객체는 allow_code 가 참일 때만 지원됩니다.

version 인수는 dump가 사용할 데이터 형식을 나타냅니다(아래 참조).

인수 value, version으로 감사 이벤트marshal.dumps를 발생시킵니다.

Changed in version 3.13: allow_code 매개변수가 추가되었습니다.

marshal.load(file, /, *, allow_code=True)¶ 열린 파일에서 값 하나를 읽어 반환합니다. 유효한 값을 읽지 못하면(예: 데이터가 다른 Python 버전의 호환되지 않는 marshal 형식인 경우) EOFError, ValueError 또는 TypeError를 발생시킵니다. 코드 객체는 allow_code 가 참일 때만 지원됩니다. 파일은 읽기 가능한 바이너리 파일이어야 합니다.

인수 없이 감사 이벤트marshal.load를 발생시킵니다.

Note

지원되지 않는 타입을 포함한 객체가 dump()로 marshal되었다면, load()는 marshal 해제할 수 없는 타입 대신 None을 대입합니다.

Changed in version 3.10: 이 호출은 예전에는 각 코드 객체마다 code.__new__ 감사 이벤트를 발생시켰습니다. 이제는 전체 load 작업에 대해 단일 marshal.load 이벤트를 발생시킵니다.

Changed in version 3.13: allow_code 매개변수가 추가되었습니다.

marshal.dumps(value, version=version, /, *, allow_code=True)¶ dump(value, file)이 파일에 쓸 bytes 객체를 반환합니다. 값은 지원되는 타입이어야 합니다. 값이 지원되지 않는 타입이거나(또는 그런 객체를 포함하고 있으면) ValueError 예외를 발생시킵니다. 코드 객체는 allow_code 가 참일 때만 지원됩니다.

version 인수는 dumps가 사용할 데이터 형식을 나타냅니다(아래 참조).

인수 value, version으로 감사 이벤트marshal.dumps를 발생시킵니다.

Changed in version 3.13: allow_code 매개변수가 추가되었습니다.

marshal.loads(bytes, /, *, allow_code=True)¶ bytes류 객체를 값으로 변환합니다. 유효한 값을 찾지 못하면 EOFError, ValueError 또는 TypeError를 발생시킵니다. 코드 객체는 allow_code 가 참일 때만 지원됩니다. 입력에 남아 있는 추가 바이트는 무시됩니다.

인수 bytes로 감사 이벤트marshal.loads를 발생시킵니다.

Changed in version 3.10: 이 호출은 예전에는 각 코드 객체마다 code.__new__ 감사 이벤트를 발생시켰습니다. 이제는 전체 load 작업에 대해 단일 marshal.loads 이벤트를 발생시킵니다.

Changed in version 3.13: allow_code 매개변수가 추가되었습니다.

추가로, 다음 상수가 정의되어 있습니다:

marshal.version¶ 모듈이 사용하는 형식을 나타냅니다. 버전 0은 역사적인 첫 번째 버전이며, 이후 버전들은 새 기능을 추가합니다. 일반적으로 새 버전은 도입될 때 기본값이 됩니다.

Footnotes