flask-postgresql-audit 1.0.9__tar.gz → 1.1.1__tar.gz

{flask_postgresql_audit-1.0.9 → flask_postgresql_audit-1.1.1}/.gitignore

@@ -22,6 +22,7 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
+.env*
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -63,3 +64,6 @@ uv.lock
 
 # VSCode
 .vscode
+
+# Agents
+.agents

{flask_postgresql_audit-1.0.9 → flask_postgresql_audit-1.1.1}/CHANGES.md

@@ -3,6 +3,63 @@
 Here you can see the full list of changes between each Flask-PostgreSQL-Audit
 release.
 
+## 1.1.1 (2026-08-08)
+
+-   Fix test teardown downgrade error in migration listener.
+-   Fix `pg_audit_enabled` state thread-safety using `ContextVar`.
+-   Quote schema names and parameterize schema existence queries in Alembic operations.
+-   Remove unused templates and unused `hybridmethod` descriptor.
+-   Document `DocumentStaging` and `PGAggregate` extensions in `README.md`.
+
+## 1.1.0 (2026-08-07)
+
+-   Bump `alembic` dependency to `>=1.18.0`.
+-   Refactor Alembic integration to use the official Plugin API and DispatchPriority system.
+-   Add multi-schema test matrix and schema-aware support to the test suite.
+-   Modernize Python type annotations, imports, string formatting, and clean up code using Ruff.
+-   Simplify context managers and type-hint fixtures in tests.
+
+## 1.0.9 (2026-08-07)
+
+-   Change `fetch_activity` join clause to `outerjoin`.
+-   Resolve type checking errors.
+
+## 1.0.8 (2026-03-30)
+
+-   Update `Audit` mixin class and refactor `fetch_activity` method, removing rowkey filter on class scope.
+-   Add PostgreSQL function `get_table_relid`.
+-   Fix `get_pk_values` returns wrong jsonb type if primary key columns are null.
+
+## 1.0.7 (2025-12-15)
+
+-   Fix cartesian join when providing a table model to `fetch_activity()`.
+
+## 1.0.6 (2025-12-15)
+
+-   Add `fetch_activity()` statement constructor with optional `verb` filtering, ordered by ID descending.
+-   Add `hybridmethod` descriptor.
+-   Add extension `document_staging`.
+
+## 1.0.5 (2025-11-27)
+
+-   Add `alembic_utils` extension `pg_aggregate`.
+
+## 1.0.4 (2025-11-17)
+
+-   Fix: use explicit schema prefix to call `get_pk_values()` in `create_activity`.
+
+## 1.0.3 (2025-11-14)
+
+-   Fix: use schema prefix when calling `jsonb_subtract()` in audit trigger functions.
+
+## 1.0.2 (2025-11-14)
+
+-   Support optional verbose value comparison in `jsonb_subtract()`.
+
+## 1.0.1 (2025-10-30)
+
+-   Update authors in `pyproject.toml` and update `README.md`.
+
 ## 1.0.0 (2025-10-30)
 
 -   Forked from PostgreSQL-Audit.

{flask_postgresql_audit-1.0.9 → flask_postgresql_audit-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
-Name: flask-postgresql_audit
-Version: 1.0.9
+Name: flask-postgresql-audit
+Version: 1.1.1
 Summary: Versioning and auditing extension for PostgreSQL and SQLAlchemy.
 Project-URL: Homepage, https://github.com/higamigu/flask-postgresql-audit
 Author-email: Higamigu <higamigu@gmail.com>, Konsta Vesterinen <konsta@fastmonkeys.com>
@@ -19,7 +19,7 @@ Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Requires-Dist: alembic-utils>=0.8.8
-Requires-Dist: alembic>=1.17.0
+Requires-Dist: alembic>=1.18.0
 Requires-Dist: flask-sqlalchemy>=3.1.1
 Requires-Dist: flask>=3.1.2
 Requires-Dist: psycopg2>=2.9.11
@@ -52,7 +52,7 @@ uv add flask-postgresql-audit
 ```
 or install directly from this repo
 ```
-uv add git+https://github.com/higamigu/flask-postgresql-audit --tag v1.0.0
+uv add git+https://github.com/higamigu/flask-postgresql-audit --tag v1.1.0
 ```
 
 ## Usage
@@ -66,16 +66,18 @@ from my_app import app  # your flask app
 db = SQLAlchemy()
 audit = PostgreSQLAudit()
 
+
 class Article(db.Model, Audit):
-    __tablename__ = 'article'
+    __tablename__ = "article"
 
     id = db.Column(db.Integer, primary_key=True)
     name = db.Column(db.String)
 
+
 db.init_app(app)
 audit.init_app(app, db)
 
-article = Article(name='Some article')
+article = Article(name="Some article")
 db.session.add(article)
 db.session.commit()
 ```
@@ -89,24 +91,24 @@ Now we can check the newly created activity.
 
 ``` python
 activity = db.session.scalar(select(audit.Activity))
-activity.id             # 1
-activity.table_name     # 'article'
-activity.verb           # 'insert'
-activity.old_data       # None
-activity.changed_data   # {'id': '1', 'name': 'Some article'}
+activity.id  # 1
+activity.table_name  # 'article'
+activity.verb  # 'insert'
+activity.old_data  # None
+activity.changed_data  # {'id': '1', 'name': 'Some article'}
 ```
 
 ``` python
-article.name = 'Some other article'
+article.name = "Some other article"
 db.session.commit()
 
 activity = db.session.scalar(select(audit.Activity).order_by(desc("id")))
-activity.id             # 2
-activity.table_name     # 'article'
-activity.verb           # 'update'
-activity.object_id      # 1
-activity.old_data       # {'id': '1', 'name': 'Some article'}
-activity.changed_data   # {'name': 'Some other article'}
+activity.id  # 2
+activity.table_name  # 'article'
+activity.verb  # 'update'
+activity.object_id  # 1
+activity.old_data  # {'id': '1', 'name': 'Some article'}
+activity.changed_data  # {'name': 'Some other article'}
 ```
 
 ``` python
@@ -114,14 +116,34 @@ db.session.delete(article)
 db.session.commit()
 
 activity = db.session.scalar(select(audit.Activity).order_by(desc("id")))
-activity.id             # 3
-activity.table_name     # 'article'
-activity.verb           # 'delete'
-activity.object_id      # 1
-activity.old_data       # {'id': '1', 'name': 'Some other article'}
-activity.changed_data   # None
+activity.id  # 3
+activity.table_name  # 'article'
+activity.verb  # 'delete'
+activity.object_id  # 1
+activity.old_data  # {'id': '1', 'name': 'Some other article'}
+activity.changed_data  # None
+```
+
+## Querying Activity History
+
+Instead of querying `audit.Activity` manually, you can use `fetch_activity()` to retrieve the audit trail for a model class, a single model instance, or a sequence/list of model instances:
+
+``` python
+# Query activity for a specific model class (e.g. Article)
+stmt = audit.fetch_activity(Article)
+activities = db.session.execute(stmt).all()
+
+# Query activity for a specific article instance
+stmt = audit.fetch_activity(article)
+activities = db.session.execute(stmt).all()
+
+# Query activity for multiple instances
+stmt = audit.fetch_activity([article1, article2])
+activities = db.session.execute(stmt).all()
 ```
 
+The returned statement is a SQLAlchemy `select` object that joins `Activity` and `Transaction` tables, ordered by activity ID descending. You can further customize or execute this statement.
+
 ## Different Schema
 You can isolate `pg_audit` objects entirely to a different schema by doing
 
@@ -159,6 +181,7 @@ You can customize actor id getter function by doing the following. Here is an ex
 ``` python
 from flask_jwt_extended import jwt_required, current_user
 
+
 @jwt_required(optional=True)
 def actor_id_getter():
     try:
@@ -166,6 +189,7 @@ def actor_id_getter():
     except Exception:
         return None
 
+
 ...
 
 audit = PostgreSQLAudit(actor_id_getter=actor_id_getter)
@@ -188,6 +212,88 @@ handlers =
 qualname = pg_audit
 ```
 
+## Troubleshooting
+
+### Activity not being recorded?
+
+1. **Check triggers are installed**: Run `flask db upgrade` after installing the extension
+2. **Verify audit is initialized**: Ensure you called `audit.init_app(app, db)` before using models
+3. **Commit after changes**: Audit records are only created on `db.session.commit()`
+
+### Actor tracking not working?
+
+The default actor ID getter tries to import `flask_login.current_user`. If you're not using Flask-Login:
+
+1. Provide your own `actor_id_getter` function:
+   ```python
+   def my_actor_id():
+       return current_user.id if current_user.is_authenticated else None
+   ```
+
+2. Pass it to the extension: `audit = PostgreSQLAudit(actor_id_getter=my_actor_id)`
+
+### Using a custom schema?
+
+1. Set schema when creating audit: `audit = PostgreSQLAudit(schema_name="my_schema")`
+2. Configure Alembic to track multiple schemas (see "Different Schema" section)
+3. Add `"include_schemas=True"` to `alembic/env.py` in `run_migrations_online()`
+
+### Fetching activity for custom models?
+
+The `fetch_activity()` method works with:
+- A model class: `audit.fetch_activity(MyModel)`
+- A single instance: `audit.fetch_activity(my_instance)`
+- Multiple instances: `audit.fetch_activity([instance1, instance2])`
+
+## Extensions
+
+### Document Staging
+
+The `document_staging` extension provides document lifecycle management and version revision tracking for models.
+
+```python
+from flask_postgresql_audit.extensions.document_staging import (
+    DocumentStaging,
+    Docstatus,
+    attach_listener,
+)
+
+
+class Article(BaseModel, DocumentStaging):
+    __tablename__ = "article"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str]
+
+
+# Attach session listener for automatic actor and timestamp tracking
+attach_listener()
+```
+
+#### Lifecycle & Transitions
+
+- **`Docstatus` states**: `DRAFT` (0), `SUBMITTED` (1), `CANCELLED` (2), `REVISED` (3).
+- **`doc.bump()`**: Advances document status (`DRAFT` -> `SUBMITTED` -> `CANCELLED`).
+- **`doc.revise(new_doc)`**: Creates a new revision `new_doc` from a `CANCELLED` document and sets state to `REVISED`.
+- **`doc.delete(session)`**: Deletes a `DRAFT` document. If it was a revision, reverts parent document status back to `CANCELLED`.
+- **Automatic Fields**: `created_by`, `created_on`, `submitted_by`, `submitted_on`, `cancelled_by`, `cancelled_on` are automatically set during session flush events.
+
+### Custom PostgreSQL Aggregates (`alembic_utils`)
+
+`PGAggregate` extends `alembic_utils` to manage custom PostgreSQL aggregate functions in Alembic migrations.
+
+```python
+from flask_postgresql_audit.extensions.alembic_utils import PGAggregate
+
+# Example: Define custom aggregate function entity
+sum_agg = PGAggregate(
+    schema="public",
+    signature="custom_sum(numeric)",
+    definition="(SFUNC = numeric_add, STYPE = numeric, INITCOND = '0')",
+)
+```
+
+Automatically detects and tracks custom `CREATE AGGREGATE` definitions during `alembic revision --autogenerate`.
+
 ## Running the tests
 
     git clone https://github.com/higamigu/flask-postgresql-audit.git

flask_postgresql_audit-1.1.1/README.md

@@ -0,0 +1,276 @@
+# Flask-PostgreSQL-Audit
+
+![BuildStatus](https://github.com/higamigu/flask-postgresql-audit/actions/workflows/test.yml/badge.svg?branch=main)
+[![VersionStatus](https://img.shields.io/pypi/v/flask-postgresql-audit.svg)](https://pypi.org/project/flask-postgresql-audit/)
+
+Auditing extension for Flask-SQLAlchemy with PostgreSQL.
+Forked from [PostgreSQL-Audit](https://github.com/kvesteri/postgresql-audit), tries to combine the best of breed from existing solutions such as
+[SQLAlchemy-Continuum](https://github.com/kvesteri/SQLAlchemy-Continuum),
+[Papertrail](https://github.com/airblade/paper_trail) and especially
+[Audit Trigger by 2ndQuadrant](https://github.com/2ndQuadrant/audit-trigger).
+
+-   Stores audit recordss into single table called `pga_activity`
+-   Uses trigger based approach to keep INSERTs, UPDATEs
+    and DELETEs as fast as possible
+-   Tracks and stores actor identities into table called `pga_transaction`
+-   Uses Alembic and Alembic-Utils to generate necessary database objects for migration
+
+## Installation
+```
+pip install flask-postgresql-audit
+```
+or using `uv`
+```
+uv add flask-postgresql-audit
+```
+or install directly from this repo
+```
+uv add git+https://github.com/higamigu/flask-postgresql-audit --tag v1.1.0
+```
+
+## Usage
+
+``` python
+from flask_sqlalchemy import SQLAlchemy
+from flask_postgresql_audit import PostgreSQLAudit, Audit
+
+from my_app import app  # your flask app
+
+db = SQLAlchemy()
+audit = PostgreSQLAudit()
+
+
+class Article(db.Model, Audit):
+    __tablename__ = "article"
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+
+
+db.init_app(app)
+audit.init_app(app, db)
+
+article = Article(name="Some article")
+db.session.add(article)
+db.session.commit()
+```
+Then generate migration file
+```
+flask db migrate -m "pg audit initial migration"
+flask db upgrade
+```
+
+Now we can check the newly created activity.
+
+``` python
+activity = db.session.scalar(select(audit.Activity))
+activity.id  # 1
+activity.table_name  # 'article'
+activity.verb  # 'insert'
+activity.old_data  # None
+activity.changed_data  # {'id': '1', 'name': 'Some article'}
+```
+
+``` python
+article.name = "Some other article"
+db.session.commit()
+
+activity = db.session.scalar(select(audit.Activity).order_by(desc("id")))
+activity.id  # 2
+activity.table_name  # 'article'
+activity.verb  # 'update'
+activity.object_id  # 1
+activity.old_data  # {'id': '1', 'name': 'Some article'}
+activity.changed_data  # {'name': 'Some other article'}
+```
+
+``` python
+db.session.delete(article)
+db.session.commit()
+
+activity = db.session.scalar(select(audit.Activity).order_by(desc("id")))
+activity.id  # 3
+activity.table_name  # 'article'
+activity.verb  # 'delete'
+activity.object_id  # 1
+activity.old_data  # {'id': '1', 'name': 'Some other article'}
+activity.changed_data  # None
+```
+
+## Querying Activity History
+
+Instead of querying `audit.Activity` manually, you can use `fetch_activity()` to retrieve the audit trail for a model class, a single model instance, or a sequence/list of model instances:
+
+``` python
+# Query activity for a specific model class (e.g. Article)
+stmt = audit.fetch_activity(Article)
+activities = db.session.execute(stmt).all()
+
+# Query activity for a specific article instance
+stmt = audit.fetch_activity(article)
+activities = db.session.execute(stmt).all()
+
+# Query activity for multiple instances
+stmt = audit.fetch_activity([article1, article2])
+activities = db.session.execute(stmt).all()
+```
+
+The returned statement is a SQLAlchemy `select` object that joins `Activity` and `Transaction` tables, ordered by activity ID descending. You can further customize or execute this statement.
+
+## Different Schema
+You can isolate `pg_audit` objects entirely to a different schema by doing
+
+``` python
+from flask_postgresql_audit import PostgreSQLAudit
+
+audit = PostgreSQLAudit(schema="audit")
+
+...
+```
+And then you need to tell alembic to track other than `public` schema by adding following line in `alembic/env.py`
+``` python
+...
+
+def run_migrations_online():
+    connectable = get_engine()
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=get_metadata(),
+            include_schemas=True, # add this arg
+            ...
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+...
+```
+
+## Custom Actor ID getter
+You can customize actor id getter function by doing the following. Here is an example using `current_user` from `flask_jwt_extended` library.
+
+``` python
+from flask_jwt_extended import jwt_required, current_user
+
+
+@jwt_required(optional=True)
+def actor_id_getter():
+    try:
+        return current_user.email or None
+    except Exception:
+        return None
+
+
+...
+
+audit = PostgreSQLAudit(actor_id_getter=actor_id_getter)
+
+...
+```
+
+## Enable Alembic Logger
+You can enable alembic logger for `pg_audit` by adding the following to your `alembic.ini`
+``` ini
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic,alembic_utils,pg_audit # add 'pg_audit' here
+
+...
+
+[logger_pg_audit]  # and add the logger for pg_audit here
+level = INFO
+handlers =
+qualname = pg_audit
+```
+
+## Troubleshooting
+
+### Activity not being recorded?
+
+1. **Check triggers are installed**: Run `flask db upgrade` after installing the extension
+2. **Verify audit is initialized**: Ensure you called `audit.init_app(app, db)` before using models
+3. **Commit after changes**: Audit records are only created on `db.session.commit()`
+
+### Actor tracking not working?
+
+The default actor ID getter tries to import `flask_login.current_user`. If you're not using Flask-Login:
+
+1. Provide your own `actor_id_getter` function:
+   ```python
+   def my_actor_id():
+       return current_user.id if current_user.is_authenticated else None
+   ```
+
+2. Pass it to the extension: `audit = PostgreSQLAudit(actor_id_getter=my_actor_id)`
+
+### Using a custom schema?
+
+1. Set schema when creating audit: `audit = PostgreSQLAudit(schema_name="my_schema")`
+2. Configure Alembic to track multiple schemas (see "Different Schema" section)
+3. Add `"include_schemas=True"` to `alembic/env.py` in `run_migrations_online()`
+
+### Fetching activity for custom models?
+
+The `fetch_activity()` method works with:
+- A model class: `audit.fetch_activity(MyModel)`
+- A single instance: `audit.fetch_activity(my_instance)`
+- Multiple instances: `audit.fetch_activity([instance1, instance2])`
+
+## Extensions
+
+### Document Staging
+
+The `document_staging` extension provides document lifecycle management and version revision tracking for models.
+
+```python
+from flask_postgresql_audit.extensions.document_staging import (
+    DocumentStaging,
+    Docstatus,
+    attach_listener,
+)
+
+
+class Article(BaseModel, DocumentStaging):
+    __tablename__ = "article"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str]
+
+
+# Attach session listener for automatic actor and timestamp tracking
+attach_listener()
+```
+
+#### Lifecycle & Transitions
+
+- **`Docstatus` states**: `DRAFT` (0), `SUBMITTED` (1), `CANCELLED` (2), `REVISED` (3).
+- **`doc.bump()`**: Advances document status (`DRAFT` -> `SUBMITTED` -> `CANCELLED`).
+- **`doc.revise(new_doc)`**: Creates a new revision `new_doc` from a `CANCELLED` document and sets state to `REVISED`.
+- **`doc.delete(session)`**: Deletes a `DRAFT` document. If it was a revision, reverts parent document status back to `CANCELLED`.
+- **Automatic Fields**: `created_by`, `created_on`, `submitted_by`, `submitted_on`, `cancelled_by`, `cancelled_on` are automatically set during session flush events.
+
+### Custom PostgreSQL Aggregates (`alembic_utils`)
+
+`PGAggregate` extends `alembic_utils` to manage custom PostgreSQL aggregate functions in Alembic migrations.
+
+```python
+from flask_postgresql_audit.extensions.alembic_utils import PGAggregate
+
+# Example: Define custom aggregate function entity
+sum_agg = PGAggregate(
+    schema="public",
+    signature="custom_sum(numeric)",
+    definition="(SFUNC = numeric_add, STYPE = numeric, INITCOND = '0')",
+)
+```
+
+Automatically detects and tracks custom `CREATE AGGREGATE` definitions during `alembic revision --autogenerate`.
+
+## Running the tests
+
+    git clone https://github.com/higamigu/flask-postgresql-audit.git
+    cd flask-postgresql-audit
+    pip install tox
+    createdb postgresql_audit_test
+    tox

{flask_postgresql_audit-1.0.9 → flask_postgresql_audit-1.1.1}/flask_postgresql_audit/__init__.py

@@ -1,4 +1,4 @@
 # ruff: noqa: F401
 from .core import Audit, PostgreSQLAudit
 
-__version__ = "1.0.9"
+__version__ = "1.1.1"

flask_postgresql_audit-1.1.1/flask_postgresql_audit/alembic/__init__.py

@@ -0,0 +1,7 @@
+# ruff: noqa: F401
+from .setup import (
+    chain_revision_directives,
+    register_triggers,
+    reorder_migration_ops,
+    setup_db,
+)

{flask_postgresql_audit-1.0.9 → flask_postgresql_audit-1.1.1}/flask_postgresql_audit/alembic/schema.py

@@ -32,16 +32,16 @@ class SchemaDrop(SchemaOperation):
 
 @Operations.implementation_for(SchemaCreate)
 def create_schema(operations: Operations, operation: SchemaCreate):
-    stmt = """
-        CREATE SCHEMA {name};
-        REVOKE ALL ON SCHEMA {name} FROM public;
-    """.format(name=operation.schema_name)
+    stmt = f"""
+        CREATE SCHEMA "{operation.schema_name}";
+        REVOKE ALL ON SCHEMA "{operation.schema_name}" FROM public;
+    """
     operations.execute(text(stmt))
 
 
 @Operations.implementation_for(SchemaDrop)
 def drop_schema(operations: Operations, operation: SchemaDrop):
-    stmt = "DROP SCHEMA {name} CASCADE;".format(name=operation.schema_name)
+    stmt = f'DROP SCHEMA "{operation.schema_name}" CASCADE;'
     operations.execute(text(stmt))