From 484bd69a0373f50f689babb3c168c925d401e3e0 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 19 Feb 2026 14:59:44 +0000 Subject: [PATCH] docs: Rework reference, usage docs Change-Id: I1ba4f60c5d80fff97ad52188aeb9f2d79b37981f Signed-off-by: Stephen Finucane --- doc/source/reference/base.rst | 6 +- doc/source/reference/exception.rst | 6 +- doc/source/reference/fields.rst | 6 +- doc/source/reference/fixture.rst | 6 +- doc/source/user/usage.rst | 129 +++++++++++------------------ 5 files changed, 61 insertions(+), 92 deletions(-) diff --git a/doc/source/reference/base.rst b/doc/source/reference/base.rst index d9c8ac09..32aa6a06 100644 --- a/doc/source/reference/base.rst +++ b/doc/source/reference/base.rst @@ -1,6 +1,6 @@ -============= - base -============= +========================== +oslo_versionedobjects.base +========================== .. automodule:: oslo_versionedobjects.base :members: diff --git a/doc/source/reference/exception.rst b/doc/source/reference/exception.rst index b2cfaff2..9dfd63c3 100644 --- a/doc/source/reference/exception.rst +++ b/doc/source/reference/exception.rst @@ -1,6 +1,6 @@ -========= -exception -========= +=============================== +oslo_versionedobjects.exception +=============================== .. automodule:: oslo_versionedobjects.exception :members: diff --git a/doc/source/reference/fields.rst b/doc/source/reference/fields.rst index 80b87eef..4a937695 100644 --- a/doc/source/reference/fields.rst +++ b/doc/source/reference/fields.rst @@ -1,6 +1,6 @@ -============= - fields -============= +============================ +oslo_versionedobjects.fields +============================ .. automodule:: oslo_versionedobjects.fields :members: diff --git a/doc/source/reference/fixture.rst b/doc/source/reference/fixture.rst index 9ccc9a80..40490c48 100644 --- a/doc/source/reference/fixture.rst +++ b/doc/source/reference/fixture.rst @@ -1,6 +1,6 @@ -========= - Fixture -========= +============================= +oslo_versionedobjects.fixture +============================= .. automodule:: oslo_versionedobjects.fixture :members: diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index 338cf0a9..38987a0f 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -2,76 +2,58 @@ Usage ======= -Incorporating oslo.versionedobjects into your projects can be accomplished in +Incorporating *oslo.versionedobjects* into your project can be accomplished in the following steps: -1. `Add oslo.versionedobjects to requirements`_ -2. `Create objects subdirectory and a base.py inside it`_ -3. `Create base object with the project namespace`_ -4. `Create other base objects if needed`_ -5. `Implement objects and place them in objects/\*.py`_ -6. `Implement extra fields in objects/fields.py`_ -7. `Create object registry and register all objects`_ -8. `Create and attach the object serializer`_ -9. `Implement the indirection API`_ +Initial scaffolding +------------------- +By convention, objects reside in the `/objects` directory. This is the +place from which all objects should be imported. -Add oslo.versionedobjects to requirements ------------------------------------------ +Start the implementation by creating `objects/base.py` with a subclass of the +:class:`oslo_versionedobjects.base.VersionedObject`. This class will form the +base class for all objects in the project. You need to populate the +``OBJ_PROJECT_NAMESPACE`` property. -To use oslo.versionedobjects in an OpenStack project remember to add it to the -requirements.txt +.. note:: + ``OBJ_SERIAL_NAMESPACE`` is used only for backward compatibility and + should not be set in new projects. -Create objects subdirectory and a base.py inside it ---------------------------------------------------- +You may also wish to optionally include the following mixins: -Objects reside in the `/objects` directory and this is the place -from which all objects should be imported. +* :class:`oslo_versionedobjects.base.VersionedPersistentObject` -Start the implementation by creating `objects/base.py` with these main -classes: + A mixin class for persistent objects can be created, defining repeated + fields like ``created_at``, ``updated_at``. Fields are defined in the fields + property (which is a dict). +* :class:`oslo_versionedobjects.base.VersionedObjectDictCompat` -Create base object with the project namespace ---------------------------------------------- + If objects were previously passed as dicts (a common situation), this class + can be used as a mixin class to support dict operations. -:class:`oslo_versionedobjects.base.VersionedObject` - -The VersionedObject base class for the project. You have to fill up the -`OBJ_PROJECT_NAMESPACE` property. `OBJ_SERIAL_NAMESPACE` is used only for -backward compatibility and should not be set in new projects. - - -Create other base objects if needed ------------------------------------ - -class:`oslo_versionedobjects.base.VersionedPersistentObject` - -A mixin class for persistent objects can be created, defining repeated fields -like `created_at`, `updated_at`. Fields are defined in the fields property -(which is a dict). - -If objects were previously passed as dicts (a common situation), a -:class:`oslo_versionedobjects.base.VersionedObjectDictCompat` can be used as a -mixin class to support dict operations. - -Implement objects and place them in objects/\*.py -------------------------------------------------- - -Objects classes should be created for all resources/objects passed via RPC -as IDs or dicts in order to: +Once you have you base class defined, you can define your actual object +classes. Objects classes should be created for all resources/objects passed via +RPC as IDs or dicts in order to: * spare the database (or other resource) from extra calls * pass objects instead of dicts, which are tagged with their version -* handle all object versions in one place (the `obj_make_compatible` method) +* handle all object versions in one place (the ``obj_make_compatible`` method) To make sure all objects are accessible at all times, you should import them -in __init__.py in the objects/ directory. +in ``__init__.py`` in the ``objects/`` directory and expose them via +``__all__``. +Finally, you should create an object registry by subclassing +:class:`oslo_versionedobjects.base.VersionedObjectRegistry`. The object +registry is the place where all objects are registered. All object classes +should be registered by the +:attr:`oslo_versionedobjects.base.ObjectRegistry.register` class decorator. -Implement extra fields in objects/fields.py -------------------------------------------- +Using custom field types +------------------------ New field types can be implemented by inheriting from :class:`oslo_versionedobjects.field.Field` and overwriting the `from_primitive` @@ -81,28 +63,14 @@ By subclassing :class:`oslo_versionedobjects.fields.AutoTypedField` you can stack multiple fields together, making sure even nested data structures are being validated. - -Create object registry and register all objects ------------------------------------------------ - -:class:`oslo_versionedobjects.base.VersionedObjectRegistry` - -The place where all objects are registered. All object classes should be -registered by the :attr:`oslo_versionedobjects.base.ObjectRegistry.register` -class decorator. - - - -Create and attach the object serializer ---------------------------------------- - -:class:`oslo_versionedobjects.base.VersionedObjectSerializer` +Configure serialization +----------------------- To transfer objects by RPC, subclass the :class:`oslo_versionedobjects.base.VersionedObjectSerializer` setting the OBJ_BASE_CLASS property to the previously defined Object class. -Connect the serializer to oslo_messaging: +For example, to use a custom serializer with `oslo_messaging`__: .. code:: python @@ -110,22 +78,23 @@ Connect the serializer to oslo_messaging: target = messaging.Target(topic=topic, server=server) self._server = messaging.get_rpc_server(transport, target, handlers, serializer=serializer) +.. __: https://docs.openstack.org/oslo.messaging/latest/ Implement the indirection API ----------------------------- -:class:`oslo_versionedobjects.base.VersionedObjectIndirectionAPI` +*oslo.versionedobjects* supports "remotable" method calls. These are calls of +the object methods and classmethods which can be executed locally or remotely +depending on the configuration. Setting the ``indirection_api`` as a property +of an object relays the calls to decorated methods through the defined RPC API. +The attachment of the ``indirection_api`` should be handled by configuration at +startup time. -oslo.versionedobjects supports `remotable` method calls. These are calls -of the object methods and classmethods which can be executed locally or -remotely depending on the configuration. Setting the indirection_api as a -property of an object relays the calls to decorated methods through the -defined RPC API. The attachment of the indirection_api should be handled -by configuration at startup time. - -Second function of the indirection API is backporting. When the object -serializer attempts to deserialize an object with a future version, not -supported by the current instance, it calls the object_backport method in an -attempt to backport the object to a version which can then be handled as +The second function of the indirection API is backporting. When the object +serializer attempts to deserialize an object with a future version not +supported by the current instance, it calls the ``object_backport`` method in +an attempt to backport the object to a version which can then be handled as normal. +The :class:`oslo_versionedobjects.base.VersionedObjectIndirectionAPI` class +provides a base class for implementing your own indirection API.