marshal --- Tuần tự hóa đối tượng Python nội bộ

---

Mô-đun này chứa các hàm có thể đọc và ghi các giá trị Python ở định dạng nhị phân. Định dạng này dành riêng cho Python nhưng không phụ thuộc vào các vấn đề về kiến ​​trúc máy (ví dụ: bạn có thể ghi giá trị Python vào tệp trên PC, truyền tệp sang máy Mac và đọc lại ở đó). Thông tin chi tiết về định dạng không được ghi lại có mục đích; nó có thể thay đổi giữa các phiên bản Python (mặc dù hiếm khi xảy ra). [1]

Đây không phải là mô-đun "kiên trì" chung chung. Để biết tính bền vững và chuyển giao chung của các đối tượng Python thông qua lệnh gọi RPC, hãy xem các mô-đun pickle và shelve. Mô-đun marshal tồn tại chủ yếu để hỗ trợ đọc và ghi mã "được biên dịch giả" cho các mô-đun Python của tệp .pyc. Do đó, những người bảo trì Python có quyền sửa đổi định dạng nguyên soái theo những cách không tương thích ngược nếu cần. Định dạng của các đối tượng mã không tương thích giữa các phiên bản Python, ngay cả khi phiên bản có định dạng giống nhau. Việc hủy tuần tự hóa một đối tượng mã trong phiên bản Python không chính xác có hành vi không xác định. Nếu bạn đang tuần tự hóa và hủy tuần tự hóa các đối tượng Python, hãy sử dụng mô-đun pickle thay thế -- hiệu suất có thể so sánh được, tính độc lập của phiên bản được đảm bảo và dưa chua hỗ trợ phạm vi đối tượng rộng hơn đáng kể so với nguyên soái.

Cảnh báo

Mô-đun marshal không nhằm mục đích bảo mật trước dữ liệu sai sót hoặc được xây dựng độc hại. Không bao giờ sắp xếp dữ liệu nhận được từ một nguồn không đáng tin cậy hoặc không được xác thực.

Có các hàm đọc/ghi tệp cũng như các hàm hoạt động trên các đối tượng giống byte.

Không phải tất cả các loại đối tượng Python đều được hỗ trợ; nói chung, chỉ những đối tượng có giá trị độc lập với lệnh gọi Python cụ thể mới có thể được ghi và đọc bởi mô-đun này. Các loại sau đây được hỗ trợ:

• Các loại số: int, bool, float, complex.

• Dây (str) và bytes. Bytes-like objects như bytearray được sắp xếp thành bytes.

• Vùng chứa: tuple, list, set, frozenset và (kể từ version 5), slice. Cần hiểu rằng những điều này chỉ được hỗ trợ nếu bản thân các giá trị chứa trong đó được hỗ trợ. Các vùng chứa đệ quy được hỗ trợ kể từ version 3.

• Các đĩa đơn None, Ellipsis và StopIteration.

• đối tượng code, nếu allow_code là đúng. Xem lưu ý ở trên về sự phụ thuộc vào phiên bản.

Thay đổi trong phiên bản 3.4:

• Đã thêm định dạng phiên bản 3, hỗ trợ sắp xếp các danh sách, bộ và từ điển đệ quy.

• Đã thêm phiên bản định dạng 4, hỗ trợ biểu diễn hiệu quả các chuỗi ngắn.

Thay đổi trong phiên bản 3.14: Đã thêm định dạng phiên bản 5, cho phép sắp xếp các lát cắt.

Mô-đun xác định các chức năng này:

marshal.dump(value, file, version=version, /, *, allow_code=True)

Viết giá trị vào tập tin đang mở. Giá trị phải là loại được hỗ trợ. Tệp phải là binary file có thể ghi được.

Nếu giá trị có (hoặc chứa một đối tượng có) loại không được hỗ trợ, ngoại lệ ValueError sẽ xuất hiện --- nhưng dữ liệu rác cũng sẽ được ghi vào tệp. Đối tượng sẽ không được load() đọc lại chính xác. Code objects chỉ được hỗ trợ nếu allow_code là đúng.

Đối số version cho biết định dạng dữ liệu mà dump nên sử dụng (xem bên dưới).

Tăng một auditing event marshal.dumps với các đối số value, version.

Thay đổi trong phiên bản 3.13: Đã thêm tham số allow_code.

marshal.load(file, /, *, allow_code=True)

Đọc một giá trị từ tệp đang mở và trả về nó. Nếu không có giá trị hợp lệ nào được đọc (ví dụ: vì dữ liệu có định dạng so sánh không tương thích của phiên bản Python khác), hãy tăng EOFError, ValueError hoặc TypeError. Code objects chỉ được hỗ trợ nếu allow_code là đúng. Tệp phải là binary file có thể đọc được.

Tăng auditing event marshal.load mà không có đối số.

Ghi chú

Nếu một đối tượng chứa loại không được hỗ trợ được sắp xếp bằng dump(), load() sẽ thay thế None cho loại không thể sắp xếp được.

Thay đổi trong phiên bản 3.10: Cuộc gọi này được sử dụng để đưa ra sự kiện kiểm tra code.__new__ cho từng đối tượng mã. Bây giờ nó đưa ra một sự kiện marshal.load duy nhất cho toàn bộ hoạt động tải.

Thay đổi trong phiên bản 3.13: Đã thêm tham số allow_code.

marshal.dumps(value, version=version, /, *, allow_code=True)

Trả về đối tượng byte sẽ được dump(value, file) ghi vào tệp. Giá trị phải là loại được hỗ trợ. Đưa ra ngoại lệ ValueError nếu giá trị có (hoặc chứa đối tượng có) loại không được hỗ trợ. Code objects chỉ được hỗ trợ nếu allow_code là đúng.

Đối số version cho biết định dạng dữ liệu mà dumps nên sử dụng (xem bên dưới).

Tăng một auditing event marshal.dumps với các đối số value, version.

Thay đổi trong phiên bản 3.13: Đã thêm tham số allow_code.

marshal.loads(bytes, /, *, allow_code=True)

Chuyển đổi bytes-like object thành một giá trị. Nếu không tìm thấy giá trị hợp lệ, hãy tăng EOFError, ValueError hoặc TypeError. Code objects chỉ được hỗ trợ nếu allow_code là đúng. Các byte bổ sung trong đầu vào sẽ bị bỏ qua.

Tăng một auditing event marshal.loads với đối số bytes.

Thay đổi trong phiên bản 3.10: Cuộc gọi này được sử dụng để đưa ra sự kiện kiểm tra code.__new__ cho từng đối tượng mã. Bây giờ nó đưa ra một sự kiện marshal.loads duy nhất cho toàn bộ hoạt động tải.

Thay đổi trong phiên bản 3.13: Đã thêm tham số allow_code.

Ngoài ra, các hằng số sau được xác định:

marshal.version

Cho biết định dạng mà mô-đun sử dụng. Phiên bản 0 là phiên bản lịch sử đầu tiên; các phiên bản tiếp theo bổ sung thêm tính năng mới. Nói chung, một phiên bản mới sẽ trở thành mặc định khi nó được giới thiệu.

Phiên bản	Có sẵn kể từ	Tính năng mới
1	Python 2.4	Chia sẻ chuỗi thực tập
2	Python 2.5	Biểu diễn nhị phân của float
3	Python 3.4	Hỗ trợ khởi tạo và đệ quy đối tượng
4	Python 3.4	Biểu diễn hiệu quả các chuỗi ngắn
5	Python 3.14	Hỗ trợ các đối tượng slice

Chú thích cuối trang

[1]

Tên của mô-đun này bắt nguồn từ một số thuật ngữ được các nhà thiết kế Modula-3 (trong số những người khác) sử dụng, những người sử dụng thuật ngữ "sắp xếp" để vận chuyển dữ liệu ở dạng độc lập. Nói đúng ra, "sang sắp xếp" có nghĩa là chuyển đổi một số dữ liệu từ dạng bên trong sang dạng bên ngoài (ví dụ: trong bộ đệm RPC) và "không sắp xếp theo thứ tự" cho quy trình ngược lại.