Aller au contenu
northstar
Menu de la documentation

SDK Python

Installer le SDK, se connecter avec une clé API et comprendre le fonctionnement de son client.

En bref

Le SDK Python permet à votre code d'enregistrer et de gouverner des ressources dans Northstar : systèmes de stockage, sources, datasets, collections de documents, KPIs, tableaux de bord, équipes. Il s'authentifie avec la clé API d'un compte d'intégration et appelle l'API de la plateforme, jamais votre entrepôt. Tout ce qu'il fait respecte les rôles et les équipes du compte.

Installer

Le SDK demande Python 3.13 ou plus récent.

bash
pip install northstar-sdk
# ou
uv add northstar-sdk

Le paquet fournit les annotations de types : votre éditeur complète les arguments de chaque méthode.

Configurer

Le SDK lit deux variables d'environnement :

VariableValeurExemple
NORTHSTAR_API_URLL'adresse de votre plateforme, suivie de /apihttps://data.example.com/api
NORTHSTAR_API_KEYLa clé API du compte d'intégrationnorthstar_…

Vous pouvez aussi les passer dans le code, par exemple quand vous lisez la clé dans un gestionnaire de secrets :

python
from northstar_sdk import Client

client = Client(
    api_url="https://data.example.com/api",
    api_key=secrets["northstar-api-key"],
    timeout=120,  # secondes, la valeur par défaut
)

Client() lève une ValueError si l'adresse ou la clé manque.

Le client

Client est le point d'entrée unique. Il ne parle qu'à l'API de la plateforme : les identifiants de votre entrepôt, quand vous enregistrez un système de stockage, sont envoyés à Northstar, qui les chiffre.

L'organisation vient de la clé. Le premier appel qui en a besoin la demande une fois à la plateforme, puis la garde :

python
client = Client()
print(client.resolve_organization())  # l'identifiant de l'organisation de la clé

Les espaces de noms

Chaque type de ressource a son espace de noms sur le client :

Espace de nomsLectureÉcriture
client.storage_systems—create, upsert, update, delete
client.data_source_categories—create, upsert, update, delete
client.data_sourceslist, getcreate, upsert, update, delete
client.datasetslist, get, find_by_namecreate, upsert, update, delete
client.document_collections—create, upsert, update, delete, puis ingest()
client.kpislist, get, find_by_namecreate, upsert, update, delete
client.figureslist, getcreate, upsert, update, delete
client.dashboardsbrowse, get, find_by_titlecreate, upsert, update, delete, create_folder
client.dashboard_foldersbrowse, list, get, find_by_namecreate, upsert, update, delete
client.teamslist, find_by_name, find_by_slugcreate, upsert, update, delete
client.usersresolvecreate, upsert, update
client.organisations—create, upsert, update, delete
client.searchrecherche globale—

Les lectures ne renvoient que ce que voient les équipes du compte :

  • list(search=…, page=1, limit=20) renvoie une Page avec items, total, total_pages et has_next. list_all() récupère toutes les pages.
  • get(id) renvoie None quand la ressource n'existe pas ou que le compte ne peut pas la voir. get_or_raise(id) lève alors NotFoundError.
  • find_by_name(name) lève NotFoundError quand rien ne correspond, et AmbiguousLookupError quand plusieurs ressources correspondent.

Créer, modifier, upsert, supprimer

MéthodeÀ utiliser pourSi la ressource existe déjà
create(...)Ajouter une ressource qui ne doit pas encore existerÉchoue avec 409 Conflict, en donnant l'identifiant existant
update(id, ...)Modifier une ressource dont vous connaissez l'identifiantLa modifie ; échoue avec 404 si elle manque
upsert(...)Provisionner de façon idempotente, par exemple à chaque exécution d'un pipelineLa met à jour au lieu d'échouer
delete(id)Supprimer une ressourceLa supprime ; échoue avec 404 si elle manque

Chaque ressource est identifiée par une clé métier : le slug d'un système de stockage ou d'une source, le système de stockage et l'emplacement d'un dataset, l'URL d'intégration d'un tableau de bord. upsert utilise cette clé pour retrouver la ressource existante.

Les méthodes d'écriture renvoient un handle : un objet qui connaît l'identifiant de la ressource et propose ses actions. for_id(id) donne le handle d'une ressource existante.

python
dataset = client.datasets.upsert(
    location={"schema": "marts", "table": "orders"},
    name="Orders",
    type="TABLE",
    layer="GOLD",
    storage_system_slug="warehouse",
)
dataset.analyze()

same_dataset = client.datasets.for_id(dataset.dataset_id)

Gouvernance

Les handles des datasets, KPIs, tableaux de bord et figures portent les actions de gouvernance des équipes et ressources :

python
dataset.assign_to_team("sales")                       # droits par défaut du type de ressource
dataset.assign_to_team("finance", permissions=["view", "ask_ai"])
dataset.assign_owner("owner@example.com")
dataset.assign_editors(["editor@example.com"])
  • assign_to_team prend le slug de l'équipe. Un slug inconnu n'attribue rien : le résultat contient alors un avertissement, sans lever d'erreur.
  • Sans permissions, l'équipe reçoit les droits par défaut du type de ressource.
  • Le propriétaire et les éditeurs doivent appartenir à une équipe avec laquelle la ressource est partagée : rattachez d'abord l'équipe.
  • Les figures n'ont pas de propriétaire : appelez assign_editors sur elles, pas assign_owner. Les collections de documents se rattachent aux équipes dans l'application.
  • Un nouveau dataset n'est visible que des administrateurs de la plateforme tant qu'aucune équipe n'y a accès. Rattachez une équipe juste après l'avoir créé.

Erreurs

ErreurQuand
ValueErrorNORTHSTAR_API_URL ou NORTHSTAR_API_KEY manque, ou la clé n'a pas d'organisation
PermissionErrorLa clé est absente, inconnue ou révoquée (401)
httpx.HTTPStatusErrorToute autre réponse d'erreur : 400 entrée invalide, 403 droit manquant, 404 introuvable, 409 conflit. Le corps de la réponse l'explique.
NotFoundError, AmbiguousLookupErrorUne recherche par identifiant ou par nom n'a rien trouvé, ou a trouvé plusieurs ressources

Voir les réponses d'erreur pour leur contenu.

Questions fréquentes

Le SDK lit-il des données dans mon entrepôt ? Non. Il enregistre et gouverne des ressources ; Northstar lit l'entrepôt avec les identifiants du système de stockage.

Puis-je utiliser le SDK depuis un notebook ? Oui, avec la clé d'un compte d'intégration dans l'environnement. Utilisez une clé dédiée, et révoquez-la quand le notebook est terminé.

Quelles ressources le SDK ne gère-t-il pas encore ? Les règles de validation, les alertes, les transformations et les tableaux de bord construits dans Northstar se gèrent dans l'application. Le SDK enregistre les tableaux de bord intégrés depuis d'autres outils.

Voir aussi