Fixture

Fixtures for writing tests for code using oslo.versionedobjects

Note

This module has several extra dependencies not needed at runtime for production code, and therefore not installed by default. To ensure those dependencies are present for your tests, add oslo.versionedobjects[fixtures] to your list of test dependencies.

oslo_versionedobjects.fixture.CompatArgSpec

alias of ArgSpec

class oslo_versionedobjects.fixture.FakeIndirectionAPI(serializer=None)
object_action(context, objinst, objmethod, args, kwargs)

Perform an action on a VersionedObject instance.

When indirection_api is set on a VersionedObject (to a class implementing this interface), method calls on remotable methods will cause this to be executed to actually make the desired call. This often involves performing RPC.

Parameters:

  • context – The context within which to perform the action

  • objinst – The object instance on which to perform the action

  • objmethod – The name of the action method to call

  • args – The positional arguments to the action method

  • kwargs – The keyword arguments to the action method

Returns:

The result of the action method

object_backport(context, objinst, target_version)

Deprecated since version 0.10.0.

Use object_backport_versions() instead.

Perform a backport of an object instance to a specified version.

When indirection_api is set on a VersionedObject (to a class implementing this interface), the default behavior of the base VersionedObjectSerializer, upon receiving an object with a version newer than what is in the lcoal registry, is to call this method to request a backport of the object. In an environment where there is an RPC-able service on the bus which can gracefully downgrade newer objects for older services, this method services as a translation mechanism for older code when receiving objects from newer code.

NOTE: This older/original method is soon to be deprecated. When a backport is required, the newer object_backport_versions() will be tried, and if it raises NotImplementedError, then we will fall back to this (less optimal) method.

Parameters:

  • context – The context within which to perform the backport

  • objinst – An instance of a VersionedObject to be backported

  • target_version – The maximum version of the objinst’s class that is understood by the requesting host.

Returns:

The downgraded instance of objinst

object_class_action(context, objname, objmethod, objver, args, kwargs)

Deprecated since version 0.10.0.

Use object_class_action_versions() instead.

Perform an action on a VersionedObject class.

When indirection_api is set on a VersionedObject (to a class implementing this interface), classmethod calls on remotable_classmethod methods will cause this to be executed to actually make the desired call. This usually involves performing RPC.

Parameters:

  • context – The context within which to perform the action

  • objname – The registry name of the object

  • objmethod – The name of the action method to call

  • objver – The (remote) version of the object on which the action is being taken

  • args – The positional arguments to the action method

  • kwargs – The keyword arguments to the action method

Returns:

The result of the action method, which may (or may not) be an instance of the implementing VersionedObject class.

object_class_action_versions(context, objname, objmethod, object_versions, args, kwargs)

Perform an action on a VersionedObject class.

When indirection_api is set on a VersionedObject (to a class implementing this interface), classmethod calls on remotable_classmethod methods will cause this to be executed to actually make the desired call. This usually involves performing RPC.

This differs from object_class_action() in that it is provided with object_versions, a manifest of client-side object versions for easier nested backports. The manifest is the result of calling obj_tree_get_versions().

NOTE: This was not in the initial spec for this interface, so the base class raises NotImplementedError if you don’t implement it. For backports, this method will be tried first, and if unimplemented, will fall back to object_class_action(). New implementations should provide this method instead of object_class_action()

Parameters:

  • context – The context within which to perform the action

  • objname – The registry name of the object

  • objmethod – The name of the action method to call

  • object_versions – A dict of {objname: version} mappings

  • args – The positional arguments to the action method

  • kwargs – The keyword arguments to the action method

Returns:

The result of the action method, which may (or may not) be an instance of the implementing VersionedObject class.

class oslo_versionedobjects.fixture.IndirectionFixture(indirection_api=None)
setUp()

Prepare the Fixture for use.

This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass).

Raises:

MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.

Returns:

None.

Changed in 1.3:

The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.

Changed in 1.3.1:

BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.

exception oslo_versionedobjects.fixture.ObjectHashMismatch(expected, actual)
class oslo_versionedobjects.fixture.ObjectVersionChecker(obj_classes={})
get_dependency_tree()
get_hashes(extra_data_func=None)

Return a dict of computed object hashes.

Parameters:

extra_data_func – a function that is given the object class which gathers more relevant data about the class that is needed in versioning. Returns a tuple containing the extra data bits.

test_compatibility_routines(use_manifest=False, init_args=None, init_kwargs=None)

Test obj_make_compatible() on all object classes.

Parameters:

  • use_manifest – a boolean that determines if the version manifest should be passed to obj_make_compatible

  • init_args – a dictionary of the format {obj_class: [arg1, arg2]} that will be used to pass arguments to init on the given obj_class. If no args are needed, the obj_class does not need to be added to the dict

  • init_kwargs – a dictionary of the format {obj_class: {‘kwarg1’: val1}} that will be used to pass kwargs to init on the given obj_class. If no kwargs are needed, the obj_class does not need to be added to the dict

test_hashes(expected_hashes, extra_data_func=None)
test_relationships(expected_tree)
test_relationships_in_order()
class oslo_versionedobjects.fixture.OsloOrderedDict

Oslo version of OrderedDict for Python consistency.

class oslo_versionedobjects.fixture.StableObjectJsonFixture

Fixture that makes sure we get stable JSON object representations.

Since objects contain things like set(), which can’t be converted to JSON, we have some situations where the representation isn’t fully deterministic. This doesn’t matter at all at runtime, but does to unit tests that try to assert things at a low level.

This fixture mocks the obj_to_primitive() call and makes sure to sort the list of changed fields (which came from a set) before returning it to the caller.

setUp()

Prepare the Fixture for use.

This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass).

Raises:

MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.

Returns:

None.

Changed in 1.3:

The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.

Changed in 1.3.1:

BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.

class oslo_versionedobjects.fixture.VersionedObjectRegistryFixture

Use a VersionedObjectRegistry as a temp registry pattern fixture.

The pattern solution is to backup the object registry, register a class locally, and then restore the original registry. This could be used for test objects that do not need to be registered permanently but will have calls which lookup registration.

static register(cls_name)
setUp()

Prepare the Fixture for use.

This should not be overridden. Concrete fixtures should implement _setUp. Overriding of setUp is still supported, just not recommended.

After setUp has completed, the fixture will have one or more attributes which can be used (these depend totally on the concrete subclass).

Raises:

MultipleExceptions if _setUp fails. The last exception captured within the MultipleExceptions will be a SetupError exception.

Returns:

None.

Changed in 1.3:

The recommendation to override setUp has been reversed - before 1.3, setUp() should be overridden, now it should not be.

Changed in 1.3.1:

BaseException is now caught, and only subclasses of Exception are wrapped in MultipleExceptions.

oslo_versionedobjects.fixture.compare_obj(test, obj, db_obj, subs=None, allow_missing=None, comparators=None)

Compare a VersionedObject and a dict-like database object.

This automatically converts TZ-aware datetimes and iterates over the fields of the object.

Parameters:

  • test – The TestCase doing the comparison

  • obj – The VersionedObject to examine

  • db_obj – The dict-like database object to use as reference

  • subs – A dict of objkey=dbkey field substitutions

  • allow_missing – A list of fields that may not be in db_obj

  • comparators – Map of comparator functions to use for certain fields

oslo_versionedobjects.fixture.get_method_spec(method)

Get a stable and compatible method spec.

Newer features in Python3 (kw-only arguments and annotations) are not supported or representable with inspect.getargspec() but many object hashes are already recorded using that method. This attempts to return something compatible with getargspec() when possible (i.e. when those features are not used), and otherwise just returns the newer getfullargspec() representation.

ObjectVersionChecker

Fingerprints

One function of the ObjectVersionChecker is to generate fingerprints of versioned objects. These fingerprints are a combination of the object’s version and a hash of the RPC-critical attributes of the object: fields and remotable methods.

The test_hashes() method is used to retrieve the expected and actual fingerprints of the objects. When using this method to assert the versions of objects in a local project, the expected fingerprints are the fingerprints of the previous state of the objects. These fingerprints are defined locally in the project and passed to test_hashes(). The actual fingerprints are the dynamically-generated fingerprints of the current state of the objects. If the expected and actual fingerprints do not match on an object, this means the RPC contract that was previously defined in the object is no longer the same. Because of this, the object’s version must be updated. When the version is updated and the tests are run again, a new fingerprint for the object is generated. This fingerprint should be written over the previous version of the fingerprint. This shows the newly generated fingerprint is now the most recent state of the object.