README.md

Django Signoffs

A mico-framework for collecting lightweight, non-crypto "signatures" for virtually anything.

• Signoff - a permitted user agrees to something at a time.
• Approval - a set of Signoffs that trigger a state change when the SigningOrder is complete.
• Approval Process - a sequence of Approvals that drive a Finite State Machine.

Quick Start

1. Install the django-signoffs package from PyPI

   $ pip install django-signoffs

2. Add signoffs to INSTALLED_APPS:

   INSTALLED_APPS = [
       ...,
       "signoffs",
       ...,
   ]

Features

django-signoffs has 3 tiers. Import and use only the features you need...

signoffs.signoffs

A Signoff records that a user agreed to some statement at a time. signoffs.signoffs provides a framework for defining use-cases that fall within this broad requirement.

Core features:

• AbstractSignet and AbstractRevokedSignet Models (persistence layer)
• Base Signoff Types, with injectable business and presentation logic...
  • SignoffLogic (permissions and buisness logic)
  • SignoffFormsManager and SignoffRenderer (presentation layer)
  • SignoffUrlsManager (custom end-points)
• Signoff "forward" relation: SignoffOneToOneField
• Signoff "reverse" relation Manager: SignoffSet (many-to-one)
• Declarative signing order automation: SigningOrder
• Template tag: {% render_signoff my_signoff %}

signoffs.approvals

An Approval records whether some condition was met at some point in time. Essentially, it is a 2-state machine, designed to change states when one or more Signoffs are completed, in some defined SigningOrder.

Core features:

• AbstractApprovalSignet and AbstractApprovalStamp Models (persistence layer)
• Base Approval Types, with injectable business and presentation logic...
  • ApprovalLogic (business logic)
  • ApprovalStatus and ApprovalRenderer (presentation layer)
  • ApprovalUrlsManager (custom end-points)
• Approval "forward" relation: ApprovalOneToOneField
• Approval "reverse" relation Manager: ApprovalSet (experimental)
• Template tag: {% render_approval my_approval %}

signoffs.process

An ApprovalsProcess defines a sequence of Approvals and the state changes and/or side effects triggered by approving or revoking each of them.

Core Features:

• ApprovalsProcess (a basic linear sequence of Approvals)
• FsmApprovalsProcess (state-changes and sequencing defined by django-fsm)

Opt-in

Contrib Models

signoffs.contrib.signets

Signoffs core defines only abstract models, no migrations. signoffs.contrib.signets provide concrete models that cover the basic use-cases. To opt-in, you must:

 INSTALLED_APPS = [
     ...,
     "signoffs.contrib.signets",
      ...,
 ]

 $ python manage.py migrate signoffs_signets

Core Features:

• Concrete Models: Signet, and RevokedSignet provide persistence layer for
• Concrete Signoffs: SimpleSignoff, RevokableSignoff, and IrrevokableSignoff

signoffs.contrib.approvals

Approvals core defines only abstract models, no migrations. signoffs.contrib.approvals provide concrete models with basic relations. To opt-in you must:

 INSTALLED_APPS = [
     ...,
     "signoffs.contrib.approvals",
      ...,
 ]

 $ python manage.py migrate signoffs_approvals

Core Features:

• Concrete Models: ApprovalSignet, and RevokedApprovalSignet define a FK relation to...
• Stamp which provides persistence layer for...
• SimpleApproval and IrrevokableApproval, which play nicely with...
• ApprovalSignoff, which uses the Concrete Models for persistence.

FsmApprovalsProcess

Signoffs is integrated with django-fsm, allowing approval processes to drive a finite state machine. To opt-in:

 $ pip install django-signoffs[fsm]

Get Me Some of That

• Source Code
• Read The Docs
• Issues
• PyPI

MIT License

Check Out the Demo App

1. pip install -e git+https://github.com/powderflask/django-signoffs.git#egg=django-signoffs
2. python django-signoffs/manage.py install_demo
3. python django-signoffs/manage.py runserver

Acknowledgments

Special thanks to BC Hydro, Chartwell, and all Contributors

Technology Colophon

Without django and the django dev team, the universe would have fewer rainbows and ponies. Signoffs approval process can be integrated on the deceptively clever django_fsm Friendly Finite State Machine. Signoffs uses a global registry as store for singleton code objects - thanks persisting_theory!

This package was originally created with cookiecutter and the cookiecutter-pypackage project template.

For Developers

$  pip install -r reqirements_dev.txt

Tests

$ pytest

or

$ tox

Code Style / Linting

$ isort
$ black
$ flake8

Versioning

• Semantic Versioning

  $ bumpver show

Docs

• Sphinx + MyST parser
• Read The Docs

Build / Deploy Automation

• invoke

  $ invoke -l

• GitHub Actions (see .github/workflows)
• GitHub Webhooks (see settings/hooks)