{"id":4164,"library":"oslo-serialization","title":"Oslo Serialization Library","description":"The oslo.serialization library, part of the OpenStack Oslo project, provides robust utilities for representing Python objects in transmittable and storable formats like JSON and MessagePack. It aims to offer high-quality, stable, and consistent serialization functionalities for OpenStack and other projects. The library is actively maintained and currently at version 5.9.1.","status":"active","version":"5.9.1","language":"en","source_language":"en","source_url":"https://github.com/openstack/oslo.serialization","tags":["serialization","json","messagepack","openstack","utilities","data-interchange"],"install":[{"cmd":"pip install oslo-serialization","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides core utility functions used by oslo.serialization.","package":"oslo.utils","optional":false},{"reason":"Required for MessagePack serialization support (imported as `msgpack`).","package":"msgpack-python","optional":true},{"reason":"Required for YAML serialization, though the `yamlutils` module is deprecated.","package":"PyYAML","optional":true}],"imports":[{"note":"While 'import oslo_serialization.jsonutils' works, directly importing the module is the standard and cleaner approach for accessing its functions like dumps, loads, and to_primitive.","wrong":"import oslo_serialization.jsonutils","symbol":"jsonutils","correct":"from oslo_serialization import jsonutils"}],"quickstart":{"code":"from oslo_serialization import jsonutils\nimport datetime\nimport uuid\n\nclass CustomObject:\n    def __init__(self, name, value, created_at=None):\n        self.name = name\n        self.value = value\n        self.id = str(uuid.uuid4())\n        self.created_at = created_at or datetime.datetime.now(datetime.timezone.utc)\n\n    # oslo_serialization.jsonutils.to_primitive will handle this automatically\n    # but for custom types, you might explicitly define how to convert them.\n    # For datetime and UUID, jsonutils has built-in support.\n    def to_dict(self):\n        return {\n            'name': self.name,\n            'value': self.value,\n            'id': self.id,\n            'created_at': self.created_at.isoformat()\n        }\n\n# Example usage\nobj = CustomObject('test_item', 123.45)\n\n# Serialize to JSON string\njson_string = jsonutils.dumps(obj, indent=2)\nprint(f\"Serialized JSON:\\n{json_string}\")\n\n# Deserialize from JSON string\ndata_dict = jsonutils.loads(json_string)\nprint(f\"Deserialized dictionary: {data_dict}\")\n\n# Demonstrate to_primitive (used internally by dumps by default)\nprimitive_data = jsonutils.to_primitive(obj)\nprint(f\"Primitive representation: {primitive_data}\")\n","lang":"python","description":"This quickstart demonstrates how to use `oslo_serialization.jsonutils.dumps` and `loads` to serialize and deserialize a custom Python object. It highlights the automatic handling of types like `datetime` and `UUID` by `jsonutils.to_primitive`, which `dumps` utilizes by default."},"warnings":[{"fix":"Ensure your project runs on Python 3.10 or newer. Upgrade your Python environment if necessary.","message":"Support for Python 2.7 has been dropped since version 3.0.0. The minimum supported Python version is now 3.10 (as of oslo.serialization 5.9.1). Older Python versions will not work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate any usage of `oslo_serialization.yamlutils` to direct usage of the PyYAML library. Review OpenStack documentation for recommended patterns if specific OpenStack-isms were relied upon.","message":"The `oslo_serialization.yamlutils` module is deprecated since the Ussuri series (version 3.1.1) and its support will be removed in a future release. PyYAML is now considered safe by default.","severity":"deprecated","affected_versions":">=3.1.1"},{"fix":"Review code that serializes complex or potentially unhandled types. Implement a `to_dict` method on custom objects or provide a `default` function to `jsonutils.dumps` to handle non-primitive types gracefully, catching `ValueError` if specific error handling is needed.","message":"The `oslo_serialization.jsonutils.to_primitive` function (used internally by `dumps`) now explicitly raises a `ValueError` when the input value cannot be converted to a primitive type. Previously, it might have silently skipped or handled it differently.","severity":"gotcha","affected_versions":">=5.3.0"},{"fix":"Be aware of this limitation when designing systems that rely on remote exception handling. Consider capturing additional context or logging details at the source if a full traceback is critical for remote debugging.","message":"Serialization of Python traceback objects (e.g., as part of remote exceptions) is inherently lossy. The reconstructed traceback on the receiving end may not be as rich or complete as the original due to missing local stack frame information.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}