API Reference¶

Django Admin¶

class dj_cqrs.admin.CQRSAdminMasterSyncMixin¶

Mixin that includes a custom action in AdminModel. This action allows synchronizing master’s model items from Django Admin page,

_cqrs_sync_queryset(queryset)¶

This function is used to adjust the QuerySet before sending the sync signal.

Parameters: queryset (Queryset) – Original queryset
Returns: Updated queryset
Return type: Queryset

sync_items(request, queryset)¶: This method synchronizes selected items from the Admin Page. It is registered as a custom action in Django Admin

Mixins¶

class dj_cqrs.mixins.RawMasterMixin(*args, **kwargs)¶

Base class for MasterMixin. Users shouldn’t use this class directly.

CQRS_ID = None¶: Unique CQRS identifier for all microservices.

CQRS_PRODUCE = True¶: If false, no cqrs data is sent through the transport.

CQRS_FIELDS = '__all__'¶: List of fields to include in the CQRS payload. You can also set the fields attribute to the special value ‘__all__’ to indicate that all fields in the model should be used.

CQRS_SERIALIZER = None¶: Optional serializer used to create the instance representation. Must be expressed as a module dotted path string like mymodule.serializers.MasterModelSerializer.

CQRS_TRACKED_FIELDS = None¶: List of fields of the main model for which you want to track the changes and send the previous values via transport. You can also set the field attribute to the special value “__all__” to indicate that all fields in the model must be used.

cqrs¶: Manager that adds needed CQRS queryset methods.

property cqrs_saves_count¶: Shows how many times this instance has been saved within the transaction.

property is_initial_cqrs_save¶: This flag is used to check if instance has already been registered for CQRS update.

reset_cqrs_saves_count()¶: This method is used to automatically reset instance CQRS counters on transaction commit. But this can also be used to control custom behaviour within transaction or in case of rollback, when several sequential transactions are used to change the same instance.

to_cqrs_dict(using=None, sync=False)¶

CQRS serialization for transport payload.

Parameters: using (str, optional) – The using argument can be used to force the database to use, defaults to None
Returns: The serialized instance data.
Return type: dict

get_tracked_fields_data()¶

CQRS serialization for tracked fields to include in the transport payload.

Returns: Previous values for tracked fields.
Return type: dict

cqrs_sync(using=None, queue=None)¶

Manual instance synchronization.

Parameters

using (str, optional) – The using argument can be used to force the database to use, defaults to None
queue (str, optional) – Syncing can be executed just for a single queue, defaults to None (all queues)

Returns

True if instance can be synced, False otherwise.

Return type

bool

is_sync_instance()¶

This method can be overridden to apply syncing only to instances by some rules. For example, only objects with special status or after some creation date, etc.

Returns: True if this instance needs to be synced, False otherwise
Return type: bool

get_cqrs_meta(**kwargs)¶

This method can be overridden to collect model/instance specific metadata.

Returns: Metadata dictionary if it’s provided.
Return type: dict

classmethod relate_cqrs_serialization(queryset)¶

This method shoud be overriden to optimize database access for example using select_related and prefetch_related when related models must be included into the master model representation.

Parameters: queryset (django.db.models.QuerySet) – The initial queryset.
Returns: The optimized queryset.
Return type: django.db.models.QuerySet

get_custom_cqrs_delete_data()¶: This method should be overridden when additional data is needed in DELETE payload.

classmethod call_post_bulk_create(instances, using=None)¶

Post bulk create signal caller (django doesn’t support it by default).

# Used automatically by cqrs.bulk_create()
instances = model.cqrs.bulk_create(instances)

classmethod call_post_update(instances, using=None)¶

Post bulk update signal caller (django doesn’t support it by default).

# Used automatically by cqrs.bulk_update()
qs = model.objects.filter(k1=v1)
model.cqrs.bulk_update(qs, k2=v2)

class dj_cqrs.mixins.MasterMixin(*args, **kwargs)¶

Bases: dj_cqrs.mixins.RawMasterMixin

Mixin for the master CQRS model, that will send data updates to it’s replicas.

class dj_cqrs.mixins.ReplicaMixin(*args, **kwargs)¶

Mixin for the replica CQRS model, that will receive data updates from master. Models, using this mixin should be readonly, but this is not enforced (f.e. for admin).

CQRS_ID = None¶: Unique CQRS identifier for all microservices.

CQRS_MAPPING = None¶: Mapping of master data field name to replica model field name.

CQRS_CUSTOM_SERIALIZATION = False¶: Set it to True to skip default data check.

CQRS_SELECT_FOR_UPDATE = False¶: Set it to True to acquire lock on instance creation/update.

CQRS_NO_DB_OPERATIONS = False¶: Set it to True to disable any default DB operations for this model.

CQRS_META = False¶: Set it to True to receive meta data for this model.

cqrs¶: Manager that adds needed CQRS queryset methods.

classmethod cqrs_save(master_data, previous_data=None, sync=False, meta=None)¶

This method saves (creates or updates) model instance from CQRS master instance data. This method must not be overridden. Otherwise, sync checks need to be implemented manually.

Parameters

master_data (dict) – CQRS master instance data.
previous_data (dict) – Previous values for tracked fields.
sync (bool) – Sync package flag.
or None meta (dict) – Payload metadata, if exists.

Returns

Model instance.

Return type

django.db.models.Model

classmethod cqrs_create(sync, mapped_data, previous_data=None, meta=None)¶

This method creates model instance from CQRS mapped instance data. It must be overridden by replicas of master models with custom serialization.

Parameters

sync (bool) – Sync package flag.
mapped_data (dict) – CQRS mapped instance data.
previous_data (dict) – Previous mapped values for tracked fields.
or None meta (dict) – Payload metadata, if exists.

Returns

Model instance.

Return type

django.db.models.Model

cqrs_update(sync, mapped_data, previous_data=None, meta=None)¶

This method updates model instance from CQRS mapped instance data. It must be overridden by replicas of master models with custom serialization.

Parameters

sync (bool) – Sync package flag.
mapped_data (dict) – CQRS mapped instance data.
previous_data (dict) – Previous mapped values for tracked fields.
or None meta (dict) – Payload metadata, if exists.

Returns

Model instance.

Return type

django.db.models.Model

classmethod cqrs_delete(master_data, meta=None)¶

This method deletes model instance from mapped CQRS master instance data.

Parameters

master_data (dict) – CQRS master instance data.
or None meta (dict) – Payload metadata, if exists.

Returns

Flag, if delete operation is successful (even if nothing was deleted).

Return type

bool

Managers¶

class dj_cqrs.managers.MasterManager(*args, **kwargs)¶

bulk_create(objs, **kwargs)¶

Custom bulk create method to support sending of create signals. This can be used only in cases, when IDs are generated on client or DB returns IDs.

Parameters

objs (django.db.models.Model) – List of objects for creation
kwargs – Bulk create kwargs

bulk_update(queryset, **kwargs)¶

Custom update method to support sending of update signals.

Parameters

queryset (django.db.models.QuerySet) – Django Queryset (f.e. filter)
kwargs – Update kwargs

class dj_cqrs.managers.ReplicaManager(*args, **kwargs)¶

save_instance(master_data, previous_data=None, sync=False, meta=None)¶

This method saves (creates or updates) model instance from CQRS master instance data.

Parameters

master_data (dict) – CQRS master instance data.
previous_data (dict) – Previous values for tracked fields.
sync (bool) – Sync package flag.
or None meta (dict) – Payload metadata, if exists.

Returns

Model instance.

Return type

django.db.models.Model

create_instance(mapped_data, previous_data=None, sync=False, meta=None)¶

This method creates model instance from mapped CQRS master instance data.

Parameters

mapped_data (dict) – Mapped CQRS master instance data.
previous_data (dict) – Previous values for tracked fields.
sync (bool) – Sync package flag.
or None meta (dict) – Payload metadata, if exists.

Returns

ReplicaMixin model instance.

Return type

django.db.models.Model

update_instance(instance, mapped_data, previous_data=None, sync=False, meta=None)¶

This method updates model instance from mapped CQRS master instance data.

Parameters

instance (django.db.models.Model) – ReplicaMixin model instance.
mapped_data (dict) – Mapped CQRS master instance data.
previous_data (dict) – Previous values for tracked fields.
or None meta (dict) – Payload metadata, if exists.
sync (bool) – Sync package flag.

Returns

ReplicaMixin model instance.

Return type

django.db.models.Model

delete_instance(master_data)¶

This method deletes model instance from mapped CQRS master instance data.

Parameters: master_data (dict) – CQRS master instance data.
Returns: Flag, if delete operation is successful (even if nothing was deleted).
Return type: bool

Signals¶

dj_cqrs.signals.post_bulk_create = <django.dispatch.dispatcher.Signal object>¶: Signal sent after a bulk create. See dj_cqrs.mixins.RawMasterMixin.call_post_bulk_create.

dj_cqrs.signals.post_update = <django.dispatch.dispatcher.Signal object>¶: Signal sent after a bulk update. See dj_cqrs.mixins.RawMasterMixin.call_post_update.

class dj_cqrs.signals.MasterSignals¶

Signals registry and handlers for CQRS master models.

classmethod register_model(model_cls)¶

Registers signals for a model.

Parameters: model_cls (dj_cqrs.mixins.MasterMixin) – Model class inherited from CQRS MasterMixin.

classmethod post_save(sender, **kwargs)¶

Parameters: sender (dj_cqrs.mixins.MasterMixin) – Class or instance inherited from CQRS MasterMixin.

classmethod post_delete(sender, **kwargs)¶

Parameters: sender (dj_cqrs.mixins.MasterMixin) – Class or instance inherited from CQRS MasterMixin.

classmethod post_bulk_create(sender, **kwargs)¶

Parameters: sender (dj_cqrs.mixins.MasterMixin) – Class or instance inherited from CQRS MasterMixin.

classmethod post_bulk_update(sender, **kwargs)¶

Parameters: sender (dj_cqrs.mixins.MasterMixin) – Class or instance inherited from CQRS MasterMixin.

Transports¶

class dj_cqrs.transport.BaseTransport¶

CQRS pattern can be implemented over any transport (AMQP, HTTP, etc.) All transports need to inherit from this base class. Transport must be set in Django settings:

CQRS = {
    'transport': 'dj_cqrs.transport.rabbit_mq.RabbitMQTransport',
}

static produce(payload)¶

Send data from master model to replicas.

Parameters: payload (dj_cqrs.dataclasses.TransportPayload) – Transport payload from master model.

static consume(*args, **kwargs)¶: Receive data from master model.

static clean_connection(*args, **kwargs)¶: Clean transport connection. Here you can close all connections that you have

class dj_cqrs.transport.RabbitMQTransport¶

classmethod clean_connection()¶: Clean transport connection. Here you can close all connections that you have

classmethod consume(cqrs_ids=None)¶: Receive data from master model.

classmethod produce(payload)¶

Send data from master model to replicas.

Parameters: payload (dj_cqrs.dataclasses.TransportPayload) – Transport payload from master model.

class dj_cqrs.transport.KombuTransport¶

classmethod clean_connection()¶: Nothing to do here

classmethod consume(cqrs_ids=None)¶: Receive data from master model.

classmethod produce(payload)¶

Send data from master model to replicas.

Parameters: payload (dj_cqrs.dataclasses.TransportPayload) – Transport payload from master model.

class dj_cqrs.constants.SignalType¶

Type of signal that generates this event.

SAVE = 'SAVE'¶: The master model has been saved.

DELETE = 'DELETE'¶: The master model has been deleted.

SYNC = 'SYNC'¶: The master model needs syncronization.

class dj_cqrs.dataclasses.TransportPayload(signal_type, cqrs_id, instance_data, instance_pk, queue=None, previous_data=None, correlation_id=None, expires=None, retries=0, meta=None)¶

Transport message payload.

Parameters

signal_type (dj_cqrs.constants.SignalType) – Type of the signal for this message.
cqrs_id (str) – The unique CQRS identifier of the model.
instance_data (dict) – Serialized data of the instance that generates the event.
instance_pk – Primary key of the instance.
queue (str, optional) – Queue to synchronize, defaults to None.
previous_data (dict, optional) – Previous values for fields tracked for changes, defaults to None.
correlation_id (str, optional) – Correlation ID of process, where this payload is used.
retries (int, optional) – Current number of message retries.
expires (datetime, optional) – Message expiration datetime, infinite if None
meta (dict, optional) – Payload metadata

classmethod from_message(dct)¶

Builds payload from message data.

Parameters: dct (dict) – Deserialized message body data.
Returns: TransportPayload instance.
Return type: TransportPayload

to_dict()¶

Return the payload as a dictionary.

Returns: This payload.
Return type: dict

is_expired()¶

Checks if this payload is expired.

Returns: True if payload is expired, False otherwise.
Return type: bool

Registries¶

class dj_cqrs.registries.MasterRegistry¶

classmethod register_model(model_cls)¶: Registration of CQRS model identifiers.

classmethod get_model_by_cqrs_id(cqrs_id)¶

Returns the model class given its CQRS_ID.

Parameters: cqrs_id (str) – The CQRS_ID of the model to be retrieved.
Returns: The model that correspond to the given CQRS_ID or None if it has not been registered.
Return type: django.db.models.Model

class dj_cqrs.registries.ReplicaRegistry¶

classmethod register_model(model_cls)¶: Registration of CQRS model identifiers.

classmethod get_model_by_cqrs_id(cqrs_id)¶

Returns the model class given its CQRS_ID.

Parameters: cqrs_id (str) – The CQRS_ID of the model to be retrieved.
Returns: The model that correspond to the given CQRS_ID or None if it has not been registered.
Return type: django.db.models.Model