django-maker-checker 0.4.0__py3-none-any.whl

django_maker_checker/__init__.py

@@ -0,0 +1,3 @@
+"""Maker-checker approvals engine for Django (headless: models, rules, services and queries)."""
+
+__version__ = "0.4.0"

django_maker_checker/actions.py

@@ -0,0 +1,171 @@
+"""``@approval_action``: put a service function behind maker-checker without writing a handler class.
+
+This is the Command pattern. Calling the decorated function captures the call (its keyword arguments, made
+JSON-safe) as an Approval Request when a policy applies, and runs the function only once the request is approved.
+With no policy the function runs immediately, so the call site is the same either way.
+
+The decorated function must take keyword-only arguments: ``tenant``, ``maker`` and ``context`` are supplied by the
+framework; everything else is the payload and must survive a JSON round trip (``Decimal``/dates arrive as strings).
+
+.. code-block:: python
+
+    @approval_action(
+        "balance_update",
+        label="Balance Update",
+        category="Balances",
+        lock_key=lambda p: f"{p['account_id']}:{p['balance_date']}",
+        target_label=lambda p: f"Account {p['account_id']} on {p['balance_date']}",
+    )
+    def update_balance(*, tenant, maker, context, account_id, balance_date, new_balance):
+        ...
+        return {"account_id": account_id}
+
+    outcome = update_balance(tenant=tenant, maker=request.user, request=request,
+                             justification="Bank restated the balance",
+                             account_id=1, balance_date="2026-09-30", new_balance="100.00")
+    if outcome.pending:
+        ...  # outcome.approval_request.reference
+"""
+
+import json
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from django.core.serializers.json import DjangoJSONEncoder
+
+from django_maker_checker import services
+from django_maker_checker.registry import ActionHandler, ExecutionContext, Scope, diff_rows, register_handler
+
+
+@dataclass
+class Outcome:
+    """Result of calling an approval action: either pending approval or already applied."""
+
+    approval_request: Optional[Any] = None
+    result: Any = None
+
+    @property
+    def pending(self):
+        return self.approval_request is not None
+
+
+def to_payload(values: dict) -> dict:
+    """The JSON form a payload is stored in; raises TypeError naming the offending value.
+
+    Payloads go through this round trip on both paths (approved later, or applied immediately), so the action's
+    function always receives the same JSON values (``Decimal`` and dates as strings) whether or not approval was
+    required. That keeps behaviour identical when a tenant turns a rule on or off.
+    """
+    try:
+        return json.loads(json.dumps(values, cls=DjangoJSONEncoder))
+    except TypeError as err:
+        raise TypeError(f"Maker-checker payloads must be JSON-serialisable: {err}") from err
+
+
+class FunctionHandler(ActionHandler):
+    """ActionHandler whose behaviour comes from a function plus optional hook callables.
+
+    Each hook argument of ``@approval_action`` replaces the matching ``ActionHandler`` method; omitted hooks keep the
+    neutral defaults (no label, empty snapshot, no scopes, every change matches, nothing to re-validate).
+    """
+
+    def __init__(
+        self,
+        func,
+        *,
+        action_type,
+        label,
+        category,
+        lock_key,
+        description="",
+        icon="shield",
+        sub_options=(),
+        scopes=(Scope.GLOBAL,),
+        review_template="approvals/review/generic.html",
+        target_label=None,
+        snapshot_before=None,
+        scope_keys=None,
+        matches=None,
+        validate=None,
+    ):
+        self.func = func
+        self.action_type = action_type
+        self.label = label
+        self.category = category
+        self.description = description
+        self.icon = icon
+        self.sub_options = tuple(sub_options)
+        self.scopes = tuple(scopes)
+        self.review_template = review_template
+        self._lock_key = lock_key
+        self._target_label = target_label
+        self._snapshot_before = snapshot_before
+        self._scope_keys = scope_keys
+        self._matches = matches
+        self._validate = validate
+
+    @property
+    def origin(self):
+        # All decorated functions share this class, so the function (not the class) identifies the definition.
+        return f"{self.func.__module__}.{self.func.__qualname__}"
+
+    def lock_key(self, payload):
+        return str(self._lock_key(payload))
+
+    def target_label(self, payload):
+        return str(self._target_label(payload)) if self._target_label else ""
+
+    def snapshot_before(self, tenant, payload):
+        return to_payload(self._snapshot_before(tenant, payload)) if self._snapshot_before else {}
+
+    def scope_keys(self, tenant, payload):
+        return list(self._scope_keys(tenant, payload)) if self._scope_keys else []
+
+    def matches(self, policy, payload):
+        return self._matches(policy, payload) if self._matches else True
+
+    def validate(self, approval_request):
+        if self._validate:
+            self._validate(approval_request)
+
+    def execute(self, approval_request, context: ExecutionContext):
+        """Replay the captured call. ``maker`` is the person who asked for the change, so the change is attributed
+        to them; the final checker is ``context.actor``."""
+        return self.func(
+            tenant=approval_request.tenant,
+            maker=approval_request.maker,
+            context=context,
+            **approval_request.payload,
+        )
+
+    def review_context(self, approval_request):
+        return {"rows": diff_rows(approval_request.before_snapshot or {}, approval_request.payload)}
+
+
+def approval_action(action_type: str, *, label: str, category: str, lock_key: Callable[[dict], str], **options):
+    """Register ``func`` as a maker-checker action and return a callable that routes through approval."""
+
+    def decorator(func):
+        handler = register_handler(
+            FunctionHandler(func, action_type=action_type, label=label, category=category, lock_key=lock_key, **options)
+        )
+
+        @wraps(func)
+        def submit(*, tenant, maker, justification="", request=None, **payload):
+            """Call the action: returns an ``Outcome`` that is pending (a request was raised) or holds the result."""
+            approval_request, result = services.submit_or_execute(
+                action_type,
+                tenant=tenant,
+                maker=maker,
+                payload=to_payload(payload),
+                justification=justification,
+                request=request,
+            )
+            return Outcome(approval_request, result)
+
+        submit.handler = handler
+        submit.apply = func  # the undecorated function, for callers that must bypass approval (tests, admin tools)
+        return submit
+
+    return decorator

django_maker_checker/adapter.py

@@ -0,0 +1,115 @@
+"""The contract between the approvals engine and the host application.
+
+The engine never imports the host. Everything it needs to know about tenancy, roles, permissions, scopes,
+notifications and audit comes through one ``ApprovalsAdapter`` instance, named by the ``APPROVALS_ADAPTER``
+setting. Subclass it in the host and implement every abstract method.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Optional
+
+
+@dataclass(frozen=True)
+class Notice:
+    """One notification event, delivered by the host to ``recipients`` over its own channels."""
+
+    kind: str  # requested | decided | escalated | cancelled | sla_warning
+    title: str
+    text: str
+    severity: str  # info | warning | error
+    recipients: tuple
+    approval_request: Any
+    link: str = ""
+
+
+@dataclass(frozen=True)
+class AuditRecord:
+    """One audit-trail entry for the host's central audit log."""
+
+    action: str  # created | updated
+    resource_type: str  # ApprovalRequest | ApprovalDelegation
+    resource_id: str
+    tenant_id: Any
+    actor_id: Any = None
+    before: Optional[dict] = None
+    after: Optional[dict] = None
+    metadata: dict = field(default_factory=dict)
+
+
+class ApprovalsAdapter(ABC):
+    """Host integration.
+
+    ``tenant`` arguments are instances of ``APPROVALS_TENANT_MODEL`` and ``role`` arguments of ``APPROVALS_ROLE_MODEL``.
+    """
+
+    # --- tenancy and roles ----------------------------------------------------------------------
+
+    @abstractmethod
+    def tenant_of(self, user) -> Optional[Any]:
+        """The tenant ``user`` acts for, or None if they are not an active member of one."""
+
+    @abstractmethod
+    def members(self, tenant, user_ids: Optional[Iterable] = None, role_ids: Optional[Iterable] = None):
+        """Active users of ``tenant``. When ids are given, only users with one of ``user_ids`` or holding one of
+        the (active) roles in ``role_ids``. Returns a queryset of ``AUTH_USER_MODEL``."""
+
+    @abstractmethod
+    def role_ids_of(self, user) -> set:
+        """Ids of the active roles ``user`` holds."""
+
+    @abstractmethod
+    def roles(self, tenant):
+        """Active roles of ``tenant`` (queryset of ``APPROVALS_ROLE_MODEL``)."""
+
+    @abstractmethod
+    def role_member_count(self, role) -> int:
+        """Number of active members holding ``role`` (shown in approver pickers)."""
+
+    # --- permissions ---------------------------------------------------------------------------
+
+    @abstractmethod
+    def has_permission(self, user, codename: str) -> bool:
+        """Whether ``user`` holds the approvals permission ``codename`` (e.g. ``approve_user_create``)."""
+
+    @abstractmethod
+    def role_has_permission(self, role, codename: str) -> bool:
+        """Whether members of ``role`` get the approvals permission ``codename`` through it."""
+
+    # --- scopes --------------------------------------------------------------------------------
+
+    def is_enabled(self, tenant) -> bool:
+        """Whether maker-checker is switched on for ``tenant`` (e.g. a feature flag or a plan the host sells).
+
+        While it is off the tenant is treated as having no rules: guarded actions run immediately and the SLA job
+        leaves its requests alone. Rules, history and requests are kept, so switching it back on resumes where it
+        stopped. Requests still open when it is switched off stay open; cancel them first if they must not linger.
+        """
+        return True
+
+    def scope_label(self, tenant, scope_key: str) -> str:
+        """Human name of a scope key returned by a handler's ``scope_keys`` (e.g. a department or account group)."""
+        return scope_key
+
+    # --- side effects --------------------------------------------------------------------------
+
+    @abstractmethod
+    def notify(self, notice: Notice) -> None:
+        """Deliver ``notice`` (in-app, email, chat…). Called after the transaction commits."""
+
+    @abstractmethod
+    def audit(self, record: AuditRecord) -> None:
+        """Write ``record`` to the host's audit log."""
+
+    def request_url(self, approval_request) -> str:
+        """Absolute or site-relative link to the request in the host UI (used in notifications)."""
+        return ""
+
+    # --- presentation helpers ------------------------------------------------------------------
+
+    def user_label(self, user) -> str:
+        """How a user is named in timelines, pickers and history; ``None`` means an automated (system) actor."""
+        return (user.get_full_name() or user.get_username()) if user else "System"
+
+    def role_label(self, role) -> str:
+        return str(role)

django_maker_checker/admin.py

@@ -0,0 +1,86 @@
+"""Django admin views of maker-checker data, for inspection by staff.
+
+Every page here is read-only. Changes must go through ``services`` and ``policies``, which enforce the rules
+(segregation of duties, approver eligibility) and record the audit trail (request events, policy revisions, host
+audit records). An editable admin would let staff bypass both.
+"""
+
+from django.contrib import admin
+
+from django_maker_checker import models
+
+
+class ReadOnlyAdmin(admin.ModelAdmin):
+    """Shows every field and allows no add, change or delete."""
+
+    def get_readonly_fields(self, request, obj=None):
+        return [f.name for f in self.model._meta.fields]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+class ReadOnlyInline(admin.TabularInline):
+    extra = 0
+    can_delete = False
+
+    def get_readonly_fields(self, request, obj=None):
+        return [f.name for f in self.model._meta.fields]
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+class PolicyApproverInline(ReadOnlyInline):
+    model = models.ApprovalPolicyApprover
+
+
+class RevisionInline(ReadOnlyInline):
+    model = models.ApprovalPolicyRevision
+    fields = ("version", "change_type", "changes", "reason", "actor", "created")
+
+
+@admin.register(models.ApprovalPolicy)
+class ApprovalPolicyAdmin(ReadOnlyAdmin):
+    list_display = ("tenant", "action_type", "scope_key", "workflow_type", "is_enabled", "sla_enabled", "updated")
+    list_filter = ("action_type", "workflow_type", "is_enabled")
+    inlines = [PolicyApproverInline, RevisionInline]
+
+
+@admin.register(models.ApprovalPolicyRevision)
+class ApprovalPolicyRevisionAdmin(ReadOnlyAdmin):
+    """All revisions, including those of deleted rules (which no longer appear under a policy)."""
+
+    list_display = ("tenant", "action_type", "scope_key", "version", "change_type", "actor", "created")
+    list_filter = ("action_type", "change_type")
+
+
+class StageInline(ReadOnlyInline):
+    model = models.ApprovalStage
+
+
+class DecisionInline(ReadOnlyInline):
+    model = models.ApprovalDecision
+
+
+class EventInline(ReadOnlyInline):
+    model = models.ApprovalEvent
+
+
+@admin.register(models.ApprovalRequest)
+class ApprovalRequestAdmin(ReadOnlyAdmin):
+    list_display = ("reference", "tenant", "action_type", "target_label", "maker", "status", "submitted_at")
+    list_filter = ("status", "action_type")
+    search_fields = ("reference", "target_label", "maker__email", "maker__username")
+    inlines = [StageInline, DecisionInline, EventInline]
+
+
+@admin.register(models.ApprovalDelegation)
+class ApprovalDelegationAdmin(ReadOnlyAdmin):
+    list_display = ("tenant", "delegator", "delegate", "starts_at", "ends_at", "revoked_at")

django_maker_checker/apps.py

@@ -0,0 +1,14 @@
+"""Django app configuration.
+
+The package is ``django_maker_checker`` but the app label is ``approvals``, which keeps table names (``approvals_*``)
+and migration history stable for hosts.
+"""
+
+from django.apps import AppConfig
+
+
+class ApprovalsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_maker_checker"
+    label = "approvals"
+    verbose_name = "Approvals (Maker-Checker)"

django_maker_checker/audit.py

@@ -0,0 +1,17 @@
+"""Hand audit records to the host without letting an audit-sink failure break the operation being audited."""
+
+import logging
+
+from django_maker_checker.conf import get_adapter
+
+logger = logging.getLogger(__name__)
+
+
+def send(record):
+    """Pass ``record`` to ``adapter.audit``. Failures are logged and swallowed: the engine's own records (request
+    events, policy revisions) are written in the same transaction and stay authoritative, so an unavailable audit
+    sink must not roll back a decision or a rule change."""
+    try:
+        get_adapter().audit(record)
+    except Exception:  # noqa: BLE001 - the engine's own records (events, revisions) are authoritative
+        logger.exception("Audit sink failed for %s %s", record.resource_type, record.resource_id)

django_maker_checker/conf.py

@@ -0,0 +1,54 @@
+"""Settings read by the engine.
+
+``APPROVALS_TENANT_MODEL``  "app_label.Model" of the tenant (required; referenced by migrations)
+``APPROVALS_ROLE_MODEL``    "app_label.Model" of a tenant role that can be named as an approver (required)
+``APPROVALS_ADAPTER``       dotted path of the ``ApprovalsAdapter`` subclass (required)
+``APPROVALS_CACHE_TIMEOUT`` seconds the per-user pending count is cached (default 60)
+``APPROVALS_CACHE_ALIAS``   cache used for pending counts (default "default")
+``APPROVALS_REFERENCE_PREFIX`` prefix of request references, as in ``REQ-2610-00042`` (default "REQ")
+"""
+
+from functools import cache
+
+from django.conf import settings
+from django.core.cache import caches
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+
+
+def _required(name):
+    value = getattr(settings, name, None)
+    if not value:
+        raise ImproperlyConfigured(f"django_maker_checker requires the {name} setting")
+    return value
+
+
+def tenant_model_name():
+    return _required("APPROVALS_TENANT_MODEL")
+
+
+def role_model_name():
+    return _required("APPROVALS_ROLE_MODEL")
+
+
+def cache_timeout():
+    return getattr(settings, "APPROVALS_CACHE_TIMEOUT", 60)
+
+
+def counts_cache():
+    return caches[getattr(settings, "APPROVALS_CACHE_ALIAS", "default")]
+
+
+def reference_prefix():
+    return getattr(settings, "APPROVALS_REFERENCE_PREFIX", "REQ")
+
+
+# Adapters are stateless, so one instance per dotted path is reused for the life of the process.
+@cache
+def _adapter_for(path):
+    return import_string(path)()
+
+
+def get_adapter():
+    """The configured adapter instance (one per process)."""
+    return _adapter_for(_required("APPROVALS_ADAPTER"))

django_maker_checker/constants.py

@@ -0,0 +1,126 @@
+"""Fixed vocabularies of the engine: request statuses, workflows, SLA units and states, risk levels, decisions,
+timeline event types and policy change types. Values are stored in the database, so they must not be renamed."""
+
+
+class RequestStatus:
+    PENDING = "pending"
+    APPROVED = "approved"
+    EXECUTED = "executed"
+    REJECTED = "rejected"
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+
+    CHOICES = [
+        (PENDING, "Pending"),
+        (APPROVED, "Approved"),
+        (EXECUTED, "Approved & Executed"),
+        (REJECTED, "Rejected"),
+        (CANCELLED, "Cancelled"),
+        (FAILED, "Execution Failed"),
+    ]
+    # Statuses that hold the resource lock: a second request for the same target is refused.
+    OPEN = (PENDING, APPROVED)
+    TERMINAL = (EXECUTED, REJECTED, CANCELLED, FAILED)
+
+
+class WorkflowType:
+    """How a policy's approver slots become stages: SINGLE and MULTI are one stage (MULTI with any-one or all
+    approvers, per ``require_all``); SEQUENTIAL is one stage per slot, in order."""
+
+    SINGLE = "single"
+    MULTI = "multi"
+    SEQUENTIAL = "sequential"
+
+    CHOICES = [
+        (SINGLE, "Single Approver"),
+        (MULTI, "Multiple Approvers"),
+        (SEQUENTIAL, "Approval Flow"),
+    ]
+
+
+class SlaUnit:
+    MINUTES = "minutes"
+    HOURS = "hours"
+    DAYS = "days"
+
+    CHOICES = [(MINUTES, "Minutes"), (HOURS, "Hours"), (DAYS, "Days")]
+    TO_MINUTES = {MINUTES: 1, HOURS: 60, DAYS: 60 * 24}
+
+
+class RiskLevel:
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+    CHOICES = [(LOW, "Low"), (MEDIUM, "Medium"), (HIGH, "High")]
+
+
+class Decision:
+    APPROVE = "approve"
+    REJECT = "reject"
+
+    CHOICES = [(APPROVE, "Approve"), (REJECT, "Reject")]
+
+
+class EventType:
+    CREATED = "created"
+    NOTIFIED = "notified"
+    VIEWED = "viewed"
+    SLA_WARNING = "sla_warning"
+    ESCALATED = "escalated"
+    STAGE_APPROVED = "stage_approved"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    CANCELLED = "cancelled"
+    COMMENT = "comment"
+    DELEGATED = "delegated"
+    EXECUTED = "executed"
+    FAILED = "failed"
+    RETRIED = "retried"
+
+    CHOICES = [
+        (CREATED, "Submitted"),
+        (NOTIFIED, "Notified"),
+        (VIEWED, "Viewed"),
+        (SLA_WARNING, "SLA Warning"),
+        (ESCALATED, "Escalated"),
+        (STAGE_APPROVED, "Stage Approved"),
+        (APPROVED, "Approved"),
+        (REJECTED, "Rejected"),
+        (CANCELLED, "Cancelled"),
+        (COMMENT, "Comment"),
+        (DELEGATED, "Delegated"),
+        (EXECUTED, "Executed"),
+        (FAILED, "Execution Failed"),
+        (RETRIED, "Retried"),
+    ]
+
+
+class SlaState:
+    """Display state of a stage's SLA, derived from elapsed time; it is never stored."""
+
+    ON_TRACK = "on_track"
+    AT_RISK = "at_risk"
+    ESCALATED = "escalated"
+    NONE = "none"
+
+    LABELS = {ON_TRACK: "On Track", AT_RISK: "At Risk", ESCALATED: "Escalated", NONE: "No SLA"}
+    # Share of the SLA window after which a request is shown as at risk / gets a reminder.
+    AT_RISK_RATIO = 0.6
+    WARNING_RATIO = 0.75
+
+
+class PolicyChange:
+    CREATED = "created"
+    UPDATED = "updated"
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+    DELETED = "deleted"
+
+    CHOICES = [
+        (CREATED, "Created"),
+        (UPDATED, "Updated"),
+        (ENABLED, "Enabled"),
+        (DISABLED, "Disabled"),
+        (DELETED, "Deleted"),
+    ]

django_maker_checker/exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions raised to callers. Messages are written for end users, since hosts usually show them as-is."""
+
+
+class ApprovalError(Exception):
+    """A maker-checker operation was refused; the message is safe to show to the user."""
+
+
+class ApprovalPending(ValueError):
+    """Raised from inside a guarded action when a maker-checker request was created instead.
+
+    Subclasses ValueError so callers that already surface ValueError messages degrade gracefully;
+    known callers catch it explicitly and report it as a success ("submitted for approval").
+    """
+
+    def __init__(self, approval_request):
+        # Keep the request so callers can show its reference or link to it.
+        self.approval_request = approval_request
+        super().__init__(
+            f"Submitted for approval as {approval_request.reference}. "
+            "The change will be applied once a checker approves it."
+        )

django_maker_checker/management/commands/process_approval_slas.py

@@ -0,0 +1,20 @@
+"""Run the SLA pass once: reminders and escalation of overdue approval steps.
+
+For projects without Celery, schedule it with cron or any job runner, e.g. every 5 minutes:
+
+    */5 * * * *  python manage.py process_approval_slas
+
+It is safe to run concurrently and repeatedly (see ``services.process_sla``).
+"""
+
+from django.core.management.base import BaseCommand
+
+from django_maker_checker.services import process_sla
+
+
+class Command(BaseCommand):
+    help = "Send SLA reminders and escalate overdue approval steps."
+
+    def handle(self, *args, **options):
+        summary = process_sla()
+        self.stdout.write(f"Warned {summary['warned']}, escalated {summary['escalated']}.")