cinder.objects.base module

Cinder common internal object model

class CinderComparableObject

Bases: ComparableVersionedObject

class CinderObject(context=None, **kwargs)

Bases: VersionedObject

OBJ_PROJECT_NAMESPACE = 'cinder'
cinder_obj_get_changes()

Returns a dict of changed fields with tz unaware datetimes.

Any timezone aware datetime field will be converted to UTC timezone and returned as timezone unaware datetime.

This will allow us to pass these fields directly to a db update method as they can’t have timezone information.

obj_make_compatible(primitive, target_version)

Make an object representation compatible with a target version.

This is responsible for taking the primitive representation of an object and making it suitable for the given target_version. This may mean converting the format of object attributes, removing attributes that have been added since the target version, etc. In general:

  • If a new version of an object adds a field, this routine should remove it for older versions.

  • If a new version changed or restricted the format of a field, this should convert it back to something a client knowing only of the older version will tolerate.

  • If an object that this object depends on is bumped, then this object should also take a version bump. Then, this routine should backlevel the dependent object (by calling its obj_make_compatible()) if the requested version of this object is older than the version where the new dependent object was added.

Parameters:

  • primitive – The result of obj_to_primitive()

  • target_version – The version string requested by the recipient of the object

Raises:

oslo_versionedobjects.exception.UnsupportedObjectError if conversion is not possible for some reason

class CinderObjectDictCompat

Bases: VersionedObjectDictCompat

Mix-in to provide dictionary key access compat.

If an object needs to support attribute access using dictionary items instead of object attributes, inherit from this class. This should only be used as a temporary measure until all callers are converted to use modern attribute access.

NOTE(berrange) This class will eventually be deleted.

get(key, value=<class 'oslo_versionedobjects.base._NotSpecifiedSentinel'>)

For backwards-compatibility with dict-based objects.

NOTE(danms): May be removed in the future.

class CinderObjectRegistry(*args, **kwargs)

Bases: VersionedObjectRegistry

registration_hook(cls, index)

Hook called when registering a class.

This method takes care of adding the class to cinder.objects namespace.

Should registering class have a method called cinder_ovo_cls_init it will be called to support class initialization. This is convenient for all persistent classes that need to register their models.

class CinderObjectSerializer(version_cap=None)

Bases: VersionedObjectSerializer

OBJ_BASE_CLASS

alias of CinderObject

serialize_entity(context, entity)

Serialize something to primitive form.

Parameters:

  • ctxt – Request context, in deserialized form

  • entity – Entity to be serialized

Returns:

Serialized form of entity

class CinderObjectVersionsHistory

Bases: dict

Helper class that maintains objects version history.

Current state of object versions is aggregated in a single version number that explicitly identifies a set of object versions. That way a service is able to report what objects it supports using a single string and all the newer services will know exactly what that mean for a single object.

add(ver, updates)
get_current()
get_current_versions()
class CinderPersistentObject

Bases: object

Mixin class for Persistent objects.

This adds the fields that we use in common for all persistent objects.

class Case(whens, value=None, else_=None)

Bases: object

Class for conditional value selection for conditional_update.

class Not(value, field=None, auto_none=True)

Bases: Condition

Class for negated condition values for conditional_update.

By default NULL values will be treated like Python treats None instead of how SQL treats it.

So for example when values are (1, 2) it will evaluate to True when we have value 3 or NULL, instead of only with 3 like SQL does.

get_filter(model, field=None)
OPTIONAL_FIELDS = ()
as_read_deleted(mode='yes')

Context manager to make OVO with modified read deleted context.

This temporarily modifies the context embedded in an object to have a different read_deleted parameter.

Parameter mode accepts most of the same parameters as our model_query DB method. We support ‘yes’, ‘no’, and ‘only’.

usage:

with obj.as_read_deleted():

obj.refresh()

if obj.status = ‘deleted’:

…

classmethod cinder_ovo_cls_init()

This method is called on OVO registration and sets the DB model.

conditional_update(values, expected_values=None, filters=(), save_all=False, reflect_changes=True, order=None)

Compare-and-swap update.

A conditional object update that, unlike normal update, will SAVE the contents of the update to the DB.

Update will only occur in the DB and the object if conditions are met.

If no expected_values are passed in we will default to make sure that all fields have not been changed in the DB. Since we cannot know the original value in the DB for dirty fields in the object those will be excluded.

We have 4 different condition types we can use in expected_values:

  • Equality: {‘status’: ‘available’}

  • Inequality: {‘status’: vol_obj.Not(‘deleting’)}

  • In range: {‘status’: [‘available’, ‘error’]

  • Not in range: {‘status’: vol_obj.Not([‘in-use’, ‘attaching’])

Method accepts additional filters, which are basically anything that can be passed to a sqlalchemy query’s filter method, for example:

[~sql.exists().where(models.Volume.id == models.Snapshot.volume_id)]

We can select values based on conditions using Case objects in the ‘values’ argument. For example:

has_snapshot_filter = sql.exists().where(
    models.Snapshot.volume_id == models.Volume.id)
case_values = volume.Case([(has_snapshot_filter, 'has-snapshot')],
                          else_='no-snapshot')
volume.conditional_update({'status': case_values},
                          {'status': 'available'}))

And we can use DB fields using model class attribute for example to store previous status in the corresponding field even though we don’t know which value is in the db from those we allowed:

volume.conditional_update({'status': 'deleting',
                           'previous_status': volume.model.status},
                          {'status': ('available', 'error')})
Parameters:

  • values – Dictionary of key-values to update in the DB.

  • expected_values – Dictionary of conditions that must be met for the update to be executed.

  • filters – Iterable with additional filters

  • save_all – Object may have changes that are not in the DB, this will say whether we want those changes saved as well.

  • reflect_changes – If we want changes made in the database to be reflected in the versioned object. This may mean in some cases that we have to reload the object from the database.

  • order – Specific order of fields in which to update the values

Returns:

Boolean indicating whether db rows were updated. It will be False if we couldn’t update the DB and True if we could.

classmethod exists(context, id_)
fields = {'created_at': DateTime(default=<class 'oslo_versionedobjects.fields.UnspecifiedDefault'>,nullable=True), 'deleted': Boolean(default=False,nullable=True), 'deleted_at': DateTime(default=<class 'oslo_versionedobjects.fields.UnspecifiedDefault'>,nullable=True), 'updated_at': DateTime(default=<class 'oslo_versionedobjects.fields.UnspecifiedDefault'>,nullable=True)}
classmethod get_by_id(context, id, *args, **kwargs)
obj_as_admin()

Context manager to make an object call as an admin.

This temporarily modifies the context embedded in an object to be elevated() and restores it after the call completes. Example usage:

with obj.obj_as_admin():

obj.save()

refresh()
update_single_status_where(new_status, expected_status, filters=())
class ClusteredObject

Bases: object

assert_not_frozen()
property is_clustered
property resource_backend
property service_topic_queue
class ObjectListBase(*args, **kwargs)

Bases: ObjectListBase

obj_make_compatible(primitive, target_version)