Référence développeur de Sweepy

Sweepy est un petit projet Python avec un moteur plat. Cette page associe chaque étape du pipeline au module qui l’exécute, pour que vous sachiez où modifier le code.

Public visé

Lisez cette page si vous prévoyez de modifier le code de Sweepy ou d’ajouter une source d’emploi. Les relecteurs peuvent s’en servir pour situer une demande de fusion. Elle couvre uniquement l’intérieur : modules, dépendances et versions de Python.

astuce

Ignorez cette page si vous voulez lancer des balayages. Commencez par Installation.

Étapes du pipeline et modules

swee.py exécute cinq étapes dans l’ordre. Le terminal affiche chaque étape de [1/5] à [5/5].

Étape	Module	Ce qu’il fait
1. Chargement du profil	engine/config.py	Charge et valide votre profil YAML. L’assistant du même module en écrit un.
2. Découverte des offres	engine/discovery.py	Interroge les flux d’agrégateurs via python-jobspy et classe chaque plateforme.
2. Découverte des offres	engine/sources/	Récupère les sites Greenhouse, Ashby, Lever, Workable et Built In NYC depuis des points d’accès publics.
2. Déduplication	swee.py	Fusionne les résultats des agrégateurs et des sources en une fiche par lien d’offre.
3. Vérification des URL	engine/validator.py	Vérifie chaque lien avec une requête HTTP HEAD et un repli GET. Il écarte les offres mortes.
4. Notation par rapport au CV	engine/scorer.py	Extrait les termes de l’offre et du CV, puis note le chevauchement des exigences et des mots-clés. Il étiquette les offres qui exigent des réponses rédigées.
5. Affectation des parcours de CV	engine/enrich.py	Choisit le parcours au plus fort chevauchement de termes et applique la couleur de badge correspondante.
5. Enrichissement des fiches	engine/enrich.py	Construit les résumés de fiche, les lignes de rémunération et le texte des conseils personnalisés.
5. PDF de fiches par défaut	engine/report.py	Effectue le rendu de la structure en fiches, six fiches par page par défaut, et renvoie le nombre de pages.
5. PDF en tableau hérité	engine/pdf_builder.py	Effectue le rendu de la structure en tableau quand votre profil définit report.style: legacy.
5. Exports de données	engine/exporter.py	Écrit les fichiers CSV et JSON. Il rastérise les images PNG de page sur demande.
5. Suivi des candidatures	engine/tracking.py	Ajoute les colonnes de suivi et relit les exports antérieurs pour retrouver les valeurs que vous avez saisies.

engine/session.py contient le stockage des fiches pour le flux avec état du Model Context Protocol (MCP). Il garde les fiches dans une table thread-safe indexée par un hachage stable de chaque lien d’offre.

Où modifier le code

Vous voulez modifier	Commencez dans
Une source d’emploi ou son point d’accès	engine/sources/, plus une liste d’amorçage dans data/sources/
La façon dont les correspondances sont notées	engine/scorer.py
Ce qu’affiche une fiche	engine/enrich.py, puis engine/report.py
La façon dont les liens sont vérifiés	engine/validator.py
Une option de ligne de commande	swee.py
Un outil MCP	server.py

astuce

server.py importe les mêmes modules du moteur que l’outil en ligne de commande. Testez le chemin MCP après toute modification du moteur, car une correction touche les deux points d’entrée.

Référence des modules

Points d’entrée

Module	Rôle
swee.py	Orchestrateur principal et point d’entrée argparse du pipeline en cinq étapes.
server.py	Serveur Model Context Protocol (stdio) qui expose les outils du moteur aux assistants IA.

Modules du moteur

Module	Rôle
engine/config.py	Assistant interactif, plus chargement et validation du YAML.
engine/discovery.py	Orchestration des extracteurs pour python-jobspy et les sources déterministes, détection des systèmes de suivi des candidatures (ATS) et déduplication.
engine/validator.py	Vérifications de disponibilité des liens avec détection de soft-404. Les liens invérifiables restent dans l’exécution.
engine/scorer.py	Extraction des termes du CV, calcul du pourcentage de correspondance, étiquetage et notation par parcours.
engine/enrich.py	Enrichissement des fiches pour les résumés, la rémunération, l’affectation aux parcours et les conseils personnalisés.
engine/session.py	Stockage de fiches thread-safe avec identifiants stables pour le flux MCP avec état.
engine/report.py	PDF par défaut à structure de fiches.
engine/pdf_builder.py	PDF hérité à structure de tableau pour report.style: legacy.
engine/exporter.py	Exports CSV et JSON, plus rastérisation PNG des rapports PDF.
engine/tracking.py	Colonnes de suivi et relecture des exports antérieurs pour le report des valeurs.
engine/docx.py	Conversion DOCX vers PDF avec python-docx et reportlab, plus un repli sur Microsoft Word.
engine/documents.py	Répartition des documents pour --convert et le convertisseur MCP, couvrant DOCX, DOC, texte, Markdown et PDF.
engine/logging.py	Journaux de débogage optionnels dans logs/.
engine/cache.py	Cache SQLite des extractions indexé par requête et par ensemble de moteurs, avec une durée de vie d’une heure.
engine/circuit_breaker.py	Compte les erreurs consécutives d’une source et suspend les appels pendant un délai de refroidissement.
engine/engine_defaults.py	Listes de sites et réglages de moteurs partagés, sans import pour éviter les cycles.
engine/engines.py	Registre d’adaptateurs et installateur pour les moteurs optionnels hirehunt, openroles, apify et jobdrop.
engine/history.py	Enregistrement persistant des offres déjà rapportées. Un balayage quotidien ne rapporte que les nouveaux postes.
engine/normalize.py	Normalise les lignes brutes des moteurs vers les colonnes d’offre partagées.
engine/salary.py	Extraction de la rémunération depuis le texte de l’offre quand un site omet le salaire structuré.
engine/sweep_config.py	Applique les valeurs par défaut partagées du moteur aux paramètres du profil.
engine/updater.py	Vérification de mise à jour basée sur Git et réinstallation des dépendances du dépôt.

Sources déterministes

Module	Rôle
engine/sources/__init__.py	Exports des récupérateurs et chargement des listes d’amorçage depuis data/sources/.
engine/sources/_common.py	Fonctions utilitaires partagées pour les en-têtes HTTP, le préfiltrage des intitulés et la conversion HTML vers texte.
engine/sources/greenhouse.py	Récupérateur de sites d’emploi Greenhouse.
engine/sources/ashby.py	Récupérateur de sites d’emploi Ashby.
engine/sources/lever.py	Récupérateur d’offres Lever.
engine/sources/workable.py	Récupérateur de l’API de widget Workable.
engine/sources/builtinnyc.py	Extracteur de catégories Built In NYC.

Adaptateurs de moteurs

Module	Rôle
engine/adapters/__init__.py	Registre qui associe chaque nom de moteur à son adaptateur.
engine/adapters/base.py	Classe de base ScraperAdapter, en-tête User-Agent partagé et utilitaires de forme des résultats.
engine/adapters/jobspy_adapter.py	Adaptateur d’agrégateur python-jobspy pour LinkedIn, Indeed, Glassdoor et ZipRecruiter.
engine/adapters/ats_adapter.py	Adaptateur au-dessus des récupérateurs ATS déterministes de engine/sources/.
engine/adapters/hirehunt_adapter.py	Adaptateur du moteur optionnel hirehunt.
engine/adapters/openroles_adapter.py	Adaptateur du moteur optionnel openroles.
engine/adapters/apify_adapter.py	Adaptateur d’acteur Apify optionnel.
engine/adapters/jobdrop_adapter.py	Adaptateur du moteur optionnel jobdrop.

Données, scripts et tests

Chemin	Rôle
data/sources/*.txt	Listes d’amorçage pour les sites, entreprises, organisations et catégories.
scripts/make_sample.py	Générateur du rapport d’exemple stocké dans docs/.
tests/	Suite pytest avec un fichier par domaine : adapters, config, documents, docx, engines, enrich, history, logging et report. D’autres fichiers couvrent salary, scorer, server, session, sources, swee, tracking, updater et validator.

Remarque

Ajoutez un fichier de test dédié quand vous modifiez discovery.py, exporter.py ou pdf_builder.py. Placez le fichier dans tests/.

Dépendances

Les paquets d’exécution viennent de requirements.txt. Les versions ci-dessous correspondent à ce fichier.

Paquet	Version	Ce qu’il apporte à Sweepy
reportlab	5.0.1	Construit le rapport PDF mis en forme avec des liens cliquables.
pymupdf	1.28.2	Extrait le texte des CV PDF et rastérise les exports PNG.
python-docx	1.2.0	Lit les CV .docx et reconstruit le texte DOCX en PDF sans Word.
requests	2.32.5	Atteint les points d’accès ATS et vérifie la réponse de chaque lien d’offre.
beautifulsoup4	4.15.0	Analyse le HTML des sources Greenhouse, Lever, Workable et Built In NYC.
pyyaml	6.0.3	Lit et écrit les profils YAML.
questionary	2.1.1	Pilote les questions de l’assistant interactif.
prompt-toolkit	3.0.53	Pilote la saisie de texte interactive de l’assistant.
python-jobspy	1.2.0	Extrait les offres de LinkedIn, Indeed, Glassdoor et ZipRecruiter sans identifiants API.
pandas	2.2.3	Structure les offres et construit les exports CSV et JSON.
mcp	1.30.0	Fait tourner le serveur Model Context Protocol.
anyio	4.12.1	Fait tourner le transport MCP asynchrone.

requirements.txt liste aussi un paquet optionnel. Décommentez docx2pdf quand Word doit construire le PDF.

• docx2pdf (0.5.2, optionnel) effectue le rendu DOCX vers PDF via Microsoft Word sous Windows. Sweepy l’appelle dès que Microsoft Word existe sur la machine.

Remarque

mcp reste volontairement en 1.x. Le SDK 2.x ne sert que l’ère de protocole 2026-07-28. Un client qui sonde server/discover puis se rabat sur la poignée de main initialize reçoit une erreur -32022. VS Code Copilot suit ce repli.

astuce

pandas reste volontairement en 2.x. Pandas 3.x exige Python 3.11 ou plus récent, et la matrice CI teste encore Python 3.10.

Paquets de développement (requirements-dev.txt)

Paquet	Version	Ce qu’il fait
pytest	9.1.1	Lance la suite de tests dans tests/.
pytest-cov	7.1.0	Rapporte la couverture de swee.py, server.py et engine/scorer.py.
ruff	0.17.0	Analyse le code et trie les imports.
tomli	2.2.1	Fournit tomllib pour les exécutions de test sous Python 3.10.

Terminal

pip install -r requirements.txt
pip install -r requirements-dev.txt
ruff check .
pytest -q

Prérequis et versions de Python prises en charge

Élément	Détail
Version minimale	Sweepy exige Python 3.10 ou plus récent et cible la syntaxe 3.10 dans chaque module.
Plage testée	Le workflow CI dans .github/workflows/ci.yml exécute Python 3.10, 3.11 et 3.12 sur Ubuntu.
Cible du linter	pyproject.toml définit target-version = "py310" pour ruff. Une construction réservée aux versions récentes fait échouer la tâche de lint.
Longueur de ligne	Ruff impose une limite de 100 caractères par ligne et ignore E501.
Étapes CI	La tâche installe les deux fichiers de dépendances et lance ruff check . avant pytest.

Remarque

pyproject.toml déclare requires-python = ">=3.10", donc pip refuse un interpréteur plus ancien à l’installation. La matrice CI et la cible ruff définissent la plage testée. Python 3.13 fonctionne en pratique mais reste hors de cette plage.

Python 3.13

Le paquet pymupdf peut se compiler depuis les sources quand aucune roue précompilée n’existe. Installez les Microsoft C++ Build Tools et sélectionnez la charge de travail « Desktop development with C++ » avant d’installer les dépendances.

Structure du dépôt

Arborescence du dépôt

swee.py             Point d’entrée CLI et orchestrateur du balayage
server.py           Serveur MCP sur stdio
engine/             Modules du pipeline
engine/sources/     Récupérateurs ATS déterministes
engine/adapters/    Adaptateurs d’agrégateurs et de moteurs optionnels
data/sources/       Listes d’amorçage pour chaque récupérateur
profiles/           Profils de recherche YAML
results/            Fichiers PDF, CSV, JSON et PNG générés
logs/               Journaux de débogage optionnels
styles/             Règles de style Vale pour la documentation
tests/              Suite pytest

Quand vous changez la signature d’un outil dans server.py, mettez à jour la référence des outils MCP dans le même commit.