Skip to content

Commit 781551c

Browse files
venantvrvenantvr
committed
First commit...
1 parent b620209 commit 781551c

File tree

10 files changed

+308
-103
lines changed

10 files changed

+308
-103
lines changed

‎.env.example‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
# ----------------------------------------------------------------------------
2-
# BUSINESS EVENT LOGGER CONFIGURATION
2+
# SQLITE BUSINESS EVENT LOGGER CONFIGURATION
33
# ----------------------------------------------------------------------------
4-
# Enable the dedicated business event logger
54
BUSINESS_LOGGER_ENABLED=false
65
# Path to the SQLite database file for business events
76
BUSINESS_LOGGER_DB_FILE=./logs/business_events.db
87
# Table name for business events
98
BUSINESS_LOGGER_TABLE_NAME=business_events
9+
10+
# ----------------------------------------------------------------------------
11+
# JSON BUSINESS EVENT LOGGER CONFIGURATION
12+
# ----------------------------------------------------------------------------
13+
JSON_BUSINESS_LOGGER_ENABLED=false
14+
# Path to the JSON database file for business events
15+
JSON_BUSINESS_LOGGER_DB_FILE=./logs/business_events.json

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
11
.venv
2-
.idea
2+
.idea
3+
4+
# Fichiers de log générés
5+
*.db
6+
*.json
7+
logs/

‎Makefile‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Makefile
2+
3+
# =============================================================================
4+
# VARIABLES
5+
# =============================================================================
6+
7+
# Utilise python3 par défaut. Peut être surchargé : make PYTHON=python3.9 install
8+
PYTHON ?= python3
9+
VENV_DIR ?= .venv
10+
VENV_BIN = $(VENV_DIR)/bin
11+
PIP = $(VENV_BIN)/pip
12+
13+
# =============================================================================
14+
# CONFIGURATION
15+
# =============================================================================
16+
17+
# Cible par défaut, exécutée quand on tape juste "make"
18+
.DEFAULT_GOAL := help
19+
20+
# Déclare les cibles qui ne sont pas des fichiers
21+
.PHONY: help install-dev install run clean clean-venv lint format
22+
23+
# =============================================================================
24+
# CIBLES PRINCIPALES
25+
# =============================================================================
26+
27+
help: ## ✨ Affiche ce message d'aide
28+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
29+
awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
30+
31+
install: venv ## 📦 Installe la librairie en mode éditable
32+
@echo "--- Installation des dépendances du projet ---"
33+
@$(PIP) install -e .
34+
35+
install-dev: venv ## 🛠️ Installe les outils de développement (lint, formatage...)
36+
@echo "--- Installation des dépendances de développement ---"
37+
# Note : nécessite une section [project.optional-dependencies] dans pyproject.toml
38+
@$(PIP) install -e ".[dev]"
39+
40+
run: install ## ▶️ Lance le script d'exemple
41+
@echo "--- Lancement du script d'exemple (examples/main.py) ---"
42+
@$(VENV_BIN)/python examples/main.py
43+
44+
# =============================================================================
45+
# CIBLES DE QUALITÉ & NETTOYAGE
46+
# =============================================================================
47+
48+
lint: install-dev ## 🔬 Analyse le code avec un linter (ex: ruff)
49+
@echo "--- Analyse du code avec le linter ---"
50+
@$(VENV_BIN)/ruff check src examples
51+
52+
format: install-dev ## 💅 Formate le code automatiquement (ex: black, ruff)
53+
@echo "--- Formatage du code ---"
54+
@$(VENV_BIN)/ruff format src examples
55+
56+
clean: clean-venv ## 🧹 Nettoie tous les fichiers générés (cache, etc.)
57+
@echo "--- Nettoyage des fichiers cache Python ---"
58+
@find . -type f -name "*.py[co]" -delete
59+
@find . -type d -name "__pycache__" -delete
60+
@find . -type d -name ".pytest_cache" -delete
61+
@find . -type d -name ".ruff_cache" -delete
62+
63+
clean-venv: ## 🗑️ Supprime l'environnement virtuel (.venv)
64+
@echo "--- Suppression de l'environnement virtuel ---"
65+
@rm -rf $(VENV_DIR)
66+
67+
# =============================================================================
68+
# CIBLES UTILITAIRES (non affichées dans l'aide)
69+
# =============================================================================
70+
71+
venv: pyproject.toml
72+
@if [ ! -d "$(VENV_DIR)" ]; then \
73+
echo "--- Création de l'environnement virtuel ---"; \
74+
$(PYTHON) -m venv $(VENV_DIR); \
75+
echo "--- Mise à jour de pip ---"; \
76+
$(PIP) install --upgrade pip; \
77+
fi

‎README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# PubSub Business Loggers
2+
3+
![Licence](https://img.shields.io/badge/licence-MIT-blue.svg)
4+
![Python Version](https://img.shields.io/badge/python-3.8%2B-brightgreen.svg)
5+
![Status](https://img.shields.io/badge/status-stable-green.svg)
6+
7+
Une librairie Python simple et robuste pour enregistrer des événements métier de manière asynchrone dans des bases de données locales (SQLite ou JSON). Conçue pour être
8+
non-bloquante, thread-safe et facile à intégrer.
9+
10+
## ✨ Fonctionnalités Principales
11+
12+
* **Deux Backends de Stockage :** Choisissez entre **SQLite** pour des logs structurés ou **JSON** (via TinyDB) pour une flexibilité maximale.
13+
* **Non-bloquant & Thread-Safe :** L'écriture des logs est gérée par un thread dédié en arrière-plan, garantissant que votre application principale n'est jamais ralentie.
14+
* **Auto-configurable :** Activez et configurez les loggers simplement via des variables d'environnement dans un fichier `.env`.
15+
* **Gestion de Cycle de Vie Automatique :** Grâce à la prise en charge du gestionnaire de contexte (`with`), l'arrêt propre des loggers est garanti, sans perte de
16+
données.
17+
* **API Simple et Intuitive :** Une seule méthode `.log()` à apprendre.
18+
* **Feedback Visuel :** Les logs sont affichés en temps réel et en couleur dans la console pour un débogage facile.
19+
20+
## ⚙️ Installation et Configuration
21+
22+
L'installation est simplifiée grâce au `Makefile` fourni.
23+
24+
1. **Clonez le dépôt :**
25+
```sh
26+
git clone <votre-url-de-depot>
27+
cd <nom-du-dossier>
28+
```
29+
30+
2. **Configurez votre environnement :**
31+
Copiez le fichier d'exemple et modifiez-le pour activer les loggers de votre choix.
32+
```sh
33+
cp .env.example .env
34+
```
35+
Modifiez le fichier `.env` :
36+
```ini
37+
# .env
38+
39+
# Activer le logger SQLite
40+
BUSINESS_LOGGER_ENABLED=true
41+
BUSINESS_LOGGER_DB_FILE=./logs/business_events.db
42+
43+
# Activer le logger JSON
44+
JSON_BUSINESS_LOGGER_ENABLED=true
45+
JSON_BUSINESS_LOGGER_DB_FILE=./logs/business_events.json
46+
```
47+
48+
3. **Installez l'environnement :**
49+
Cette commande va créer un environnement virtuel (`.venv`) et installer toutes les dépendances nécessaires en mode éditable.
50+
```sh
51+
make install
52+
```
53+
54+
## 🚀 Démarrage Rapide
55+
56+
L'utilisation des loggers est conçue pour être la plus simple possible grâce au gestionnaire de contexte `with`, qui s'occupe automatiquement du `shutdown()`.
57+
58+
```python
59+
# examples/main.py
60+
import time
61+
from dotenv import load_dotenv
62+
63+
# Charger la configuration depuis .env
64+
load_dotenv()
65+
66+
# Importer les loggers depuis la librairie
67+
from pubsub import sqlite_business_logger, json_business_logger
68+
69+
70+
def run_my_application():
71+
"""Simule l'exécution de l'application principale."""
72+
print("Application en cours d'exécution...")
73+
for i in range(5):
74+
# Enregistrer un événement dans la base de données SQLite
75+
sqlite_business_logger.log(
76+
"ORDER_PROCESSED",
77+
{"order_id": f"ORD-00{i}", "amount": 100 + i}
78+
)
79+
# Enregistrer un événement dans le fichier JSON
80+
json_business_logger.log(
81+
"USER_ACTIVITY",
82+
{"user_id": "user123", "action": "view_page", "page": f"/product/{i}"}
83+
)
84+
time.sleep(1)
85+
print("Les opérations sont terminées.")
86+
87+
88+
if __name__ == "__main__":
89+
# Le bloc 'with' garantit que les deux loggers seront arrêtés proprement
90+
# à la fin, même en cas d'erreur.
91+
with sqlite_business_logger, json_business_logger:
92+
run_my_application()
93+
94+
print("Application terminée avec succès.")
95+
```
96+
97+
## 🧰 Commandes utiles (Makefile)
98+
99+
Utilisez `make` pour automatiser les tâches courantes.
100+
101+
* `make` ou `make help` : Affiche toutes les commandes disponibles.
102+
* `make install` : Installe l'environnement de développement et les dépendances.
103+
* `make run` : Lance le script d'exemple `examples/main.py`.
104+
* `make lint` : Analyse la qualité du code avec `ruff`.
105+
* `make format` : Formate le code automatiquement.
106+
* `make clean` : Supprime l'environnement virtuel et tous les fichiers temporaires.
107+
108+
## 📚 Composants
109+
110+
### `sqlite_business_logger`
111+
112+
* **Backend :** SQLite
113+
* **Cas d'usage :** Idéal pour des événements structurés, l'audit, et lorsque vous avez besoin de requêter les logs avec la puissance du SQL.
114+
115+
### `json_business_logger`
116+
117+
* **Backend :** Fichier JSON (via TinyDB)
118+
* **Cas d'usage :** Parfait pour des données avec une structure variable, le prototypage rapide, et des logs facilement lisibles par un humain.
119+
120+
## 📜 Licence
121+
122+
Ce projet est sous licence MIT.

‎examples/main.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import time
2+
3+
from dotenv import load_dotenv
4+
5+
# Charger la configuration depuis le fichier .env à la racine
6+
load_dotenv()
7+
8+
# Importer les loggers depuis la librairie
9+
# Note : Pour que cela fonctionne, vous devez installer votre projet
10+
# en mode "éditable" (voir l'étape 3).
11+
from pubsub import sqlite_business_logger, json_business_logger
12+
13+
14+
def run_app():
15+
"""Une fonction qui simule l'activité de votre application."""
16+
print("Début de l'application...")
17+
for i in range(3):
18+
print(f"Opération #{i + 1}")
19+
sqlite_business_logger.log("SQL_EVENT", {"iteration": i, "status": "processing"})
20+
time.sleep(0.5)
21+
json_business_logger.log("JSON_EVENT", {"iteration": i, "details": "some data"})
22+
time.sleep(1)
23+
print("Fin des opérations.")
24+
25+
26+
if __name__ == "__main__":
27+
print("Lancement de l'exemple avec gestion automatique des loggers...")
28+
29+
# Le bloc 'with' garantit que shutdown() sera appelé pour les deux loggers
30+
# à la fin, même si une erreur se produit à l'intérieur.
31+
with sqlite_business_logger, json_business_logger:
32+
run_app()
33+
34+
print("\nApplication terminée. Les loggers ont été arrêtés proprement.")

‎pyproject.toml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[build-system]
2+
requires = ["setuptools>=61.0"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "pubsub_business_loggers"
7+
version = "0.2.0"
8+
description = "Une librairie fournissant des loggers métier thread-safe avec backend SQLite ou JSON."
9+
requires-python = ">=3.8"
10+
dependencies = [
11+
"tinydb>=4.7.0",
12+
"python-dotenv>=1.0.0",
13+
]

‎requirements.txt‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎src/pubsub/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,5 @@
1212

1313
__all__ = [
1414
"sqlite_business_logger",
15-
"json_business_logger" # <-- NOUVEL EXPORT
15+
"json_business_logger"
1616
]

0 commit comments

Comments
 (0)