{"id":7053,"library":"bpylist2","title":"bpylist2","description":"bpylist2 is a Python library for parsing and generating NSKeyedArchiver archives, an Apple proprietary serialization format for Cocoa objects. It is a fork of the original `Marketcircle/bpylist` project, maintained to be more responsive to contributions. While it specializes in NSKeyedArchiver, it also includes a bundled `plistlib` compatible with Python 3.8 for older Python versions, though for standard binary plists, the `stdlib` `plistlib` is recommended. The current version is 4.1.1, released in September 2023.","status":"active","version":"4.1.1","language":"en","source_language":"en","source_url":"https://github.com/parabolala/bpylist2","tags":["plist","apple","nskeyedarchiver","serialization","cocoa","binary"],"install":[{"cmd":"pip install bpylist2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for execution, with specific plistlib handling for Python < 3.8.","package":"python","optional":false}],"imports":[{"note":"The main entry point for archiving and unarchiving NSKeyedArchiver data.","symbol":"archiver","correct":"from bpylist2 import archiver"},{"note":"Used as a base class for custom Python dataclasses to be archived/unarchived.","symbol":"DataclassArchiver","correct":"from bpylist2.archive_types import DataclassArchiver"}],"quickstart":{"code":"from bpylist2 import archiver\nimport io\n\n# An object to archive\nmy_object = {'foo': 'bar', 'some_array': [1, 2, 3, 4], 'nested': {'key': 'value'}}\n\n# Archive the object into bytes\narchived_data = archiver.archive(my_object)\nprint(f\"Archived data (first 50 bytes): {archived_data[:50]}...\")\n\n# Unarchive the bytes back into an object\nunarchived_object = archiver.unarchive(archived_data)\nprint(f\"Unarchived object: {unarchived_object}\")\n\n# Verify round-trip\nassert my_object == unarchived_object\nprint(\"Archiving and unarchiving successful!\")\n","lang":"python","description":"This quickstart demonstrates the basic workflow of archiving a Python dictionary into `NSKeyedArchiver` format bytes and then unarchiving it back. This covers the most common use case for standard Python types."},"warnings":[{"fix":"For standard binary plists, use Python's built-in `plistlib` module (`import plistlib`) instead of `bpylist2.archiver`.","message":"When working with plain binary `.plist` files (not NSKeyedArchiver), `bpylist2` is not the correct tool. It will likely raise `UnarchiveError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For custom classes, define `encode_archive(obj, archive)` and `decode_archive(archive)` static methods. Alternatively, use a dataclass and inherit `from bpylist2.archive_types import DataclassArchiver`.","message":"To archive or unarchive custom Python objects (that are not standard types like dicts, lists, strings, numbers), you must either implement `encode_archive` and `decode_archive` static methods on your class or inherit from `bpylist2.archive_types.DataclassArchiver`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Register a mapping using `archiver.update_class_map({'CocoaClassName': PythonClass})`, where `PythonClass` is your custom Python class capable of decoding the data (e.g., using `DataclassArchiver` or custom `decode_archive`).","message":"When unarchiving a `NSKeyedArchiver` file containing custom Cocoa classes (not standard `NSString`, `NSArray`, etc.), `bpylist2` needs to know how to map these Cocoa classes to Python classes.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your custom class `MyCustomClass` either inherits from `bpylist2.archive_types.DataclassArchiver` (if it's a dataclass) or implements `encode_archive(obj, archive)` and `decode_archive(archive)` as static methods.","cause":"You are attempting to archive an instance of a custom Python class without having properly defined the archiving interface for it.","error":"AttributeError: 'MyCustomClass' object has no attribute 'encode_archive'"},{"fix":"Define a corresponding Python class (e.g., `MyPythonClass`) that can handle the structure of 'SomeCustomCocoaClass', and then register it using `archiver.update_class_map({'SomeCustomCocoaClass': MyPythonClass})` before attempting to unarchive.","cause":"The NSKeyedArchiver archive contains a custom Apple Cocoa class ('SomeCustomCocoaClass' in this example) that `bpylist2` does not have a registered Python class mapping for.","error":"bpylist2.archiver.UnarchiveError: Unknown class: 'SomeCustomCocoaClass'"},{"fix":"Verify that the file is indeed an `NSKeyedArchiver` archive. If it's a regular binary plist, use Python's standard `plistlib` module instead. If it's expected to be `NSKeyedArchiver`, check the file's integrity.","cause":"This error typically occurs when you are trying to unarchive a file that is not a valid NSKeyedArchiver format, but rather a standard binary plist, or a corrupted file.","error":"bpylist2.archiver.UnarchiveError: Invalid magic string: 'bplist00' expected"}]}