Passer au contenu principal
Il nécessite Python 3.10 ou plus récent. Il repose sur httpx et Pydantic v2, et il est livré avec des annotations de type complètes qui passent mypy et pyright en mode strict.

Installation

Démarrage rapide

Créez un article, puis listez le stock en main :
AsyncStockShift a les mêmes méthodes pour asyncio et Trio. Attendez chaque appel avec await et parcourez les pages avec async for :

Authentification

Passez une clé d’API ou un jeton d’accès OAuth dans token. Créez une clé d’API dans l’application sous Paramètres > Accès > Clés d’API. La clé agit au nom du membre qui l’a créée, et un appel exige à la fois l’autorisation du membre et l’une des portées de la clé. Pour un jeton OAuth qui expire, passez une fonction. Le client l’appelle avant chaque requête. AsyncStockShift accepte aussi une fonction coroutine :
Autres arguments : with_options() renvoie une copie avec d’autres paramètres qui partage les connexions :

Faire des appels

Chaque domaine de l’API est un attribut, comme catalog ou inventory, et chaque opération est une méthode de cet attribut. Les paramètres de chemin viennent en premier. Tout le reste est un argument nommé :
La docstring de chaque méthode nomme son chemin, comme GET /catalog/items/{item}, et reprend la référence de l’API. Un appel renvoie un modèle Pydantic de stockshift.models, ou une liste de modèles. Une réponse vide renvoie None, un export CSV son texte et un fichier la httpx.Response. Un champ que l’API ajoute après cette version est conservé dans le modèle, et vous pouvez le lire dans model_extra. Un champ facultatif du corps que vous omettez n’est pas envoyé. Passez None pour envoyer null, ce qui efface le champ. Pour appeler un chemin qui n’a pas de méthode dans cette version, utilisez request(). Elle renvoie la httpx.Response :

Pagination

Une liste qui peut grossir renvoie une page à la fois. Chaque liste paginée a une deuxième méthode qui commence par iter_. Elle suit les curseurs et produit chaque enregistrement :
Elle récupère la page suivante seulement quand les enregistrements de la précédente sont épuisés. Pour paginer vous-même, renvoyez le next_cursor de chaque page dans after jusqu’à ce qu’il soit None.

Erreurs

Un appel qui échoue lève une APIError qui contient le corps des détails du problème RFC 9457. Basez votre logique sur code, qui est stable. detail est rédigé pour des humains et peut changer.
APIError a aussi status, problem, headers et response. Un appel qui n’obtient aucune réponse, parce que le réseau a fait défaut ou que la tentative a expiré, lève une APIConnectionError. Les deux héritent de StockShiftError, qui est aussi levée pour une réponse que cette version ne sait pas lire.

Nouvelles tentatives et clés d’idempotence

Le client réessaie un 429 après le délai indiqué dans Retry-After. Il le fait pour toutes les méthodes, parce que l’API n’a pas exécuté l’appel. Si Retry-After dépasse max_retry_after, il lève plutôt une erreur. Un 5xx ou une défaillance réseau est réessayé pour GET, PUT et DELETE, avec un court délai progressif. Un POST ou un PATCH n’est réessayé que si vous lui donnez une clé d’idempotence, pour qu’une nouvelle tentative ne puisse pas appliquer la modification deux fois :
Utilisez une nouvelle clé pour chaque modification que vous voulez faire. Les points de terminaison qui tiennent compte de la clé l’indiquent dans la référence de l’API.

Webhooks

Vérifiez l’en-tête StockShift-Signature avant de faire confiance à une livraison. verify_webhook() a besoin du corps brut, exactement tel qu’il est arrivé :
Elle renvoie un modèle pour chaque type d’événement, ou un UnknownWebhookEvent pour un type ajouté après cette version. Elle refuse une livraison de plus de cinq minutes. Passez tolerance, en secondes, pour changer ce délai. Les nouvelles tentatives d’un événement gardent son id : conservez-le et ignorez les événements que vous avez déjà traités. Pour tester votre propre récepteur, sign_webhook() signe une charge utile de la même façon que StockShift.

Versions

La version majeure change quand l’API évolue d’une façon qui peut briser votre code, comme un champ retiré ou un nouveau paramètre obligatoire. Les nouveaux points de terminaison et champs arrivent dans des versions mineures. stockshift.API_VERSION contient la version de la référence de l’API à partir de laquelle le paquet a été construit.