How kuaterpillar/lbc works
1. Overall shape
- This repository is a Python 3.9+ package named lbc, an unofficial client for the Leboncoin marketplace.
- The core architectural boundary is between the public Python API (lbc.Client, models, enums) and the remote Leboncoin HTTP API it talks to.
2. Primary runtime path
- The main data flow is: user code calls lbc.Client → request-building/session logic in lbc/mixin/* → HTTP calls to Leboncoin → JSON response parsing into typed models in lbc/model/*.
- The README examples and examples/ folder show the intended usage pattern: search ads, fetch a single ad, fetch user info, and optionally route traffic through a proxy.
3. Client composition
- lbc/client.py is the top-level facade that likely composes the mixins and exposes the stable API.
- The package is organized around mixins rather than a deep class hierarchy, which keeps search, ad lookup, user lookup, and session/proxy concerns separated but available through one client object.
4. Network/session boundary
- lbc/mixin/session.py is the transport boundary: it is where HTTP session management, headers, proxy wiring, and request execution are centralized.
- lbc/model/proxy.py and the README’s Proxy examples show that proxy configuration is a first-class concern, not an afterthought.
- The README’s 403/Datadome note indicates the client is designed to operate against an anti-bot-protected external service, so request frequency and proxy quality materially affect behavior.
5. Search subsystem
- lbc/mixin/search.py handles the core query-building logic for Leboncoin search URLs and parameterized searches.
- Search inputs can come from structured arguments (text, category, locations, ranges like price and square) or a full Leboncoin URL, with URL input overriding other filters.
- This is the highest-volume path in the library and is the main source of result lists returned to callers.
6. Ad and user lookup subsystems
- lbc/mixin/ad.py and lbc/mixin/user.py represent secondary read APIs that retrieve a single ad or user profile/metadata.
- These paths likely share the same session layer and response-to-model conversion pipeline as search, but expose narrower resource-oriented operations.
7. Data model layer
- lbc/model/* contains the typed domain objects used by the client: ads, cities, searches, users, proxies, and enums.
- The enums in lbc/model/enums.py capture Leboncoin’s categorical values such as sort order, ad type, owner type, and categories, making the public API more stable than passing raw strings everywhere.
- City, Region, and Department show that geography is a key domain concept in the search model.
8. Utility and configuration support
- lbc/utils.py and lbc/dotenv.py provide shared helpers and environment loading/configuration support.
- The presence of .env.example, data/bot_config.json, and other JSON files suggests the project supports both library use and local operational tooling with externalized settings.
9. Generated/reference data
- utils/generate_enum_* scripts indicate some model enums or lookup tables are generated from source data, reducing manual maintenance for regions, departments, and categories.
- The data/ directory contains persisted JSON artifacts such as searches and seen ads, which appear to support tracking, caching, or monitoring workflows rather than the core library API.
10. Operational tools and automation
- monitor.py, market_analyzer.py, search_honda.py, and discord_bot.py are application-level scripts built on top of the library, not the library itself.
- .github/workflows/monitor.yml suggests at least one scheduled/automated monitoring use case.
- These utilities likely consume the core client, then transform search results into alerts, analytics, or bot messages.
11. Examples and tests
- examples/ demonstrates the supported use cases and acts as documentation for the architecture of the public API.
- test_full_features.py and test_moto_1500cc.py indicate integration-style validation against real or representative Leboncoin flows, especially search scenarios.
- The data/ JSON files likely double as fixtures or recorded state for these tests and tools.
12. Documentation and auxiliary assets
- README.md, CHANGELOG.md, RESOURCES.md, and claude.md describe usage and project context.
- The .claude/skills/* directories are auxiliary documentation/scripting assets for document processing and PDF handling; they are not part of the Leboncoin client architecture and appear unrelated to the main package.
Main entry points: client.py Client · search.py Search · session.py Session · ad.py Ads
Components 22
Core library
Public client, transport, and domain models for the Leboncoin API.
- lbc · Top-level package exports the public client and domain types.
lbc/__init__.py - Client · Primary entry point composing the library mixins into one API.
lbc/client.py - Session · HTTP session, headers, proxy wiring, and request execution.
lbc/mixin/session.py - Search · Builds search requests from arguments or full Leboncoin URLs.
lbc/mixin/search.py - Ad lookup · Fetches a single advertisement and related metadata.
lbc/mixin/ad.py - User lookup · Fetches user profiles and user-related metadata.
lbc/mixin/user.py - Ads · Typed advertisement structures returned by search and lookup flows.
lbc/model/ad.py - Searches · Search request and result models used by the query subsystem.
lbc/model/search.py - Users · Typed user structures for profile and metadata responses.
lbc/model/user.py - Geo model · City, region, and department structures for location-based search.
lbc/model/city.py - Proxy · Proxy configuration object used by the session layer.
lbc/model/proxy.py - Enums · Stable categorical values such as sort order, categories, and owner type.
lbc/model/enums.py - Helpers · Shared utility helpers and configuration support.
lbc/utils.py - Dotenv · Environment loading helpers for local and operational setup.
lbc/dotenv.py
Apps and tools
Scripts and automations built on top of the library.
- Monitor · Scheduled or long-running monitoring script built on the client.
monitor.py - Analyzer · Market analysis workflow that consumes search and model data.
market_analyzer.py - Discord bot · Chatbot integration layered on top of the core client.
discord_bot.py - Search tools · Ad-hoc scripts for running searches with specific inputs or proxies.
search_honda.py
Data and generation
Persisted artifacts and enum-generation helpers.
- Data files · Persisted searches, seen ads, prices, and bot configuration.
data/searches.json - Enum generators · Scripts that derive enum and lookup data from source material.
utils/generate_enum_categories.py
Connections 26
- lbc → Client: exports · The package exposes the main client entry point.
- Client → Session: uses · Client methods rely on the shared HTTP/session boundary.
- Client → Search: searches · Search is the primary high-volume API path.
- Client → Ad lookup: gets ad · Client exposes single-ad retrieval.
- Client → User lookup: gets user · Client exposes user lookup operations.
- Session → Proxy: accepts · Session configuration can include proxies.
- Session → Helpers: shares helpers · Transport and request logic use common helpers.
- Search → Searches: returns · Search responses are converted into search domain models.
- Search → Ads: yields ads · Search results are normalized into ad objects.
- Search → Enums: filters by · Search parameters use stable categorical enums.
- Search → Geo model: uses geo · Location filters depend on geography models.
- Ad lookup → Ads: returns · Single-ad fetches produce ad models.
- User lookup → Users: returns · User lookup produces user models.
- Ads → Enums: typed by · Ad fields use library enums for categories and metadata.
- Searches → Geo model: contains · Search structures include location-aware data.
- Proxy → Session: configures · Proxy objects feed into session setup.
- Dotenv → Session: configures · Environment loading supports transport configuration.
- Enum generators → Enums: generates · Code generation scripts maintain enum and lookup data.
- Data files → Monitor: inputs · Persisted JSON state supports monitoring and analytics workflows.
- Data files → Analyzer: inputs · Analytics scripts consume stored searches and price data.
- Examples → Client: demonstrates · Examples show the public client usage patterns.
- README → Examples: documents · The README points to example workflows.
- Monitor → Client: uses · Monitoring automation is built on the core client.
- Analyzer → Client: uses · Analysis tooling uses the same library API.
- Discord bot → Client: uses · Bot integration consumes library search and lookup APIs.
- Search tools → Client: uses · Ad-hoc scripts call into the client for searches.