openstack/neutron
Code Issues Proposed changes

Add documentation about OVO "obj_make_compatible"

Browse Source 
Adds new documentation about how to implement
"VersionedObject.obj_make_compatible" when a new object version
is released and how to test it.

Change-Id: I055cf2ae493759562175f9d859d2a065458ca7e2
Related-Bug: #1828437
This commit is contained in:
Rodolfo Alonso Hernandez 2019-05-22 10:31:20 +00:00
parent dfc2586fb1
commit 079de324ab
1 changed files with 34 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/source/contributor/internals/objects_usage.rst
View File

@ -175,7 +175,40 @@ Example::
set the :code:`VERSION` field to 1.0.
Change :code:`VERSION` if fields or their types are modified. When you change
the version of objects being exposed via RPC, add method
:code:`obj_make_compatible(self, primitive, target_version)`.
:code:`obj_make_compatible(self, primitive, target_version)`. For example, if
a new version introduces a new parameter, it needs to be removed for previous
versions::
from oslo_utils import versionutils
def obj_make_compatible(self, primitive, target_version):
_target_version = versionutils.convert_version_to_tuple(target_version)
if _target_version < (1, 1): # version 1.1 introduces "new_parameter"
primitive.pop('new_parameter', None)
In the following example the object has changed an attribute definition. For
example, in version 1.1 :code:`description` is allowed to be :code:`None` but
not in version 1.0::
from oslo_utils import versionutils
from oslo_versionedobjects import exception
def obj_make_compatible(self, primitive, target_version):
_target_version = versionutils.convert_version_to_tuple(target_version)
if _target_version < (1, 1): # version 1.1 changes "description"
if primitive['description'] is None:
# "description" was not nullable before
raise exception.IncompatibleObjectVersion(
objver=target_version, objname='OVOName')
Using the first example as reference, this is how the unit test can be
implemented::
def test_object_version_degradation_1_1_to_1_0(self):
OVO_obj_1_1 = self._method_to_create_this_OVO()
OVO_obj_1_0 = OVO_obj_1_1.obj_to_primitive(target_version='1.0')
self.assertNotIn('new_parameter', OVO_obj_1_0['versioned_object.data'])
.. note::
Standard Attributes are automatically added to OVO fields in base class.