Install & Compatibility
Where this runs
tested against v3.10.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.884s · 71.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.9s · import 1.745s · 70MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VersionedObject
✓ from oslo_versionedobjects import base
✗ from oslo.versionedobjects import base
The top-level package is `oslo_versionedobjects`, not `oslo.versionedobjects`.
Field
✓ from oslo_versionedobjects import fields
✗ from oslo.versionedobjects import fields
Field types (StringField, IntegerField, etc.) are imported from `oslo_versionedobjects.fields`.
VersionedObjectSerializer
✓ from oslo_versionedobjects import base
✗ from oslo.versionedobjects import base
The serializer is part of the base module for object primitives.
This quickstart demonstrates how to define a basic VersionedObject with fields and methods. It then shows how to instantiate it, modify its state, and finally serialize it to a primitive representation (dictionary) and deserialize it back, illustrating the core versioning and serialization capabilities of the library.
import uuid
from oslo_versionedobjects import base, fields
# 1. Define your VersionedObject
class MyExampleObject(base.VersionedObject):
# The current version of this object schema.
# Increment this when making backwards-incompatible changes.
VERSION = '1.0'
# Define the fields for your object
fields = {
'id': fields.UUIDField(),
'name': fields.StringField(nullable=False),
'status': fields.StringField(default='active'),
'value': fields.IntegerField(nullable=True, default=0),
}
# Optional: Override __init__ to set defaults or perform custom logic
def __init__(self, context=None, **kwargs):
super().__init__(context, **kwargs)
# Call obj_set_defaults() to ensure default values from fields are applied.
self.obj_set_defaults()
# Optional: Add methods to your object
def activate(self):
if self.status != 'active':
self.status = 'active'
self.obj_make_compatible() # Mark object as changed for serialization
print(f"Object {self.name} activated.")
else:
print(f"Object {self.name} is already active.")
# 2. Instantiate and use your object
# Create an instance with some data
obj_id = str(uuid.uuid4())
my_obj = MyExampleObject(id=obj_id, name="First Item", value=100)
print(f"Initial object: {my_obj.obj_name} v{my_obj.obj_version}")
print(f"ID: {my_obj.id}")
print(f"Name: {my_obj.name}")
print(f"Status: {my_obj.status}")
print(f"Value: {my_obj.value}")
print(f"Is changed? {my_obj.obj_what_changed()}")
my_obj.activate()
print(f"Status after activation: {my_obj.status}")
print(f"Is changed? {my_obj.obj_what_changed()}")
# 3. Serialize and Deserialize (demonstrates versioning capability)
serializer = base.VersionedObjectSerializer()
# Convert the object to a primitive (dictionary) for serialization
primitive = serializer.serialize_entity(None, my_obj)
print("\nSerialized primitive:")
print(primitive)
# Simulate deserialization (e.g., after receiving over RPC)
deserialized_obj = serializer.deserialize_entity(None, MyExampleObject, primitive)
print("\nDeserialized object:")
print(f"Name: {deserialized_obj.name}")
print(f"Status: {deserialized_obj.status}")
print(f"Value: {deserialized_obj.value}")
print(f"Are objects equal? {my_obj == deserialized_obj}")
print(f"Has deserialized object changed? {deserialized_obj.obj_what_changed()}")
Errors
Common errors & fixes
TypeError: Object of type MyExampleObject is not JSON serializable
Attempting to serialize a VersionedObject instance directly using `json.dumps()` or similar standard JSON encoders.
fixUse the provided serializer: `from oslo_versionedobjects import base; serializer = base.VersionedObjectSerializer(); primitive = serializer.serialize_entity(None, my_obj)`
VersionedObjectNotFound: Object MyExampleObject with version 1.0 could not be found.
The object class (or its specific version) was not properly registered with the VersionedObjectRegistry before deserialization or RPC calls, or there's a mismatch between `obj_name`/`obj_version` and the registered objects.
fixEnsure your VersionedObject classes are imported and accessible where deserialization occurs. In OpenStack services, this is often handled by a central manager; for standalone use, ensure all object definitions are loaded.
AttributeError: 'MyExampleObject' object has no attribute 'some_field'
Attempting to access a field that was not defined in the `fields` dictionary of the VersionedObject class, or the field was not loaded (if using lazy-loading from `obj_load_attr`).
fixVerify that 'some_field' is correctly defined in the `fields` dictionary of `MyExampleObject`. If the object is loaded from a primitive, ensure the primitive contains the field data. For lazy-loaded fields, call `obj_load_attr('some_field')` before access. Upgrade
Version history
3.10.2latest on PyPI · released Apr 22, 2026
Audit
Dependencies
oslo.utilsrequiredCore utility library for OpenStack projects, used for logging, i18n, etc.
oslo.configrequiredConfiguration management library for OpenStack projects.