El cliente de Python

Una envoltura fina y tipada sobre los mismos endpoints HTTP. Nada de lo que hace es imposible con fetch; simplemente te ahorra volver a escribir las clases de error, los reintentos y la negociación de formato.

Instalación

pip install xcrap-sdk

O con lo que uses de verdad:

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

Requiere · Python 3.9 o posterior. Una dependencia: httpx.

Nunca una clave

Nada a lo que registrarse, nada que guardar en una variable de entorno, nada que rotar cuando alguien la sube al repositorio.
Tipado hasta el fondo

Declaraciones completas para cada método y cada forma de respuesta, de modo que un nombre de campo mal escrito es un subrayado rojo y no una sorpresa en ejecución.
Markdown incorporado

Una opción convierte cualquier respuesta en markdown listo para un prompt, con una estimación de lo que le costará a tu ventana de contexto.

Dos líneas hasta una publicación

No hay clave que pasar ni cliente que configurar. Lo construyes y lo llamas.

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

Markdown, con su coste en tokens

Todos los métodos de lectura aceptan una opción markdown. La respuesta vuelve como una cadena lista para un prompt, y el cliente anota cuántos tokens costará probablemente, para comprobar un presupuesto antes de gastarlo.

# 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)

Hilos y cronologías

Un hilo vuelve desenrollado y en orden, desde la primera publicación y no desde la última. Una cronología pagina con cursores para que no tengas que guardarlos.

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)

Búsqueda, con los operadores de X

Pasa la consulta tal como la escribirías en X, operadores incluidos. Vuelve una página con el cursor de la siguiente. La búsqueda tiene el presupuesto más ajustado de todos los métodos: una consulta precisa vale más que cinco amplias.

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)

Los errores son tipos, no códigos

Cada fallo es una clase que puedes capturar por su nombre. Un 404 es una publicación borrada o privada, un 429 lleva los segundos que faltan para que se reabra la ventana, y un fallo de red se distingue de una negativa.

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

Todos los métodos

Todos aceptan un formato y una opción markdown, y todos devuelven las mismas formas que devuelve la API HTTP.

tweet(url, **opts): Una publicación, resuelta del todo: texto, autor, métricas, medios, encuesta y la publicación citada si la hay.
thread(url, **opts): Un hilo entero desde cualquiera de sus publicaciones, desenrollado en orden de publicación.
search(query, **opts): Posts que coinciden con una consulta — recientes, destacados, fotos o vídeos — dentro de un rango de fechas opcional.
replies(url, **opts): Una página de las respuestas directas a un post, primero las más gustadas o las más recientes.
user(handle, **opts): Un perfil: biografía, cifras, fecha de alta, verificación, ubicación y web.
user_tweets(handle, **opts): Una página de publicaciones de una cuenta, con el cursor de la siguiente.
iter_user_tweets(handle, limit=…): Lo mismo, como generador que sigue los cursores por ti y se detiene en el límite.
user_history(handle, **opts): Hasta mil posts de una cuenta en una llamada, de más reciente a más antiguo, dentro de un rango de fechas opcional.
followers(handle, **opts): Una página de las cuentas que siguen a una cuenta.
following(handle, **opts): Una página de las cuentas que sigue una cuenta.
trends(**opts): Qué es tendencia, con el número de publicaciones cuando X lo da.
media(url, **opts): Cada archivo adjunto, en todos los bitrates que X codificó, como enlaces directos.
download_media(url, **opts): Devuelve uno de esos archivos como bytes en lugar de como enlace.
bulk(urls, **opts): Hasta cincuenta publicaciones en una petición. Un enlace muerto solo hace fallar su entrada.

Cada parámetro, en la referencia de la API También hay un cliente de Node.