Notebooks dans les extensions

Les extensions peuvent inclure des notebooks marimo en tant que contenu de premier ordre. Un notebook livré par une extension apparaît dans Analytics → Notebooks → From extension pour chaque organisation qui installe l'extension ; l'ajouter copie le notebook dans l'espace de travail courant, où il se comporte exactement comme un notebook créé par un utilisateur (ouverture, modification, accès gouverné au SDK scrydon).

Usages typiques : une visite de prise en main du modèle de données de l'extension, un modèle d'analyse portant sur les sources de données de l'extension, ou un parcours guidé d'écriture en retour gouvernée.

Structure de l'extension

Chaque notebook est un sous-répertoire de l'extension :

my-extension/
  manifest.json               # extension manifest — declares the notebook entries
  notebooks-quickstart/
    manifest.json             # notebook content manifest
    notebook.py               # the marimo notebook (≤ 1 MB)
  notebooks-writeback-demo/
    manifest.json
    notebook.py

Déclarez chaque notebook dans les contents du manifeste de l'extension :

{
  "contents": [
    { "kind": "notebook", "path": "notebooks-quickstart", "required": true },
    { "kind": "notebook", "path": "notebooks-writeback-demo", "required": false }
  ]
}

Le type notebook est répétable — livrez autant de notebooks que vous le souhaitez.

Le manifeste de contenu du notebook

notebooks-<slug>/manifest.json :

{
  "slug": "quickstart",
  "name": "Lakehouse quickstart",
  "description": "Read a managed table, run an analysis, and publish the result back."
}

notebook.py doit être un fichier de notebook marimo valide d'au plus 1 Mo.

Ce qui se passe à l'installation

L'installation de l'extension ne place pas de notebooks dans l'espace de travail de quiconque. L'installation stocke chaque notebook.py dans un stockage à portée de l'organisation et répertorie le notebook dans le catalogue d'extensions de l'organisation. Les utilisateurs récupèrent ensuite ceux qu'ils souhaitent :

1. Analytics → Notebooks → From extension répertorie tous les notebooks des extensions installées de l'organisation.
2. Add copie le fichier dans l'environnement de l'espace de travail courant et crée une entrée de notebook dans l'espace de travail.
3. À partir de là, c'est un notebook normal — l'extension n'est plus consultée, et les mises à jour ultérieures de l'extension n'écrasent pas la copie d'un utilisateur.

Ajouter deux fois le même notebook d'extension est idempotent : la copie existante dans l'espace de travail est renvoyée au lieu d'un doublon.

Écrire des notebooks d'extension portables

• Utilisez le SDK scrydon pour tout accès aux données (tables, knowledge, llm) — ne codez jamais en dur d'URL ni d'identifiants. Voir Notebooks Marimo.
• Résolvez les tables par leurs noms logiques (les noms que créent les sources de données de votre extension) afin que le notebook fonctionne dans toute organisation ayant installé l'extension.
• Protégez les extensions facultatives : llm.complete lève LlmNotConfiguredError lorsque l'organisation n'a aucune extension LLM — interceptez-la et dégradez le comportement en douceur.

Voir aussi

• Notebooks Marimo — l'environnement d'exécution des notebooks et le SDK scrydon
• Extensions avec extensions — le format général d'archive d'extension
• Versionnement des extensions