signoffs.core.models.signets

A Signet is a relation between a user and a timestamp. A concrete Signet may have other information about, or perhaps a relation to, the thing being signed off.

A Signet records a one-time action that can generally only be completed by a User with permission. The presence of a Signet record provides evidence that a particular someone signed off on a particular something. A Signet is not intended to be edited. Create them, revoke them, re-create them. Don’t edit and re-save them. To revoke a Signet, we can simply delete the Signet record. To maintain a “blame” history, we can instead record who and when the signet was revoked with a RevokedSignet.

Module Contents

Classes

SignetQuerySet	Custom queries for signets
ActiveSignetManager	Filters out revoked signets from queryset - should be the default manager
RevokedSignetManager	Filters out un-revoked signets from queryset (only revoked signets returned
AbstractSignet	Abstract base class for all Signet models A Signet is the model for a single “signature” or a user’s personal “seal” or “sigil” Persistence layer for a signoff: who, when, what (what is supplied by concrete class, e.g., with a FK to other model) Note: user relation is required for signing - enforced by app logic rather than at DB level so that… SET_NULL on_delete for user field is sensible for use-cases where signoff should persist even after user is deleted. For other on_delete behaviours, concrete RevokedSignet classes will need to override the user relation.
AbstractRevokedSignet	Abstract base class for all Signet Revocation models A Revoked Signet is a record of a signet that was removed. Only needed if a record of revoked signets is required. Persistence layer for revoked signet: who, when, what (what is an app-relative concrete Signet model) Note: user relation is required for signing - enforced by app logic rather than at DB level - see AbstractSignet

Functions

validate_signoff_id

Raise ValidationError if value is not a registered Signoff Type ID

get_signet_defaults

Return a dictionary of default values for fields the given signet - this is the default implementation for settings.SIGNOFFS_SIGNET_DEFAULTS setting. Called just before signet is saved - signet is guaranteed to have a valid user object. Dictionary keys must match signet model field names - only editable fields of signet may have defaults. Only fields with no value will be set to its default value.

Data

BaseSignetManager

API

class signoffs.core.models.signets.SignetQuerySet(model=None, query=None, using=None, hints=None)

Bases: django.db.models.QuerySet

Custom queries for signets

Initialization

active()

Filter out revoked signets

revoked()

Return only revoked signets

with_user()

Select the related signing User

with_revoked_receipt()

Select related ‘revoked’ records

signoffs(signoff_id=None, subject=None)

Returns list of signoff objects, one for each signet in queryset, optionally filtered for specific signoff type - filtering done in-memory for performance.

signoffs.core.models.signets.BaseSignetManager

None

class signoffs.core.models.signets.ActiveSignetManager

Bases: signoffs.core.models.signets.BaseSignetManager

Filters out revoked signets from queryset - should be the default manager

get_queryset()

class signoffs.core.models.signets.RevokedSignetManager

Bases: signoffs.core.models.signets.BaseSignetManager

Filters out un-revoked signets from queryset (only revoked signets returned

get_queryset()

signoffs.core.models.signets.validate_signoff_id(value)

Raise ValidationError if value is not a registered Signoff Type ID

signoffs.core.models.signets.get_signet_defaults(signet)

Return a dictionary of default values for fields the given signet - this is the default implementation for settings.SIGNOFFS_SIGNET_DEFAULTS setting. Called just before signet is saved - signet is guaranteed to have a valid user object. Dictionary keys must match signet model field names - only editable fields of signet may have defaults. Only fields with no value will be set to its default value.

class signoffs.core.models.signets.AbstractSignet(*args, **kwargs)

Bases: django.db.models.Model

Abstract base class for all Signet models A Signet is the model for a single “signature” or a user’s personal “seal” or “sigil” Persistence layer for a signoff: who, when, what (what is supplied by concrete class, e.g., with a FK to other model) Note: user relation is required for signing - enforced by app logic rather than at DB level so that… SET_NULL on_delete for user field is sensible for use-cases where signoff should persist even after user is deleted. For other on_delete behaviours, concrete RevokedSignet classes will need to override the user relation.

Initialization

signoff_id

None

user

None

sigil

None

sigil_label

None

timestamp

None

class Meta

abstract

True

ordering

[‘timestamp’]

objects

None

revoked_signets

None

all_signets

None

read_only_fields

(‘signoff_id’, ‘timestamp’)

__str__()

property signoff_type

Return the Signoff Type (class) that governs this signet

get_signoff(subject=None)

Return a Signoff instance for this signet

signoff()

The Signoff instance for this signet

property signatory

Return the user who signed, or AnonymousUser if signed but no signatory, None if not yet signed

sign(user)

Sign unsigned signet for given user. If self.is_signed() raises PermissionDenied

has_user()

Return True iff this signet has a user-relation

is_signed()

Return True if this Signet has a persistent representation

is_revoked()

Return True if this Signet has been revoked - Performance: .with_revoked_receipt() to avoid extra query

has_valid_signoff()

Return True iff this Signet has a valid signoff_id

can_save()

Return True iff this signet is data-complete and ready to be saved, but has not been saved before

update(defaults=False, **attrs)

Update instance model fields with any attrs that match by name, optionally setting only unset fields

get_signet_defaults()

Return dict of default field values for this signet - signet MUST have user relation!

set_signet_defaults()

Set default field values for this signet - signet MUST have user relation!

validate_save()

Raise ValidationError if this Signet cannot be saved, otherwise just pass.

save(*args, **kwargs)

Add a ‘sigil’ label if there is not one & check user has permission to save this signet

classmethod has_object_relation()

Return True iff this Signet class has a FK relation to some object other than user

class signoffs.core.models.signets.AbstractRevokedSignet(*args, **kwargs)

Bases: django.db.models.Model

Abstract base class for all Signet Revocation models A Revoked Signet is a record of a signet that was removed. Only needed if a record of revoked signets is required. Persistence layer for revoked signet: who, when, what (what is an app-relative concrete Signet model) Note: user relation is required for signing - enforced by app logic rather than at DB level - see AbstractSignet

Initialization

signet

None

user

None

reason

None

timestamp

None

class Meta

abstract

True

__str__()

signoffs.contrib.signets.models

Basic concrete implementation for Signet models

Module Contents

Classes

Signet	A concrete persistence layer for basic Signoffs with no relations.
RevokedSignet	A concrete persistence layer for revoked Signoffs.

API

class signoffs.contrib.signets.models.Signet(*args, **kwargs)

Bases: signoffs.models.AbstractSignet

A concrete persistence layer for basic Signoffs with no relations.

Suitable for out-of-the-box use with signoffs.models.SignoffField

Initialization

class signoffs.contrib.signets.models.RevokedSignet(*args, **kwargs)

Bases: signoffs.models.AbstractRevokedSignet

A concrete persistence layer for revoked Signoffs.

May be declared on Signoff Types to provide persistence and tracking of revoked signoffs.

Initialization