flask-postgresql-audit 1.1.0__tar.gz → 1.1.2__tar.gz

{flask_postgresql_audit-1.1.0 → flask_postgresql_audit-1.1.2}/.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
@@ -66,3 +67,4 @@ uv.lock
 
 # Agents
 .agents
+AGENTS.md

{flask_postgresql_audit-1.1.0 → flask_postgresql_audit-1.1.2}/CHANGES.md

@@ -3,6 +3,69 @@
 Here you can see the full list of changes between each Flask-PostgreSQL-Audit
 release.
 
+## 1.1.2 (2026-08-21)
+
+-   Add dedicated `jsonb_array_subtract()` function to support set difference operations on JSONB arrays.
+-   Add unit tests for `DocumentStaging` and `PGAggregate` extensions.
+-   Add `reorder_migration_ops` troubleshooting guide to `README.md`.
+
+## 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.1.2/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.5
+Name: flask-postgresql-audit
+Version: 1.1.2
+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>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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.18.0
+Requires-Dist: flask-sqlalchemy>=3.1.1
+Requires-Dist: flask>=3.1.2
+Requires-Dist: psycopg2>=2.9.11
+Description-Content-Type: text/markdown
+
+# 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])`
+
+### Migration dependency or trigger ordering issues?
+
+If Alembic migration generation creates triggers before tables or schema dependencies:
+
+Use `reorder_migration_ops` and `chain_revision_directives` in `alembic/env.py`:
+
+```python
+from flask_postgresql_audit.alembic import (
+    chain_revision_directives,
+    reorder_migration_ops,
+)
+
+context.configure(
+    connection=connection,
+    target_metadata=target_metadata,
+    include_schemas=True,
+    process_revision_directives=chain_revision_directives(
+        reorder_migration_ops,
+        process_revision_directives,
+    ),
+)
+```
+
+## 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.1.2/README.md

@@ -0,0 +1,299 @@
+# 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])`
+
+### Migration dependency or trigger ordering issues?
+
+If Alembic migration generation creates triggers before tables or schema dependencies:
+
+Use `reorder_migration_ops` and `chain_revision_directives` in `alembic/env.py`:
+
+```python
+from flask_postgresql_audit.alembic import (
+    chain_revision_directives,
+    reorder_migration_ops,
+)
+
+context.configure(
+    connection=connection,
+    target_metadata=target_metadata,
+    include_schemas=True,
+    process_revision_directives=chain_revision_directives(
+        reorder_migration_ops,
+        process_revision_directives,
+    ),
+)
+```
+
+## 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.1.0 → flask_postgresql_audit-1.1.2}/flask_postgresql_audit/__init__.py

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