marshal — Внутрішня серіалізація об’єктів Python

Цей модуль містить функції, які можуть читати та записувати значення Python у двійковому форматі. Формат є специфічним для Python, але не залежить від проблем архітектури машини (наприклад, ви можете записати значення Python у файл на ПК, перенести файл на Sun і прочитати його там). Деталі формату навмисно недокументовані; він може змінюватися між версіями Python (хоча це відбувається рідко). [1]

Це не загальний модуль «постійності». Для загального збереження та передачі об’єктів Python через виклики RPC див. модулі pickle і shelve. Модуль marshal існує головним чином для підтримки читання та запису «псевдокомпільованого» коду для модулів Python файлів .pyc. Тому супроводжувачі Python залишають за собою право змінювати формат маршалу зворотно несумісними способами, якщо виникне така потреба. Якщо ви серіалізуєте та десеріалізуєте об’єкти Python, використовуйте натомість модуль pickle — продуктивність порівнянна, незалежність версії гарантована, а pickle підтримує значно ширший діапазон об’єктів, ніж marshal.

Попередження

Модуль marshal не призначений для захисту від помилкових або зловмисно створених даних. Ніколи не скасовуйте дані, отримані з ненадійного або неавтентифікованого джерела.

Підтримуються не всі типи об’єктів Python; загалом, тільки ті об’єкти, чиє значення не залежить від конкретного виклику Python, можуть бути записані та прочитані цим модулем. Підтримуються такі типи: логічні значення, цілі числа, числа з плаваючою комою, комплексні числа, рядки, байти, байтові масиви, кортежі, списки, набори, заморожені набори, словники та об’єкти коду, де слід розуміти, що кортежі, списки, набори, заморожені набори і словники підтримуються лише до тих пір, поки підтримуються самі значення, які в них містяться. Синглтони None, Ellipsis і StopIteration також можуть бути маршалізованими та немаршалізованими. Для версії формату, нижчої за 3, не можна писати рекурсивні списки, набори та словники (див. нижче).

Існують функції, які читають/записують файли, а також функції, що працюють з байтоподібними об’єктами.

Модуль визначає такі функції:

marshal.dump(value, file[, version])

Запишіть значення у відкритий файл. Значення має бути підтримуваного типу. Файл має бути записуваним binary file.

Якщо значення має (або містить об’єкт, який має) непідтримуваний тип, виникає виняток ValueError — але сміттєві дані також будуть записані у файл. Об’єкт не буде належним чином прочитаний load().

Аргумент version вказує на формат даних, який має використовувати damp (див. нижче).

Викликає подію аудиту marshal.dumps з аргументами значення, версія.

marshal.load(file)

Прочитати одне значення з відкритого файлу та повернути його. Якщо дійсне значення не зчитується (наприклад, через те, що дані мають несумісний маршальний формат іншої версії Python), викликайте EOFError, ValueError або TypeError. Файл має бути читабельним binary file.

Викликає подію аудиту marshal.load без аргументів.

Примітка

Якщо об’єкт, що містить непідтримуваний тип, був маршалований за допомогою dump(), load() замінить None для типу, який не можна маршалювати.

Змінено в версії 3.10: Цей виклик використовувався для виклику події аудиту code.__new__ для кожного об’єкта коду. Тепер він викликає одну подію marshal.load для всієї операції завантаження.

marshal.dumps(value[, version])

Повертає об’єкт bytes, який буде записаний у файл за допомогою dump(value, file). Значення має бути підтримуваного типу. Викликати виняток ValueError, якщо значення має (або містить об’єкт, який має) непідтримуваний тип.

Аргумент version вказує формат даних, який мають використовувати дампи (див. нижче).

Викликає подію аудиту marshal.dumps з аргументами значення, версія.

marshal.loads(bytes)

Перетворіть bytes-like object на значення. Якщо дійсне значення не знайдено, підніміть EOFError, ValueError або TypeError. Зайві байти у вхідних даних ігноруються.

Викликає подію аудиту marshal.loads з аргументом bytes.

Змінено в версії 3.10: Цей виклик використовувався для виклику події аудиту code.__new__ для кожного об’єкта коду. Тепер він викликає одну подію marshal.loads для всієї операції завантаження.

Крім того, визначено такі константи:

marshal.version

Вказує на формат, який використовує модуль. Версія 0 — це історичний формат, версія 1 використовує вбудовані рядки, а версія 2 використовує двійковий формат для чисел з плаваючою комою. Версія 3 додає підтримку екземплярів об’єктів і рекурсії. Поточна версія 4.

Виноски