lck.django 0.8.5 documentation

This Page

lck.django.common.models

lck.django.common.models

Contains a small set of useful abstract model base classes that are not application-specific.

Classes

class Named(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model with a unique name field.

class NonUnique(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model with a non-unique name field.

name_urlencoded

Useful as in {%url some-link argument.name_urlencoded%}.

Named.name_urlencoded

Useful as in {%url some-link argument.name_urlencoded%}.

class Titled(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model with a unique title field.

class NonUnique(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model with a non-unique title field.

class Slugged(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model with a unique slug field.

class NonUnique(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model with a non-unique slug field.

class TimeTrackable(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model whose lifecycle is tracked by time. Includes a created field that is set automatically upon object creation, a modified field that is updated automatically upon calling save() on the object whenever a significant change was done, and a cache_version integer field that is automatically incremeneted any time a significant change is done.

By a significant change we mean any change outside of those internal created, modified, cache_version, display_count or last_active fields. Full list of ignored fields lies in TimeTrackable.insignificant_fields.

Note: for admin integration lck.django.common.admin.ModelAdmin is recommended over the vanilla ModelAdmin. It adds the created and modified fields as filters on the side of the change list and those fields will be rendered as read-only on the change form.

dirty_fields

dirty_fields() -> {‘field1’: ‘old_value1’, ‘field2’: ‘old_value2’, ...}

Returns a dictionary of attributes that have changed on this object and are not yet saved. The values are original values present in the database at the moment of this object’s creation/read/last save.

mark_clean(*fields, **kwargs)

Removes the forced dirty marks from fields.

Fields that would be considered dirty anyway stay that way, unless force is set to True. In that case a field is unmarked until another change on it happens.

mark_dirty(*fields)

Forces fields to be marked as dirty to make all machinery checking for dirty fields treat them accordingly.

save(update_modified=True, *args, **kwargs)

Overrides save(). Adds the update_modified=True argument. If False, the modified field won’t be updated even if there were significant changes to the model.

significant_fields_updated

Returns True on significant changes to the model.

By a significant change we mean any change outside of those internal created, modified, cache_version, display_count or last_active fields. Full list of ignored fields lies in TimeTrackable.insignificant_fields.

update_cache_version(force=False)

Updates the cache_version bypassing the save() mechanism, thus providing better performance and consistency. Unless forced by force=True, the update happens only when a significant change was made on the object.

class SavePrioritized(*args, **kwargs)

Bases: lck.django.common.models.TimeTrackable

Describes a variant of the TimeTrackable model which also tracks priorities of saves on its fields. The default priority is stored in the settings under DEFAULT_SAVE_PRIORITY (defaults to 0 if missing).

The priority engine enables parts of the application to make saves with higher priority. Then all modified fields store the priority value required to update them again. If another part of the application comes along to update one of those fields using lower priority, the change is silently dropped. The priority engine works on a per-field basis.

Note: This base class should be put as far in the MRO as possible to protect from saving transformations of values which would be ignored otherwise.

Note: Because of the limits of Django’s multiple inheritance support, models based on SavePrioritized CAN NOT also be explicitly based on TimeTrackable. They are based implicitly so this should be no problem. Just make sure you get rid of the TimeTrackable base class if you introduce SavePrioritized.

get_save_priorities()

Decodes the stored save_priorities and returns a defaultdict (a key miss returns priority 0).

Probably an internal state method, not that much interesting for typical model consumers.

save(priority=0, *args, **kwargs)

Overrides save(), adding the priority=DEFAULT_SAVE_PRIORITY argument. Non-zero priority changes to significant fields are annotated and saved with the object. If later on another writer with lower priority changes one of those fields which were modified with higher priority, the later change is silently rolled back.

Note: priorities are stored and enforced on a per-field level.

update_save_priorities(priorities)

Encodes the save_priorities field based on the provided priorities dictionary (like -but not limited to- the one returned by get_save_priorities()).

Note: this doesn’t automatically run save() after updating the save_priorities field.

Probably an internal state method, not that much interesting for typical model consumers.

class Localized(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model which holds data in a specified language. The language is chosen from the Language choices class but only from those specified in settings.LANGUAGES. The default value is settings.LANGUAGE_CODE.

class DisplayCounter(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract model which display_count can be incremented by calling bump().

If bump() is called with some unique_id as its argument, Django’s cache will be used to ensure subsequent invocations with the same unique_id won’t bump the display count. This functionality requires get_absolute_url() to be defined for the model.

If the model is also TimeTrackable, bumps won’t update the modified field.

bump([unique_id])

Increments the display_count field. If unique_id is provided, Django’s cache is used to make sure a unique visitor can only increment this counter once per hour. Recommended to be used in the form:

model.bump(remote_addr(request))

where remote_addr is a helper from lck.django.common.

class SoftDeletable(*args, **kwargs)

Bases: django.db.models.base.Model

Describes an abstract models which can be soft deleted, that is instead of actually removing objects from the database, they have a deleted field which is set to True and the object is then invisible in normal operations (thanks to ViewableSoftDeletableManager).

class ViewableSoftDeletableManager

Bases: django.db.models.manager.Manager

An object manager to automatically hide objects that were soft deleted for models inheriting SoftDeletable.