fastapi-audit-recorder 0.1.0__tar.gz

fastapi_audit_recorder-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.tool-versions
+__pycache__
+*egg-info/
+dist/
+node_modules/

fastapi_audit_recorder-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,58 @@
+stages:
+  - lint
+  - test
+  - build
+  - publish
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+default:
+  cache:
+    paths:
+      - .cache/pip
+
+ruff:
+  stage: lint
+  image: python:3.11
+  before_script:
+    - pip install -e .[dev]
+  script:
+    - ruff check .
+  allow_failure: true
+
+pytest:
+  stage: test
+  image: python:3.11
+  script:
+    - pip install -e .[dev]
+    - pytest
+
+build:
+  stage: build
+  image: python:3.11
+  before_script:
+    - pip install build
+  script:
+    - export SETUPTOOLS_SCM_PRETEND_VERSION=${CI_COMMIT_TAG#v}
+    - python -m build
+  artifacts:
+    paths:
+      - dist/
+  rules:
+    - if: '$CI_COMMIT_TAG'
+
+publish:
+  stage: publish
+  image: python:3.11
+  before_script:
+    - pip install twine
+  script:
+    - export TWINE_USERNAME="__token__"
+    - export TWINE_PASSWORD="$PYPI_TOKEN"
+    - twine upload dist/* --verbose
+  dependencies:
+    - build
+  rules:
+    - if: '$CI_COMMIT_TAG'
+      when: manual

fastapi_audit_recorder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fastapi-audit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_audit_recorder-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+recursive-include fastapi_audit_recorder/static *
+recursive-include fastapi_audit_recorder/static/components *
+recursive-include fastapi_audit_recorder/static/vendor *

fastapi_audit_recorder-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: fastapi-audit-recorder
+Version: 0.1.0
+Summary: Generic audit library for FastAPI applications
+Author: fastapi-audit-recorder contributors
+License: MIT License
+        
+        Copyright (c) 2026 fastapi-audit contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: fastapi,audit,sqlalchemy,logging,trail
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-anyio; extra == "dev"
+Requires-Dist: anyio[trio]; extra == "dev"
+Dynamic: license-file
+
+
+Cette librairie permet d'auditer les actions sur un projet et mets également à disposition une UI intégrée.
+
+# Structure complète du projet
+
+```text
+project-audit/
+├── fastapi_audit_recorder/
+│   ├── __init__.py
+│   ├── context.py
+│   ├── audit_decorator.py
+│   ├── transactional_decorator.py
+│   ├── service.py
+│   ├── models.py
+│   ├── resolver.py
+│   └── result.py
+├── tests/
+├── LICENSE
+├── README.md
+└── pyproject.toml
+```
+
+# Formatting with ruff
+
+ruff check . --fix
+ruff format .
+
+# Tests
+
+pytest
+
+# Builder la lib
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+Le répertoire dist contiendra un fichier .whl et un fichier .tar.gz.
+
+# Installer la distribution sur un projet (en local)
+
+```bash
+pip install /path/to/project-audit/dist/fastapi_audit_recorder-0.1.0-py3-none-any.whl
+pip show fastapi-audit-recorder
+```
+
+# Installer la distribution sur un projet (en mode dev)
+
+```bash
+pip install -e /home/you/dev/project-audit
+```
+
+# Executer les tests unitaires
+
+```bash
+pytest -v
+```
+
+## Intégration de la base de données (sqlalchemy et alembic)
+
+Importer et ajouter la metadata dans le fichier de configuration :
+
+```python
+from fastapi_audit_recorder import models as fastapi_audit_models
+
+target_metadata = [app.models.model.Base.metadata, fastapi_audit_models.Base.metadata]
+```
+
+Générer et executer le script de mise à jour, sous Alembic :
+
+```bash
+alembic revision --autogenerate -m "create_audit_logs_from_fastapi_audit_recorder"
+alembic upgrade head
+```
+
+## Intégration du service
+
+### Configuration
+
+Créer un fichier audit_setup.py.
+Celui-ci condiendra les requêtes qui seront executées avant et après chaque action, afin d'historiser les données et les changements.
+Les actions et les types de resources sont à la charge de chaque projet. TODO : héritage
+
+Créer autant de query et de register que vous avez de type de resource. Exemple :
+
+```python
+from fastapi_audit_recorder.resolver import resolver
+from sqlalchemy.orm import Session
+from app.models.model import Compte
+
+class AuditResourceEnum(enum.Enum):
+    COMPTE = "COMPTE"
+
+class AuditActionEnum(enum.Enum):
+    APPROVE = "APPROVE"
+    REFUSE = "REFUSE"
+
+def get_compte(session: Session, id: int) -> Compte | None:
+    return session.query(Compte).get(id)
+
+def audit_setup():
+    resolver.register(AuditResourceEnum.COMPTE.name, get_compte, Compte.id)
+```
+
+La méthode `register` accepte trois paramètres :
+- `resource_type` : le nom de la ressource
+- `loader` : la fonction de chargement de la ressource, signature `(session: Session, resource_id: Any) -> Any`
+- `identifier` : le champ SQLAlchemy utilisé comme identifiant de la ressource (ex. `Compte.id`, `Compte.uuid`)
+
+L'`identifier` sert à extraire automatiquement l'id depuis l'objet retourné par la fonction décorée lorsque `id_param` n'est pas renseigné, notamment dans le cas d'une création.
+
+Appeler la méthode audit_setup() dans le context manager :
+
+```python
+from app.audit_setup import audit_setup
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    ...
+    audit_setup()
+    yield
+```
+
+### Décorateur @audit
+
+La lib mets à disposition un décorateur afin d'auditer une action.
+Exemple d'utilisation :
+
+```python
+from fastapi_audit_recorder.decorators.audit_decorator import audit
+
+@audit(action="UPDATE", resource_type="COMPTE", id_param="compteDTO.id")
+async def update_compte(compteDTO: CompteDTO, id_token: KeycloakIDToken, session: Session) -> CompteDTO:
+```
+
+Si `id_param` n'est pas renseigné, l'identifiant sera extrait automatiquement depuis l'objet retourné par la fonction,
+en utilisant l'`identifier` enregistré dans le resolver (via `resolver.register`). Exemple :
+
+```python
+@audit(action="CREATE", resource_type="COMPTE")  # pas d'id_param
+async def create_compte(compteDTO: CompteDTO, id_token: KeycloakIDToken, session: Session) -> Compte:
+    ...
+    return db_compte  # db_compte.id sera extrait via Compte.id déclaré dans le resolver
+```
+
+Important:
+    - **Tous les paramètres du décorateur `@audit` doivent être passés en nommés** (`action=`, `resource_type=`, `id_param=`)
+    - **Tous les arguments de la fonction décorée doivent également être passés en nommés** lors de l'appel
+    - `id_token: KeycloakIDToken` est obligatoire afin de pouvoir récupérer les informations sur l'utilisateur
+    - `session: Session` est obligatoire afin que les logs d'audit soient ajoutées dans la même session
+
+### Gestion de la transaction - décorateur @transactional
+
+Le décorateur @audit ne réalise aucun commit, c'est action à la charge de la méthode appelante.
+Un décorateur @transactional est mis à disposition afin d'automatiser les commits, exemple :
+
+```python
+from fastapi_audit_recorder.decorators.audit_decorator import audit
+from fastapi_audit_recorder.decorators.transactional_decorator import transactional
+
+@transactional
+@audit(action=AuditActionEnum.CREATE.name, resource_type=AuditResourceEnum.COMPTE.name, id_param="db_compte.id")
+def approve_demande_creation(...)
+```
+
+A noter: l'ordre est important, le l'annotation @transactional doit précéder l'annotation @audit pour la persitance des données.
+
+### Contexte
+
+Dans certain cas, on souhaite auditer une action en fonction de l'appelant.
+Par exemple, auditer une approbation manuelle mais ne pas auditer une autoapprobation.
+
+Pour cela il est possible de définir un contexte afin de désactiver un ou plusieurs audits, exemple :
+
+```python
+from fastapi_audit_recorder.context import skip_audit
+
+with skip_audit(AuditActionEnum.APPROVE, AuditActionEnum.REJECT)
+with skip_audit():
+    service.approve(...)
+```
+
+### Ignorer l'audit
+
+L'audit est automatiquement réalisée après l'execution de la méthode annotée, sauf si celle-ci lance une exception.
+Il est possible d'ignorer explicitement l'audit. Exemple :
+
+```python
+from fastapi_audit_recorder.result import AuditResult
+
+def approve(...) {
+    if is_already_approve:
+        return AuditResult.skip(db_compte)
+}
+
+```
+
+## Services
+
+La lib mets à disposition des services afin de récupérer des données filtrées et paginées :
+
+```python
+from fastapi_audit_recorder import service
+
+service.query_logs(...)
+service.query_log_by_id(...)
+```

fastapi_audit_recorder-0.1.0/README.md

@@ -0,0 +1,208 @@
+
+Cette librairie permet d'auditer les actions sur un projet et mets également à disposition une UI intégrée.
+
+# Structure complète du projet
+
+```text
+project-audit/
+├── fastapi_audit_recorder/
+│   ├── __init__.py
+│   ├── context.py
+│   ├── audit_decorator.py
+│   ├── transactional_decorator.py
+│   ├── service.py
+│   ├── models.py
+│   ├── resolver.py
+│   └── result.py
+├── tests/
+├── LICENSE
+├── README.md
+└── pyproject.toml
+```
+
+# Formatting with ruff
+
+ruff check . --fix
+ruff format .
+
+# Tests
+
+pytest
+
+# Builder la lib
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+Le répertoire dist contiendra un fichier .whl et un fichier .tar.gz.
+
+# Installer la distribution sur un projet (en local)
+
+```bash
+pip install /path/to/project-audit/dist/fastapi_audit_recorder-0.1.0-py3-none-any.whl
+pip show fastapi-audit-recorder
+```
+
+# Installer la distribution sur un projet (en mode dev)
+
+```bash
+pip install -e /home/you/dev/project-audit
+```
+
+# Executer les tests unitaires
+
+```bash
+pytest -v
+```
+
+## Intégration de la base de données (sqlalchemy et alembic)
+
+Importer et ajouter la metadata dans le fichier de configuration :
+
+```python
+from fastapi_audit_recorder import models as fastapi_audit_models
+
+target_metadata = [app.models.model.Base.metadata, fastapi_audit_models.Base.metadata]
+```
+
+Générer et executer le script de mise à jour, sous Alembic :
+
+```bash
+alembic revision --autogenerate -m "create_audit_logs_from_fastapi_audit_recorder"
+alembic upgrade head
+```
+
+## Intégration du service
+
+### Configuration
+
+Créer un fichier audit_setup.py.
+Celui-ci condiendra les requêtes qui seront executées avant et après chaque action, afin d'historiser les données et les changements.
+Les actions et les types de resources sont à la charge de chaque projet. TODO : héritage
+
+Créer autant de query et de register que vous avez de type de resource. Exemple :
+
+```python
+from fastapi_audit_recorder.resolver import resolver
+from sqlalchemy.orm import Session
+from app.models.model import Compte
+
+class AuditResourceEnum(enum.Enum):
+    COMPTE = "COMPTE"
+
+class AuditActionEnum(enum.Enum):
+    APPROVE = "APPROVE"
+    REFUSE = "REFUSE"
+
+def get_compte(session: Session, id: int) -> Compte | None:
+    return session.query(Compte).get(id)
+
+def audit_setup():
+    resolver.register(AuditResourceEnum.COMPTE.name, get_compte, Compte.id)
+```
+
+La méthode `register` accepte trois paramètres :
+- `resource_type` : le nom de la ressource
+- `loader` : la fonction de chargement de la ressource, signature `(session: Session, resource_id: Any) -> Any`
+- `identifier` : le champ SQLAlchemy utilisé comme identifiant de la ressource (ex. `Compte.id`, `Compte.uuid`)
+
+L'`identifier` sert à extraire automatiquement l'id depuis l'objet retourné par la fonction décorée lorsque `id_param` n'est pas renseigné, notamment dans le cas d'une création.
+
+Appeler la méthode audit_setup() dans le context manager :
+
+```python
+from app.audit_setup import audit_setup
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    ...
+    audit_setup()
+    yield
+```
+
+### Décorateur @audit
+
+La lib mets à disposition un décorateur afin d'auditer une action.
+Exemple d'utilisation :
+
+```python
+from fastapi_audit_recorder.decorators.audit_decorator import audit
+
+@audit(action="UPDATE", resource_type="COMPTE", id_param="compteDTO.id")
+async def update_compte(compteDTO: CompteDTO, id_token: KeycloakIDToken, session: Session) -> CompteDTO:
+```
+
+Si `id_param` n'est pas renseigné, l'identifiant sera extrait automatiquement depuis l'objet retourné par la fonction,
+en utilisant l'`identifier` enregistré dans le resolver (via `resolver.register`). Exemple :
+
+```python
+@audit(action="CREATE", resource_type="COMPTE")  # pas d'id_param
+async def create_compte(compteDTO: CompteDTO, id_token: KeycloakIDToken, session: Session) -> Compte:
+    ...
+    return db_compte  # db_compte.id sera extrait via Compte.id déclaré dans le resolver
+```
+
+Important:
+    - **Tous les paramètres du décorateur `@audit` doivent être passés en nommés** (`action=`, `resource_type=`, `id_param=`)
+    - **Tous les arguments de la fonction décorée doivent également être passés en nommés** lors de l'appel
+    - `id_token: KeycloakIDToken` est obligatoire afin de pouvoir récupérer les informations sur l'utilisateur
+    - `session: Session` est obligatoire afin que les logs d'audit soient ajoutées dans la même session
+
+### Gestion de la transaction - décorateur @transactional
+
+Le décorateur @audit ne réalise aucun commit, c'est action à la charge de la méthode appelante.
+Un décorateur @transactional est mis à disposition afin d'automatiser les commits, exemple :
+
+```python
+from fastapi_audit_recorder.decorators.audit_decorator import audit
+from fastapi_audit_recorder.decorators.transactional_decorator import transactional
+
+@transactional
+@audit(action=AuditActionEnum.CREATE.name, resource_type=AuditResourceEnum.COMPTE.name, id_param="db_compte.id")
+def approve_demande_creation(...)
+```
+
+A noter: l'ordre est important, le l'annotation @transactional doit précéder l'annotation @audit pour la persitance des données.
+
+### Contexte
+
+Dans certain cas, on souhaite auditer une action en fonction de l'appelant.
+Par exemple, auditer une approbation manuelle mais ne pas auditer une autoapprobation.
+
+Pour cela il est possible de définir un contexte afin de désactiver un ou plusieurs audits, exemple :
+
+```python
+from fastapi_audit_recorder.context import skip_audit
+
+with skip_audit(AuditActionEnum.APPROVE, AuditActionEnum.REJECT)
+with skip_audit():
+    service.approve(...)
+```
+
+### Ignorer l'audit
+
+L'audit est automatiquement réalisée après l'execution de la méthode annotée, sauf si celle-ci lance une exception.
+Il est possible d'ignorer explicitement l'audit. Exemple :
+
+```python
+from fastapi_audit_recorder.result import AuditResult
+
+def approve(...) {
+    if is_already_approve:
+        return AuditResult.skip(db_compte)
+}
+
+```
+
+## Services
+
+La lib mets à disposition des services afin de récupérer des données filtrées et paginées :
+
+```python
+from fastapi_audit_recorder import service
+
+service.query_logs(...)
+service.query_log_by_id(...)
+```

fastapi_audit_recorder-0.1.0/dev_server.py

@@ -0,0 +1,123 @@
+"""
+Serveur de développement local avec données de test.
+Accessible depuis : http://localhost:8000/audit/
+"""
+
+from datetime import datetime, timezone
+
+from fastapi import FastAPI, Request
+from fastapi_audit.models import AuditLog, Base
+from fastapi_audit.routers.display_router import get_display_router
+from fastapi_audit.search_router import get_search_router
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+# --- DB SQLite en mémoire ---
+engine = create_engine('sqlite:///:memory:', connect_args={'check_same_thread': False})
+SessionLocal = sessionmaker(bind=engine)
+
+Base.metadata.create_all(bind=engine)
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+# --- Données de test ---
+def seed(db):
+    entries = [
+        AuditLog(
+            id='1',
+            action='CREATE',
+            resource_type='User',
+            resource_id='101',
+            user_id='42',
+            user_email='alice@example.com',
+            old_values=None,
+            new_values={'name': 'Alice', 'email': 'alice@example.com'},
+            changes={'name': {'old': None, 'new': 'Alice'}},
+            created_at=datetime(2026, 3, 1, 9, 0, 0, tzinfo=timezone.utc),
+        ),
+        AuditLog(
+            id='2',
+            action='UPDATE',
+            resource_type='User',
+            resource_id='101',
+            user_id='42',
+            user_email='alice@example.com',
+            old_values={'name': 'Alice'},
+            new_values={'name': 'Alice Dupont'},
+            changes={'name': {'old': 'Alice', 'new': 'Alice Dupont'}},
+            created_at=datetime(2026, 3, 10, 14, 30, 0, tzinfo=timezone.utc),
+        ),
+        AuditLog(
+            id='3',
+            action='DELETE',
+            resource_type='Order',
+            resource_id='55',
+            user_id='7',
+            user_email='bob@example.com',
+            old_values={'status': 'pending', 'amount': 99.9},
+            new_values=None,
+            changes={'status': {'old': 'pending', 'new': None}},
+            created_at=datetime(2026, 3, 15, 8, 0, 0, tzinfo=timezone.utc),
+        ),
+        AuditLog(
+            id='4',
+            action='CREATE',
+            resource_type='Order',
+            resource_id='56',
+            user_id='7',
+            user_email='bob@example.com',
+            old_values=None,
+            new_values={'status': 'confirmed', 'amount': 149.0},
+            changes={'status': {'old': None, 'new': 'confirmed'}},
+            created_at=datetime(2026, 3, 18, 11, 0, 0, tzinfo=timezone.utc),
+        ),
+        AuditLog(
+            id='5',
+            action='APPROVE',
+            resource_type='Invoice',
+            resource_id='9',
+            user_id='42',
+            user_email='alice@example.com',
+            old_values={'approved': False},
+            new_values={'approved': True},
+            changes={'approved': {'old': False, 'new': True}},
+            created_at=datetime(2026, 3, 19, 10, 0, 0, tzinfo=timezone.utc),
+        ),
+    ]
+    db.add_all(entries)
+    db.commit()
+
+
+with SessionLocal() as db:
+    seed(db)
+
+# --- App ---
+app = FastAPI(title='Audit Dev Server')
+
+
+@app.middleware('http')
+async def inject_dev_cookie(request: Request, call_next):
+    """Injecte un cookie kc_token factice sur toutes les requêtes en dev."""
+    headers = dict(request.scope['headers'])
+    cookie_header = headers.get(b'cookie', b'')
+    if b'kc_token' not in cookie_header:
+        sep = b'; ' if cookie_header else b''
+        headers[b'cookie'] = cookie_header + sep + b'kc_token=dev-token'
+        request.scope['headers'] = list(headers.items())
+    return await call_next(request)
+
+
+app.include_router(get_search_router(get_db), prefix='/audit')
+app.include_router(get_display_router(), prefix='/audit')
+
+if __name__ == '__main__':
+    import uvicorn
+
+    uvicorn.run('dev_server:app', host='0.0.0.0', port=8000, reload=True)

fastapi_audit_recorder-0.1.0/fastapi_audit_recorder/__init__.py

@@ -0,0 +1,17 @@
+from .audit_decorator import audit
+from .context import skip_audit
+from .models import AuditLog, AuditLogDTO, PaginatedAuditLogs
+from .resolver import ResourceResolver
+from .result import AuditResult
+from .transactional_decorator import transactional
+
+__all__ = [
+    'AuditLog',
+    'AuditLogDTO',
+    'AuditResult',
+    'PaginatedAuditLogs',
+    'ResourceResolver',
+    'audit',
+    'transactional',
+    'skip_audit',
+]