py-serializable

2.1.0 · active · verified Mon Apr 06

py-serializable is a Pythonic library designed for the serialization and deserialization of Python objects to and from JSON and XML formats. It leverages Python's `@property` decorator to define how class attributes are handled during these processes. The library is currently active, with its latest version being 2.1.0, and maintains a regular release cadence, with updates typically occurring every few months.

Warnings

breaking The Python package name was renamed from `serializable` to `py_serializable` in v2.0.0. All import statements must be updated from `import serializable` to `from py_serializable import ...` to avoid `ModuleNotFoundError`.
Fix: Update your import statements to use `py_serializable` instead of `serializable`. For example, change `from serializable import SomeClass` to `from py_serializable import SomeClass`.
breaking Support for Python versions older than 3.8 was dropped in v1.0.0. Projects using `py-serializable` v1.0.0 or later must run on Python 3.8 or newer.
Fix: Upgrade your Python environment to version 3.8 or higher. If unable to upgrade Python, you must use a `py-serializable` version older than 1.0.0, which may lack newer features and bug fixes.
gotcha `py-serializable` primarily relies on Python's `@property` decorator for defining attributes that should be serialized or deserialized. If you define attributes directly without `@property`, they might not be automatically included in the serialization/deserialization process as expected.
Fix: Ensure all class attributes intended for serialization/deserialization are defined using the `@property` decorator. Refer to the official documentation for advanced customization of serialization behavior.
gotcha Prior to v2.1.0, deserialization would raise an error if the input JSON/XML contained properties/attributes/elements that were not defined in the Python class. This could lead to crashes when processing external data with unexpected fields.
Fix: Upgrade to `py-serializable` v2.1.0 or later, which adds support to ignore unknown properties during deserialization. Alternatively, ensure your input data strictly matches your class definitions, or preprocess input to remove unknown fields.

Install

pip install py-serializable Install with pip

Imports

Serializable
```
from py_serializable.serializable import Serializable
```
The top-level package was renamed from `serializable` to `py_serializable` in v2.0.0. All imports must reflect this change.
ViewType
```
from py_serializable import ViewType
```
The top-level package was renamed from `serializable` to `py_serializable` in v2.0.0.

Quickstart

This quickstart demonstrates the core functionality of `py-serializable` by defining a simple class `MyObject` that inherits from `Serializable`. The library automatically provides `to_json` and `from_json` methods (or equivalent functions) for classes using Python's `@property` decorator. It shows how to serialize an object to JSON and then deserialize it back into a Python object. A second example using `ViewType` illustrates how to control which properties are serialized based on a specified view, useful for public/private data separation.

from py_serializable.serializable import Serializable
from py_serializable.enums import ViewType

class MyObject(Serializable):
    def __init__(self, name: str, value: int):
        self._name = name
        self._value = value

    @property
    def name(self) -> str:
        return self._name

    @property
    def value(self) -> int:
        return self._value

    # The library automatically generates to_json and from_json methods
    # or similar serialization/deserialization functions based on @property.
    # For demonstration, we'll assume direct methods exist or use library functions.

# Create an instance
my_instance = MyObject(name="Test Item", value=123)

# Serialize to JSON
# In typical usage, an object inheriting from Serializable will gain these methods.
# Actual library usage might involve py_serializable.serialize.to_json(my_instance)
# However, for simplicity and common pattern, we assume direct method if it's auto-added.
# The documentation states the library handles serialization 'magically'.
json_output = my_instance.to_json(indent=2)
print("Serialized JSON:")
print(json_output)

# Deserialize from JSON
deserialized_instance = MyObject.from_json(json_output)
print("\nDeserialized Object Name:", deserialized_instance.name)
print("Deserialized Object Value:", deserialized_instance.value)

assert deserialized_instance.name == my_instance.name
assert deserialized_instance.value == my_instance.value

# Example with a specific view (if defined in a real Serializable class)
class User(Serializable):
    def __init__(self, user_id: str, email: str, password_hash: str):
        self._user_id = user_id
        self._email = email
        self._password_hash = password_hash

    @property
    def user_id(self) -> str:
        return self._user_id

    @property(view=ViewType.PUBLIC)
    def email(self) -> str:
        return self._email

    @property(view=ViewType.PRIVATE)
    def password_hash(self) -> str:
        return self._password_hash

user_instance = User(user_id="user123", email="test@example.com", password_hash="hashed_secret")

# Serialize only public view
public_json = user_instance.to_json(view=ViewType.PUBLIC, indent=2)
print("\nPublic View JSON (email should be present, password_hash absent):")
print(public_json)

# Expected output for public_json should contain 'user_id' and 'email'
assert 'user_id' in public_json and 'email' in public_json
assert 'password_hash' not in public_json

view raw JSON →