auditrum 0.2.0__py3-none-any.whl

auditrum/integrations/django/shell_context.py

@@ -0,0 +1,3 @@
+from .utils import audit_tracked
+
+audit_tracked(source="shell").__enter__()

auditrum/integrations/django/templates/audit/object_history.html

@@ -0,0 +1,58 @@
+
+
+{% extends "admin/base_site.html" %}
+{% load i18n static %}
+
+{% block content %}
+<div class="app-auditlog module">
+    <h1>{{ title }}</h1>
+
+    {% if is_paginated %}
+    <div class="paginator">
+        {% if page_obj.has_previous %}
+            <a href="?page={{ page_obj.previous_page_number }}">&laquo; Previous</a>
+        {% endif %}
+        <span class="current">
+            Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}
+        </span>
+        {% if page_obj.has_next %}
+            <a href="?page={{ page_obj.next_page_number }}">Next &raquo;</a>
+        {% endif %}
+    </div>
+    {% endif %}
+
+    <table class="admin-auditlog-table" style="width: 100%; border-collapse: collapse;">
+        <thead>
+            <tr>
+                <th>Changed At</th>
+                <th>Operation</th>
+                <th>User</th>
+                <th>Source</th>
+                <th>Reason</th>
+                <th>Diff</th>
+            </tr>
+        </thead>
+        <tbody>
+        {% for log in audit_logs %}
+            <tr>
+                <td>{{ log.changed_at }}</td>
+                <td>{{ log.operation }}</td>
+                <td>{{ log.user_id }}</td>
+                <td>{{ log.source }}</td>
+                <td>{{ log.change_reason|default:"–" }}</td>
+                <td>
+                    <details>
+                        <summary>View</summary>
+                        <pre style="white-space: pre-wrap;">{{ log.diff|default:"–" }}</pre>
+                    </details>
+                </td>
+            </tr>
+        {% empty %}
+            <tr>
+                <td colspan="6">No audit records found.</td>
+            </tr>
+        {% endfor %}
+        </tbody>
+    </table>
+</div>
+{% endblock %}

auditrum/integrations/django/templatetags/audit_tags.py

@@ -0,0 +1,14 @@
+from django import template
+
+register = template.Library()
+
+
+@register.simple_tag
+def render_diff(diff: dict) -> str:
+    if not diff:
+        return "-"
+    lines = []
+    for field, values in diff.items():
+        old, new = values
+        lines.append(f"{field}: {old} → {new}")
+    return "\n".join(lines)

auditrum/integrations/django/utils.py

@@ -0,0 +1,172 @@
+from contextlib import contextmanager
+
+from django.contrib.admin.templatetags.admin_urls import admin_urlname
+from django.db import models, connection
+from django.shortcuts import resolve_url
+from django.utils.formats import date_format
+from django.utils.html import format_html
+from django.utils.safestring import mark_safe
+from django.utils import timezone
+
+
+def link(href: str, text: str) -> str:
+    return format_html('<a href="{}">{}</a>', href, text)
+
+
+def link_to_related_object(obj: models.Model, name: str = None) -> str:
+    url = resolve_url(admin_urlname(obj._meta, "change"), obj.pk)
+    return link(url, name or str(obj))
+
+
+def resolve_field_value(model_class, field_name, value):
+    try:
+        field = model_class._meta.get_field(field_name)
+        label = field.verbose_name.title()
+
+        # Handle choices
+        if field.choices and value is not None:
+            value = dict(field.choices).get(value, value)
+
+        # ForeignKey → str(obj)
+        elif isinstance(field, models.ForeignKey) and value:
+            try:
+                value = str(field.remote_field.model.objects.get(pk=value))
+            except field.remote_field.model.DoesNotExist:
+                value = f"[{value}]"
+
+        # Date / Time fields
+        elif isinstance(field, (models.DateTimeField, models.DateField, models.TimeField)) and value:
+            try:
+                parsed = value
+                if isinstance(value, str):
+                    parsed = timezone.datetime.fromisoformat(value)
+                if isinstance(field, models.DateTimeField):
+                    value = date_format(parsed, format="DATETIME_FORMAT")
+                elif isinstance(field, models.DateField):
+                    value = date_format(parsed, format="DATE_FORMAT")
+                elif isinstance(field, models.TimeField):
+                    value = date_format(parsed, format="TIME_FORMAT")
+            except Exception:
+                pass
+
+    except Exception:
+        label = field_name
+    return label, value or "—"
+
+
+def get_user_display(log):
+    return getattr(log.user, "username", None) or log.meta.get("username") or "System"
+
+
+def render_log_changes(log):
+    if log.content_type is None:
+        return "—"
+
+    model_class = log.content_type.model_class()
+
+    if log.operation == "INSERT" and log.new_data:
+        return format_html(
+            "<ul class='space-y-1'>{}</ul>",
+            mark_safe(
+                "".join(
+                    format_html("<li><strong>{}</strong>: {}</li>", *resolve_field_value(model_class, k, v))
+                    for k, v in log.new_data.items()
+                )
+            ),
+        )
+
+    elif log.operation == "DELETE" and log.old_data:
+        return format_html(
+            "<ul class='space-y-1 text-red-700'>{}</ul>",
+            mark_safe(
+                "".join(
+                    format_html(
+                        "<li><strong>{}</strong>: <span class='line-through'>{}</span></li>",
+                        *resolve_field_value(model_class, k, v),
+                    )
+                    for k, v in log.old_data.items()
+                )
+            ),
+        )
+
+    elif log.old_data and log.new_data:
+        diffs = []
+        for key in sorted(set(log.old_data) | set(log.new_data)):
+            old_val = log.old_data.get(key)
+            new_val = log.new_data.get(key)
+            if old_val != new_val:
+                label, old_str = resolve_field_value(model_class, key, old_val)
+                _, new_str = resolve_field_value(model_class, key, new_val)
+                diffs.append(
+                    format_html(
+                        "<li><strong>{}</strong>: <span class='line-through text-red-600'>{}</span> <span class='text-gray-400 px-1'>→</span> <span class='text-green-700 font-medium'>{}</span></li>",
+                        label,
+                        old_str,
+                        new_str,
+                    )
+                )
+        return (
+            format_html("<ul class='space-y-1'>{}</ul>", mark_safe("".join(diffs)))
+            if diffs
+            else mark_safe("<em class='text-gray-500'>No changes</em>")
+        )
+
+    return mark_safe("<em class='text-gray-500'>No changes</em>")
+
+
+def get_changed_object(log):
+    if log.content_object:
+        original_model_name = log.content_object.__class__.__name__
+        if hasattr(log.content_object, "auction") and original_model_name.lower() in ("lot", "bid", "invoice", "sale"):
+            auction = log.content_object.auction
+            if not isinstance(auction, str):
+                auction = auction.id
+
+            model_name = f"{auction.capitalize()}{original_model_name}"
+            proxy_model = apps.get_model(auction, model_name)
+            instance = proxy_model.objects.get(id=log.object_id)
+        else:
+            instance = log.content_object
+
+        try:
+            return link_to_related_object(instance, str(log.content_object))
+        except Exception:
+            return str(log.content_object)
+    return "-"
+
+
+def set_var(cursor, key, value):
+    if value is not None:
+        cursor.execute(f"SET {key} = %s", [str(value)])
+
+
+# def set_audit_context():
+#     cursor = connection.cursor()
+#     ctx = get_audit_context_data()
+#     reason = get_change_reason()
+#     if reason:
+#         ctx["change_reason"] = reason
+#     for key, value in ctx.items():
+#         set_var(cursor, f"session.myapp_{key}", value)
+
+
+@contextmanager
+def audit_tracked(**kwargs):
+    """
+    A context manager to set session-local audit context for manual or automated actions.
+    Useful for management commands, cron jobs, etc.
+
+    Example:
+        with audit_tracked(change_reason="Sync job", source="cron"):
+            ...
+    """
+    from auditrum.context import audit_context
+
+    with audit_context.use(**kwargs), audit_context.use_change_reason(kwargs.get("change_reason", "system action")):
+        from django.db import connection
+        sql = audit_context.build_sql()
+        with connection.cursor() as cursor:
+            for stmt in sql.strip().split(";"):
+                if stmt.strip():
+                    cursor.execute(stmt)
+        yield

auditrum/revert.py

@@ -0,0 +1,39 @@
+from typing import List
+
+
+def get_revert_columns_from_log(conn, audit_table: str, log_id: int) -> List[str]:
+    with conn.cursor() as cur:
+        cur.execute(
+            f"""
+            SELECT jsonb_object_keys(old_data)
+            FROM {audit_table}
+            WHERE id = %s
+        """,
+            (log_id,),
+        )
+        keys = cur.fetchall()
+    return [row[0] for row in keys]
+
+
+def generate_revert_sql(
+    audit_table: str, table_name: str, record_id: str, log_id: int, columns: List[str]
+) -> str:
+    return f"""
+WITH audit_entry AS (
+    SELECT old_data
+    FROM {audit_table}
+    WHERE id = {log_id}
+    AND table_name = '{table_name}'
+)
+UPDATE {table_name}
+SET {", ".join([f"{col} = audit_entry.old_data->>'{col}'" for col in columns])}
+FROM audit_entry
+WHERE {table_name}.id = '{record_id}';
+""".strip()
+
+
+def generate_revert_sql_from_log(
+    conn, audit_table: str, table_name: str, record_id: str, log_id: int
+) -> str:
+    columns = get_revert_columns_from_log(conn, audit_table, log_id)
+    return generate_revert_sql(audit_table, table_name, record_id, log_id, columns)

auditrum/schema.py

@@ -0,0 +1,79 @@
+from datetime import UTC, datetime
+
+from dateutil.relativedelta import relativedelta
+
+
+def generate_auditlog_table_sql(table_name: str = "auditlog") -> str:
+    return f"""
+CREATE TABLE IF NOT EXISTS {table_name} (
+    id serial,
+    operation text NOT NULL,
+    changed_at timestamp with time zone NOT NULL DEFAULT now(),
+    content_type_id integer,
+    object_id text,
+    table_name text NOT NULL,
+    user_id integer,
+    old_data jsonb,
+    new_data jsonb,
+    diff jsonb,
+    meta jsonb,
+    request_id text,
+    change_reason text,
+    source text
+) PARTITION BY RANGE (changed_at);
+
+CREATE INDEX IF NOT EXISTS {table_name}_id_idx ON {table_name} (id);
+
+-- Initial partition
+CREATE TABLE IF NOT EXISTS {table_name}_p0
+    PARTITION OF {table_name}
+    FOR VALUES FROM ('2000-01-01') TO ('2025-01-01');
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS {table_name}_table_name_idx ON {table_name} (table_name);
+CREATE INDEX IF NOT EXISTS {table_name}_user_id_idx ON {table_name} (user_id);
+CREATE INDEX IF NOT EXISTS {table_name}_changed_at_idx ON {table_name} (changed_at);
+CREATE INDEX IF NOT EXISTS {table_name}_object_id_idx ON {table_name} (object_id);
+CREATE INDEX IF NOT EXISTS {table_name}_request_id_idx ON {table_name} (request_id);
+CREATE INDEX IF NOT EXISTS {table_name}_source_idx ON {table_name} (source);
+CREATE INDEX IF NOT EXISTS {table_name}_meta_gin_idx ON {table_name} USING GIN (meta);
+CREATE INDEX IF NOT EXISTS {table_name}_diff_gin_idx ON {table_name} USING GIN (diff);
+""".strip()
+
+
+def generate_auditlog_partitions_sql(table_name: str = "auditlog", months_ahead: int = 3) -> str:
+    now = datetime.now(UTC).replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    parts = []
+
+    for i in range(months_ahead):
+        start = now + relativedelta(months=i)
+        end = start + relativedelta(months=1)
+        start_str = start.strftime("%Y-%m-%d")
+        end_str = end.strftime("%Y-%m-%d")
+        suffix = start.strftime("p%Y_%m")
+
+        parts.append(
+            f"""
+CREATE TABLE IF NOT EXISTS {table_name}_{suffix}
+    PARTITION OF {table_name}
+    FOR VALUES FROM ('{start_str}') TO ('{end_str}');
+""".strip()
+        )
+
+    return "\n\n".join(parts)
+
+
+# Function to generate SQL for a custom jsonb_diff() function in PostgreSQL
+def generate_jsonb_diff_function_sql() -> str:
+    return """
+CREATE OR REPLACE FUNCTION jsonb_diff(old jsonb, new jsonb)
+RETURNS jsonb AS $$
+BEGIN
+  RETURN (
+    SELECT jsonb_object_agg(key, value)
+    FROM jsonb_each(new)
+    WHERE old -> key IS DISTINCT FROM value
+  );
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;
+""".strip()

auditrum/settings.py

@@ -0,0 +1,20 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class PgAuditSettings(BaseSettings):
+    audit_table: str = Field("auditlog", alias="AUDIT_TABLE")
+
+    pg_host: str = Field(..., alias="PGHOST")
+    pg_port: int = Field(5432, alias="PGPORT")
+    pg_user: str = Field(..., alias="PGUSER")
+    pg_password: str = Field(..., alias="PGPASSWORD")
+    pg_dbname: str = Field(..., alias="PGDATABASE")
+
+    @property
+    def db_dsn(self) -> str:
+        return f"postgresql://{self.pg_user}:{self.pg_password}@{self.pg_host}:{self.pg_port}/{self.pg_dbname}"
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = False

auditrum/triggers.py

@@ -0,0 +1,118 @@
+def generate_trigger_sql(
+    table_name: str,
+    audit_table: str = "auditlog",
+    track_only: list[str] | None = None,
+    exclude_fields: list[str] | None = None,
+    log_conditions: str | None = None,
+    meta_fields: list[str] | None = None,
+) -> str:
+    if track_only is not None and exclude_fields is not None:
+        raise ValueError(
+            f"Cannot specify both track_only and exclude_fields for table {table_name}"
+        )
+
+    if track_only is not None:
+        track_only_keys = [f"'{k}'" for k in track_only]
+        keys_tuple = "(" + ", ".join(track_only_keys) + ")"
+        # We want to ignore keys NOT in track_only
+        ignored_keys_expr = f"ARRAY(SELECT key FROM jsonb_object_keys(to_jsonb(NEW)) AS key(key) WHERE key.key NOT IN {keys_tuple})::text[]"
+    elif exclude_fields is not None:
+        ignored_keys = [f"'{k}'" for k in exclude_fields]
+        ignored_keys_expr = f"ARRAY[{', '.join(ignored_keys)}]::text[]"
+    else:
+        ignored_keys_expr = "ARRAY[]::text[]"
+
+    default_meta_fields = [
+        "'username', current_setting('session.myapp_username', true)",
+        "'client_ip', current_setting('session.myapp_client_ip', true)",
+        "'user_agent', current_setting('session.myapp_user_agent', true)",
+        "'session_key', current_setting('session.myapp_session_key', true)",
+        "'source', current_setting('session.myapp_source', true)",
+        "'request_id', current_setting('session.myapp_request_id', true)",
+        "'change_reason', current_setting('session.myapp_change_reason', true)"
+    ]
+
+    if meta_fields:
+        extra_fields = [f"'{field}', to_jsonb(NEW.{field})" for field in meta_fields]
+        meta_fields_expr = ", ".join(default_meta_fields + extra_fields)
+    else:
+        meta_fields_expr = ", ".join(default_meta_fields)
+
+    log_conditions_expr = f"""
+    IF NOT ({log_conditions}) THEN
+        RETURN NULL;
+    END IF;
+""" if log_conditions else ""
+
+    function_name = f"audit_{table_name}_trigger"
+
+    sql = f"""
+CREATE OR REPLACE FUNCTION {function_name}() RETURNS trigger AS $$
+DECLARE
+    data JSONB;
+    diff JSONB;
+    ignored_keys TEXT[] := {ignored_keys_expr};
+    old_filtered jsonb := to_jsonb(OLD);
+    new_filtered jsonb := to_jsonb(NEW);
+    key text;
+BEGIN
+{log_conditions_expr}
+    FOREACH key IN ARRAY ignored_keys LOOP
+        old_filtered := old_filtered - key;
+        new_filtered := new_filtered - key;
+    END LOOP;
+    RAISE NOTICE 'IGNORED_KEYS: %', ignored_keys;
+    
+    IF (TG_OP = 'UPDATE') THEN
+        diff = jsonb_strip_nulls(jsonb_diff(old_filtered, new_filtered));
+        RAISE NOTICE 'Diff after filtering: %', diff;
+        RAISE NOTICE 'Diff is null?: %',  diff is null;
+        IF diff is null THEN
+            RETURN NULL;
+        END IF;
+    ELSIF TG_OP = 'INSERT' THEN
+        diff = new_filtered;
+        IF diff is null THEN
+            RETURN NULL;
+        END IF;
+    ELSIF TG_OP = 'DELETE' THEN
+        diff = old_filtered;
+        IF diff is null THEN
+            RETURN NULL;
+        END IF;
+    END IF;
+
+    IF (TG_OP = 'DELETE') THEN
+        data = to_jsonb(OLD);
+    ELSE
+        data = to_jsonb(NEW);
+    END IF;
+
+    INSERT INTO {audit_table} (
+        operation, changed_at, content_type_id, object_id, table_name,
+        user_id, old_data, new_data, diff, meta, request_id, change_reason, source
+    )
+    VALUES (
+        TG_OP, now(), NULL, NULL, TG_TABLE_NAME,
+        NULL, 
+        CASE WHEN TG_OP IN ('UPDATE', 'DELETE') THEN to_jsonb(OLD) ELSE NULL END,
+        CASE WHEN TG_OP IN ('UPDATE', 'INSERT') THEN to_jsonb(NEW) ELSE NULL END,
+        CASE WHEN TG_OP = 'UPDATE' THEN diff ELSE NULL END,
+        jsonb_build_object({meta_fields_expr}),
+        current_setting('session.myapp_request_id', true),
+        current_setting('session.myapp_change_reason', true),
+        current_setting('session.myapp_source', true)
+    );
+
+    RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS {function_name} ON {table_name};
+
+CREATE TRIGGER {function_name}
+AFTER INSERT OR UPDATE OR DELETE ON {table_name}
+FOR EACH ROW EXECUTE FUNCTION {function_name}();
+"""
+    print(f"Generated trigger SQL for table '{table_name}':\n{sql}")
+    return sql.strip()