Le client Python

Une fine enveloppe typée au-dessus des mêmes endpoints HTTP. Rien de ce qu'il fait n'est impossible avec fetch ; il vous évite juste de réécrire les classes d'erreur, les réessais et la négociation de format.

Installation

pip install xcrap-sdk

Ou, avec ce que vous utilisez vraiment :

uv add xcrap-sdk
poetry add xcrap-sdk
pdm add xcrap-sdk

Prérequis · Python 3.9 ou plus récent. Une seule dépendance : httpx.

Aucune clé, jamais

Rien à quoi s'inscrire, rien à stocker dans une variable d'environnement, rien à faire tourner quand quelqu'un la commite.
Typé de bout en bout

Des déclarations complètes pour chaque méthode et chaque forme de réponse : un nom de champ erroné devient un soulignement rouge, pas une surprise à l'exécution.
Markdown intégré

Une option transforme n'importe quelle réponse en markdown prêt pour un prompt, avec une estimation de ce que ça coûtera à votre fenêtre de contexte.

Deux lignes pour un post

Aucune clé à passer, aucun client à configurer. On l'instancie et on l'appelle.

from xcrap import Xcrap

with Xcrap() as xcrap:
    tweet = xcrap.tweet("https://x.com/jack/status/20")
    print(tweet.text)            # just setting up my twttr
    print(tweet.metrics.likes)   # 308067

Du markdown, avec son coût en tokens

Chaque méthode de lecture accepte une option markdown. La réponse revient sous forme de chaîne prête pour un prompt, et le client note combien de tokens cette chaîne coûtera probablement, pour vérifier un budget avant de le dépenser.

# Markdown, ready to drop into a prompt.
md = xcrap.tweet("https://x.com/jack/status/20", markdown=True)

# How many tokens that will cost, before you spend them.
print(xcrap.last_meta.markdown_tokens)

Fils et timelines

Un fil revient déroulé et dans l'ordre, à partir du premier post et non du dernier. Une timeline pagine via les curseurs pour que vous n'ayez pas à les garder.

thread = xcrap.thread(
    "https://x.com/naval/status/1002103360646823936",
)

print(thread.count)                  # 31
for post in thread.tweets:
    print(post.text)

# And a timeline paginates itself.
for post in xcrap.iter_user_tweets("naval", limit=200):
    print(post.id)

La recherche, avec les opérateurs de X

Passez la requête telle que vous la taperiez dans X, opérateurs compris. Une page revient avec le curseur de la suivante. La recherche a le budget le plus serré de toutes les méthodes : une requête précise vaut mieux que cinq larges.

page = xcrap.search(
    "from:nasa mars",
    feed="latest",          # or "top", "photos", "videos"
    since="2026-01-01",
)

for post in page.tweets:
    print(post.author.screen_name, post.text)

# The next page, when there is one.
if page.next_cursor:
    xcrap.search("from:nasa mars", cursor=page.next_cursor)

Les erreurs sont des types, pas des codes

Chaque échec est une classe qu'on attrape par son nom. Un 404 est un post supprimé ou privé, un 429 porte le nombre de secondes avant réouverture de la fenêtre, et une panne réseau se distingue d'un refus.

from xcrap import Xcrap, XcrapNotFound, XcrapRateLimited

try:
    xcrap.tweet("https://x.com/jack/status/1")
except XcrapNotFound:
    return None
except XcrapRateLimited as error:
    # The client already knows when the window resets.
    time.sleep(error.retry_after)
    raise

Toutes les méthodes

Toutes acceptent un format et une option markdown, et toutes renvoient les mêmes formes que l'API HTTP.

tweet(url, **opts): Un post, entièrement résolu : texte, auteur, compteurs, médias, sondage et post cité éventuel.
thread(url, **opts): Un fil entier depuis n'importe lequel de ses posts, déroulé dans l'ordre de publication.
search(query, **opts): Les posts qui correspondent à une requête — récents, populaires, photos ou vidéos — dans une fenêtre de dates facultative.
replies(url, **opts): Une page des réponses directes à un post, les plus aimées ou les plus récentes d'abord.
user(handle, **opts): Un profil : bio, compteurs, date d'inscription, vérification, localisation et site web.
user_tweets(handle, **opts): Une page de posts d'un compte, avec le curseur pour la suivante.
iter_user_tweets(handle, limit=…): La même chose, sous forme de générateur qui suit les curseurs à votre place et s'arrête à la limite.
user_history(handle, **opts): Jusqu'à mille posts d'un compte en un appel, du plus récent au plus ancien, dans une fenêtre de dates facultative.
followers(handle, **opts): Une page des comptes qui suivent un compte.
following(handle, **opts): Une page des comptes qu'un compte suit.
trends(**opts): Ce qui est en tendance, avec le nombre de posts quand X le donne.
media(url, **opts): Chaque fichier attaché, à tous les débits encodés par X, en liens directs.
download_media(url, **opts): Renvoie l'un de ces fichiers en flux d'octets plutôt qu'en lien.
bulk(urls, **opts): Jusqu'à cinquante posts en une requête. Un lien mort ne fait échouer que son entrée.

Chaque paramètre, dans la référence de l'API Il existe aussi un client Node.