Configuration

Catnip utilise une configuration hiérarchique avec des overrides par mode d'exécution.

Fichier de Configuration

Emplacement : ~/.config/catnip/catnip.toml

Voir catnip.toml.example à la racine du projet pour un fichier complet commenté.

Structure de Base

# Config globale
enable_cache = true

[optimize]
executor = "vm"
jit = false
tco = true
optimize = 3

[repl]
no_color = false
theme = "auto"      # auto, dark, light

[format]
indent_size = 4
line_length = 120

[cache]
cache_max_size_mb = 100     # Limite 100 Mo ("unlimited" pour illimité)
cache_ttl_seconds = 86400   # TTL 24 heures ("unlimited" pour pas d'expiration)

[modules]
auto = []                    # Modules chargés automatiquement au démarrage

[lint]
disable = []                 # Codes de diagnostic désactivés globalement

Configuration Par Mode

Catnip charge des overrides selon le mode d'exécution détecté.

Fonctionnement

Les sections [mode.X] dans catnip.toml surchargent les valeurs globales selon le contexte d'exécution :

standalone : Scripts .cat exécutés via CLI (fichier fourni en argument)
repl : Session interactive (pas de fichier, stdin est un TTY)
dsl : Catnip utilisé comme DSL (importé comme bibliothèque Python)

Ordre de priorité :

DEFAULT < FILE (global) < FILE ([mode.X]) < ENV < CLI

Les overrides par mode s'appliquent après la config globale du fichier mais avant les variables d'environnement.

Modes d'Exécution

Catnip détecte automatiquement 3 modes d'exécution et applique des overrides spécifiques :

Mode `standalone` (Scripts)

Déclenchement : catnip script.cat

Objectif : Startup rapide, scripts batch, automation

Config recommandée :

[mode.standalone]
jit = false      # Pas de JIT : startup instant (le startup vient d'ici, pas du niveau optimize)
optimize = 3     # Passes on (défaut) : compile cheap, gain runtime ; passe à 0 pour les scripts jetables
tco = true       # TCO utile pour récursion

Cas d'usage :

Scripts système (config validation, data transform)
Cron jobs, automation
CLI tools en Catnip

Mode `repl` (Interactif)

Déclenchement : catnip (sans arguments, stdin = tty)

Objectif : Performance interactive, exploration

Config recommandée :

[mode.repl]
jit = true       # JIT pour perf runtime
optimize = 3     # Passes on (défaut ; 1/2/3 équivalents aujourd'hui)
tco = true       # TCO pour expérimentation

Cas d'usage :

Exploration interactive
Debugging
Calculs quick

Mode DSL

Déclenchement : from catnip import Catnip (usage library)

Objectif : Prévisibilité, debugging facile, intégration simple

Config recommandée :

[mode.dsl]
jit = false      # Pas de JIT : intégration simple
tco = false      # Pas de TCO : call stacks clairs
optimize = 0     # Comportement prédictible

Cas d'usage :

DSL dans applications Python
Pandas/data wrangling DSL
Config DSL, rule engines

Note : le mode DSL n'est pas encore auto-détecté. Pour l'instant, utilisez les sections [optimize] et [repl] classiques.

Précédence des Configurations

Ordre de priorité (du plus faible au plus fort) :

Defaults (hardcodés)
Fichier config (~/.config/catnip/catnip.toml)
Mode overrides ([mode.standalone], [mode.repl], [mode.dsl])
Variables d'environnement (CATNIP_EXECUTOR, CATNIP_OPTIMIZE, CATNIP_THEME, NO_COLOR)
Arguments CLI (-x, -o, --theme, --no-color)

Exemple de Précédence

# catnip.toml
[optimize]
jit = false
optimize = 3     # passes on

[mode.standalone]
optimize = 0     # passes off pour les scripts

# Base
$ catnip -c "42"              # jit=false, optimize=3 (passes on)

# Mode override
$ catnip script.cat           # jit=false, optimize=0 (mode.standalone, passes off)

# Env var override
$ CATNIP_OPTIMIZE=jit catnip script.cat
                              # jit=true, optimize=0 (env active le JIT, niveau inchangé)

# CLI override (highest)
$ catnip -o level:3 script.cat
                              # optimize=3 (cli > all, passes on)

Note sur optimize : le niveau accepte 0-3 mais l'effet est un seuil — 0 désactive les passes, ≥1 les active toutes (les niveaux 1/2/3 sont équivalents aujourd'hui). Voir dev/OPTIMIZATIONS pour le détail.

Modules

La section [modules] configure le chargement automatique de modules et les policies d'accès.

[modules]
auto = ["io", "math"]            # Modules chargés au démarrage
policy = "allow"                 # Fallback : allow ou deny
allow = ["math", "json"]         # Patterns autorisés
deny = ["os", "subprocess"]      # Patterns bloqués

auto charge les modules listés comme namespaces globaux avant l'exécution, équivalent à -m pour chaque module. Chaque mode (REPL, CLI, DSL) peut définir sa propre liste via [modules.repl], [modules.cli], [modules.dsl] avec fallback sur [modules].auto. Les modules passés via -m sont additifs (dédupliqués).

Un module introuvable ou bloqué par la policy est ignoré avec un message d'erreur.

Voir MODULE_LOADING pour la policy et l'auto-import en détail.

Options de Cache

Le cache de compilation stocke les résultats de parsing/compilation pour accélérer les exécutions répétées.

Emplacement : ~/.cache/catnip/ (XDG_CACHE_HOME)

Configuration :

[cache]
cache_max_size_mb = 50      # Taille maximale en Mo
cache_ttl_seconds = 7200    # Durée de vie des entrées (secondes)

Valeurs spéciales :

"unlimited" : pas de limite de taille ou de TTL
Défauts : 100 Mo, 24 heures

Gestion via CLI :

catnip cache stats         # Statistiques (taille, hits/misses)
catnip cache prune         # Nettoyer entrées expirées
catnip cache clear         # Vider complètement le cache

Voir CLI pour plus de détails.

Diagnostics

Les erreurs internes (WeirdErrors) sont automatiquement loggées sur disque sous forme de rapports JSON. Ces rapports servent au diagnostic post-mortem : un utilisateur peut les partager pour signaler un bug.

Emplacement : ~/.local/state/catnip/weird/ (XDG_STATE_HOME)

Configuration :

[diagnostics]
log_weird_errors = true     # Actif par défaut
max_weird_logs = 50         # Rotation automatique

Env var : CATNIP_WEIRD_LOG=off désactive le logging (priorité sur le TOML).

Le logging est silencieux : une erreur I/O lors de l'écriture du rapport ne masque jamais l'erreur originale. Fonctionne dans les deux contextes : Python (via PyO3) et standalone Rust.

Linter

La section [lint] désactive globalement des codes de diagnostic, là où # noqa n'agit que sur une ligne.

[lint]
disable = ["W401", "I200"]   # Codes tus pour toute l'analyse

Les flags CLI surchargent le fichier : --disable CODE ajoute des codes, --enable CODE en réactive un (annule un disable du fichier ou de la même commande). L'ensemble effectif des codes tus est (fichier ∪ --disable) \ --enable. --enable n'allume pas une phase opt-in : --check-names et --deep restent les leviers des règles désactivées par défaut.

Voir tools/lint pour la liste des codes.

Variables d'Environnement

CATNIP_EXECUTOR : vm (défaut)
CATNIP_OPTIMIZE : syntaxe identique à -o (ex: jit,tco:off,level:2)
CATNIP_THEME : auto (défaut), dark, light
NO_COLOR : 1 pour désactiver les couleurs (standard freedesktop.org)
CATNIP_FORMAT_INDENT_SIZE : taille indentation (défaut: 4)
CATNIP_FORMAT_LINE_LENGTH : longueur ligne max (défaut: 120)
CATNIP_WEIRD_LOG : on/off pour activer/désactiver le logging des erreurs internes

Inspecter la Configuration

# Voir config actuelle
$ catnip config show

# Avec sources (defaults, file, env, cli)
$ catnip config show --debug

En REPL, /config (sans argument) ouvre un éditeur interactif avec navigation clavier, toggle/cycle/édition inline et sauvegarde immédiate. Voir REPL pour les détails.

$ catnip config show
# /home/ari/.config/catnip/catnip.toml
cache_max_size_mb = 100
cache_ttl_seconds = 86400
enable_cache = true
executor = vm
jit = false
log_weird_errors = true
max_weird_logs = 50
memory_limit = 2048
no_color = false
optimize = 3
tco = true
theme = auto

$ catnip config show --debug
Configuration from: /home/ari/.config/catnip/catnip.toml

  cache_max_size_mb: 100  [default]
  cache_ttl_seconds: 86400  [default]
  enable_cache: True  [default]
  executor: 'vm'  [default]
  jit: False  [default]
  log_weird_errors: True  [default]
  max_weird_logs: 50  [default]
  memory_limit: 2048  [default]
  no_color: False  [default]
  optimize: 3  [default]
  tco: True  [default]
  theme: 'auto'  [default]
  --- format config ---
  format.align: True  [default]
  format.indent_size: 4  [default]
  format.line_length: 120  [default]

Exemples Pratiques

Dev : debugging avec optimisations désactivées

export CATNIP_OPTIMIZE=tco:off,level:0
catnip myscript.cat

Prod : max performance

export CATNIP_OPTIMIZE=jit,level:3
catnip -o tco batch_processing.cat

CI : reproducibilité

[mode.standalone]
jit = false
tco = false
optimize = 0

Notes

Les overrides par mode sont optionnels : si absents, la config de base s'applique
Les 3 modes peuvent coexister dans le même fichier
La détection de mode est automatique et transparente

Configuration

Fichier de Configuration

Structure de Base

Configuration Par Mode

Fonctionnement

Modes d'Exécution

Mode standalone (Scripts)

Mode repl (Interactif)

Mode DSL

Précédence des Configurations

Exemple de Précédence

Modules

Options de Cache

Diagnostics

Linter

Variables d'Environnement

Inspecter la Configuration

Exemples Pratiques

Dev : debugging avec optimisations désactivées

Prod : max performance

CI : reproducibilité

Notes

Mode `standalone` (Scripts)

Mode `repl` (Interactif)