Exemples d'Embedding Catnip

Cette section contient des exemples complets d'intégration de Catnip comme moteur embedded dans des applications Python. Chaque exemple démontre un use case spécifique et des patterns réutilisables.

Vue d'ensemble

Catnip est conçu pour être embarqué dans des applications Python comme moteur de scripting sécurisé. Les exemples ci-dessous illustrent différents cas d'usage où Catnip permet aux utilisateurs ou administrateurs de définir des règles métier, des workflows, ou des transformations sans modifier le code de l'application.

Pattern commun

Tous les exemples suivent le même pattern :

from catnip import Catnip, Context, pass_context

# 1. Sous-classer Context pour état spécifique
class MyContext(Context):
    def __init__(self, data: dict, **kwargs):
        super().__init__(**kwargs)
        self._data = data
        self.globals['data'] = data

# 2. Sous-classer Catnip pour DSL
class MyDSL(Catnip):
    @staticmethod
    def _my_function(ctx, arg):
        # Logique métier
        return result

    DSL_FUNCTIONS = dict(
        my_function=pass_context(_my_function),
    )

    def __init__(self, data: dict, **kwargs):
        context = MyContext(data)
        super().__init__(context=context, **kwargs)
        self.context.globals.update(self.DSL_FUNCTIONS)

# 3. Utiliser le DSL
dsl = MyDSL(data)
result = dsl.execute(script)

Exemples disponibles

1. DataFrame DSL (01_dataframe_dsl.py)

Use case : Manipulation de DataFrames pandas avec syntaxe Catnip

Exemple original d'embedding montrant comment créer un DSL pour manipuler des DataFrames pandas. Les transformations sont définies en Catnip avec syntaxe chaînée.

Prérequis : pip install pandas

python docs/examples/embedding/01_dataframe_dsl.py

2. Configuration DSL (02_config_dsl.py)

Use case : Validation de fichiers de configuration avec règles déclaratives

Montre comment créer un DSL pour valider des configurations utilisateur avec des règles complexes (types, ranges, patterns, etc.). Idéal pour systèmes avec configuration utilisateur.

Fonctions DSL : required(), type_check(), range_check(), length_check(), one_of()

python docs/examples/embedding/02_config_dsl.py

3. ETL Pipeline (03_etl_pipeline.py)

Use case : Transformation de données (CSV → JSON/autre format)

Démontre comment utiliser Catnip pour créer des pipelines ETL déclaratifs. Les transformations (filtrage, mapping, agrégation) sont définies en Catnip et peuvent être stockées en base de données.

Fonctions DSL : filter_rows(), map_field(), rename_field(), add_field(), drop_field(), sort_by(), group_by()

python docs/examples/embedding/03_etl_pipeline.py

4. Rule Engine (04_rule_engine.py)

Use case : Moteur de règles métier (pricing, éligibilité, calculs)

Démontre un moteur de règles pour pricing dynamique, éligibilité crédit, calcul de frais. Les règles métier sont définies en Catnip et facilement modifiables sans recompiler.

Fonctions DSL : set_result(), mark_applied(), get_input(), calculate_percentage(), apply_discount(), clamp()

python docs/examples/embedding/04_rule_engine.py

5. Report Builder (05_report_builder.py)

Use case : Génération de rapports avec templates et données dynamiques

Montre comment utiliser Catnip pour générer des rapports personnalisés avec calcul de métriques et formatage. Les templates de rapport peuvent être définis par les administrateurs.

Fonctions DSL : calculate_sum(), calculate_avg(), calculate_count(), set_metric(), format_currency(), add_section()

python docs/examples/embedding/05_report_builder.py

6. Workflow DSL (06_workflow_dsl.py)

Use case : Orchestration de workflows (ETL, onboarding, traitement de commandes)

Illustre comment créer des workflows avec étapes séquentielles, gestion d'état, et historique. Les workflows peuvent être définis en Catnip et stockés en base de données.

Fonctions DSL : step(), set_state(), get_state(), log_event(), validate_state(), increment()

python docs/examples/embedding/06_workflow_dsl.py

7. Flask Sandbox (07_flask_sandbox.py)

Use case : Exécution sécurisée de scripts utilisateur dans Flask

Illustre comment créer un sandbox Catnip pour permettre aux utilisateurs d'écrire des workflows personnalisés dans une application web. Les scripts sont isolés et n'exposent que les APIs autorisées.

Fonctions DSL : send_email(), send_notification(), update_status(), check_permission(), add_tag(), has_tag()

python docs/examples/embedding/07_flask_sandbox.py

8. Jupyter Integration (08_jupyter_integration.py)

Use case : Magic commands IPython pour Jupyter notebooks

Montre comment créer des magic commands IPython (%catnip, %%catnip) pour utiliser Catnip dans des notebooks Jupyter. Permet l'analyse de données interactive avec partage d'état Python ↔ Catnip.

Magic commands : %catnip, %%catnip, %catnip_load, %catnip_reset, %catnip_vars

Installation dans Jupyter :

%load_ext jupyter_integration

Démo :

python docs/examples/embedding/08_jupyter_integration.py

9. Streamlit App (09_streamlit_app.py)

Use case : Dashboards interactifs et playground web

Démontre l'intégration de Catnip dans Streamlit pour créer un playground interactif et une calculatrice. Les utilisateurs peuvent écrire et exécuter du code Catnip dans le navigateur.

Lancement de l'application :

pip install streamlit
streamlit run docs/examples/embedding/09_streamlit_app.py

Démo :

python docs/examples/embedding/09_streamlit_app.py

Avantages de l'embedding

Sécurité

Les scripts Catnip s'exécutent dans un contexte isolé. Seules les fonctions explicitement exposées sont disponibles.

Flexibilité

Les règles métier et workflows peuvent être modifiés sans recompiler l'application. Stockez les scripts en base de données pour permettre aux administrateurs de les éditer.

Simplicité

La syntaxe Catnip est plus simple que Python pour des utilisateurs non-développeurs. Les scripts sont déclaratifs et focalisés sur la logique métier.

Performance

Les scripts sont compilés en bytecode avant exécution.

Ressources supplémentaires