web-core

web-core est un package d'infrastructure web partagée pour Python, décrit comme alimentant le serveur MCP wet-mcp et d'autres applications en aval. Il regroupe plusieurs capacités orientées web derrière une API publique typée, et le README précise que les sélecteurs spécifiques aux sites sont délibérément laissés aux applications consommatrices — le package lui-même ne fournit que l'infrastructure générique, les cookies et sélecteurs par domaine étant fournis via des variables d'environnement. Capacités listées dans le README : - Recherche SearXNG : un exécuteur singleton inter-processus (basé sur un verrouillage de fichier, garantissant une seule instance pour tous les processus Python) ainsi qu'un client qui effectue des tentatives de reconnexion, la déduplication des résultats et le filtrage des domaines. - Scraping multi-stratégies : un agent machine à états LangGraph qui escalade à travers différentes stratégies. Les modules de stratégie inclus comprennent la récupération directe via API, le HTTP basique, l'usurpation d'empreinte TLS via curl-cffi, le rendu headless via Crawl4AI, le rendu par navigateur furtif Patchright, le rendu distant via un RenderClient, et une stratégie CAPTCHA basée sur CapSolver. Les stratégies sont tentées selon l'ordre recommandé par le cache, les réponses sont validées et les échecs escaladent automatiquement — notamment le passage d'un shell JavaScript sous-rendu vers un backend de rendu. Un StrategyCache suit les performances par domaine. - Client HTTP sécurisé contre le SSRF : un client httpx avec épinglage DNS, normalisation d'URL, suppression des paramètres de suivi et aides à la validation de domaine. Tout le trafic HTTP sortant est destiné à passer par safe_httpx_client pour se prémunir contre le DNS rebinding. - Navigateurs et rendu distant : un protocole BrowserProvider plus un fournisseur Patchright (Playwright non détecté), un BrowserlessClient pour les points de terminaison /content auto-hébergés, et un client Cloudflare Browser Rendering, visant des conteneurs légers qui déportent le rendu JavaScript. - Conformité robots.txt : une vérification mise en cache par domaine avant la récupération. - Inférence de sélecteurs par LLM (optionnel) : lorsque les sélecteurs intégrés échouent, un fournisseur peut être auto-détecté selon la clé API présente (Google Gemini, OpenAI, Anthropic, xAI) ; si aucune clé n'est définie, l'inférence est ignorée silencieusement. Un llm_caller personnalisé peut également être injecté. Gemini peut être routé via Vertex AI via des variables de projet/location. - Adaptateurs d'API externes : clients typés et sécurisés contre le SSRF pour la récupération de dossiers/fichiers Google Drive et MangaDex (mangas, chapitres, images). L'installation se fait depuis PyPI sous le nom n24q02m-web-core (uv add), avec une ligne stable v2.x. La configuration est entièrement pilotée par variables d'environnement et chaque variable est optionnelle — l'omission de l'une désactive la fonctionnalité qu'elle contrôle, et aucune variable n'est requise pour importer ou utiliser le package. Les variables documentées couvrent l'URL SearXNG et l'utilisateur d'exécution, les cookies par domaine (JSON) pour le scraping, ainsi que les clés du fournisseur LLM et la substitution de modèle pour l'inférence de sélecteurs. Les identifiants de rendu distant sont passés comme arguments de constructeur. L'architecture est organisée sous src/web_core avec des modules stratifiés : http (primitives sécurisées SSRF, utilitaires d'URL), search (client, modèles, exécuteur), scraper (agent, stratégie de base, cache, robots, inférence de sélecteurs, état, utils et le sous-package strategies), browsers (protocole, patchright, browserless, cf_rendering) et adapters (google_drive, mangadex). Le package inclut un marqueur py.typed pour le typage PEP 561. Les décisions de conception mises en avant incluent l'épinglage DNS pour la protection SSRF, l'escalade automatique des stratégies, le singleton SearXNG inter-processus et l'utilisation du typage structurel basé sur Protocol afin que les implémentations de navigateur et de rendu n'aient pas besoin d'hériter d'une classe de base. Le développement cible Python 3.13 avec uv, des raccourcis de tâches mise optionnels, des hooks pre-commit, ruff pour le lint/format, ty pour la vérification du typage et pytest avec coverage — la suite de tests impose un seuil de couverture de 95 % et utilise asyncio_mode auto. Les fichiers de test reflètent la structure des modules sources. Le projet est sous licence Apache-2.0.