lacentrale-pros-scraper 0.1.0__tar.gz

lacentrale_pros_scraper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğrahan Saka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lacentrale_pros_scraper-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md LICENSE
+recursive-include tests *.py *.html
+recursive-include examples *.py

lacentrale_pros_scraper-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: lacentrale-pros-scraper
+Version: 0.1.0
+Summary: Scrape La Centrale's dealer directory (pros.lacentrale.fr): French car dealers, SIREN/SIRET, opening hours and every vehicle in stock with Python.
+Author: Buğrahan Saka
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bugrahansss/lacentrale-pros-scraper
+Project-URL: Source, https://github.com/bugrahansss/lacentrale-pros-scraper
+Project-URL: Issues, https://github.com/bugrahansss/lacentrale-pros-scraper/issues
+Keywords: lacentrale,la centrale,pros.lacentrale.fr,car dealers,used cars,france,web scraping,scraper,scrapedo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# La Centrale Pros Scraper
+
+[![PyPI](https://img.shields.io/pypi/v/lacentrale-pros-scraper)](https://pypi.org/project/lacentrale-pros-scraper/)
+[![Python](https://img.shields.io/pypi/pyversions/lacentrale-pros-scraper)](https://pypi.org/project/lacentrale-pros-scraper/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Scrape [La Centrale's](https://www.lacentrale.fr) dealer directory and dealer pages ([pros.lacentrale.fr](https://pros.lacentrale.fr)) into structured data. List every car dealer in a **city, department, region or brand network**, open a dealer for its **SIREN and SIRET, founding year, verified badge, address with coordinates, opening hours, website and stock size**, and pull **every vehicle in its stock**: make, model, version, year, mileage, fuel, gearbox, price, monthly price, La Centrale's **deal rating** (very good, good, fair, bad), warranty and listing dates. JSON or CSV.
+
+```bash
+pip install lacentrale-pros-scraper
+export SCRAPEDO_TOKEN=your_token
+lacentrale-pros --city lyon -f csv -o lyon_dealers.csv          # directory cards
+lacentrale-pros --city lyon --details -o lyon_dealers.json      # + SIREN/SIRET, hours, website
+lacentrale-pros --city lyon --stock -f csv -o lyon_cars.csv     # every car of every dealer
+lacentrale-pros C045088 --stock -o stock.json                   # one dealer
+```
+
+## Why plain requests fail
+
+```python
+import requests
+
+r = requests.get("https://pros.lacentrale.fr/C045088")
+print(r.status_code)   # 403
+print(r.text[:200])    # ... Please enable JS and disable any ad blocker ... dd={'rt':'c' ...
+```
+
+lacentrale.fr is protected by DataDome, which answers a script with `403` and a JavaScript challenge. This package sends each request through [Scrape.do](https://scrape.do/?utm_source=github&utm_medium=readme&utm_campaign=lacentrale-pros-scraper), which returns the real page. A plain request is enough, no extra parameters: **1 credit per page**.
+
+## Where the data is
+
+* **Directory** (`www.lacentrale.fr/annuaire/garages-villes/<city>`, `garages-departements/<dept>`, `garages-regions/<region>`, `marques/<brand>`, `?page=N&perPage=20`): server-rendered cards with the dealer name, postcode and city, number of ads, a "Marques" badge for franchised dealers, and the dealer reference (`C` + 6 digits) in `data-tracking-meta`. Some dealers link to their own website instead of their La Centrale page, but the reference is still there.
+* **Dealer page** (`pros.lacentrale.fr/C045088`):
+  * an `AutoDealer` JSON-LD block with name, address and coordinates. Its `openingHoursSpecification` is a **JSON string inside the JSON**: decode it a second time.
+  * an identity card ("Vendeur vérifié", "Date de création", "Stock"; big groups show "Stock national" instead).
+  * a footer with **SIREN / SIRET** and the dealer's website.
+  * `window.__PRELOADED_STATE_LISTING__`, whose `search.hits` is the first page of stock (9 vehicles) and `search.total` the stock size.
+* **More stock**: `pros.lacentrale.fr/C045088/index?options=&page=2&vertical=car`, same state object.
+
+In a live test, Lyon had 17 dealers in the directory and 228 cars in stock, scraped for 37 credits. 42 of those cars carried La Centrale's "very good deal" badge and 52 "good deal"; the median price was €28,940.
+
+## Python
+
+```python
+from lacentrale_pros import LaCentralePros
+
+lc = LaCentralePros(token="YOUR_SCRAPEDO_TOKEN")   # or set SCRAPEDO_TOKEN
+
+for card in lc.directory("city", "Lyon"):
+    print(card.ref, card.name, card.postcode, card.ads)
+
+dealer, cars = lc.dealer_with_stock("C045088")
+print(dealer.name, dealer.siret, dealer.founded, dealer.opening_hours)
+for car in cars:
+    print(car.make, car.model, car.year, car.mileage, car.price, car.deal)
+print(lc.credits_used)
+```
+
+## Fields
+
+**Directory card:** `ref`, `name`, `postcode`, `city`, `ads`, `franchise`, `url`, `own_site`.
+
+**Dealer:** `ref`, `url`, `name`, `dealer_type` (`CONCESSIONNAIRE`, `CENTRE_MULTIMARQUES`, ...), `verified`, `founded`, `stock`, `stock_national`, `street`, `postcode`, `city`, `country`, `latitude`, `longitude`, `opening_hours`, `siren`, `siret`, `website`, `phone`.
+
+**Vehicle:** `reference`, `url`, `make`, `model`, `version`, `year`, `mileage`, `energy`, `gearbox`, `category`, `color`, `doors`, `price`, `monthly_from`, `deal` (`VERY_GOOD_DEAL`, `GOOD_DEAL`, `EQUITABLE_DEAL`, `BAD_DEAL`, `NOT_COMPUTED`), `warranty_months`, `first_online`, `last_update`, `department`, `pictures`, `photo`, `is_new`, `dealer_ref`, `dealer_name`.
+
+## Use it responsibly
+
+This is business data published by professional sellers. Some dealers are sole traders, so treat names and phone numbers as personal data under the GDPR: use them for legitimate purposes, honour objection requests, and respect La Centrale's terms. Don't republish vehicle photos. This is not legal advice.
+
+## Tests
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+The fixtures are fictional ("GARAGE EXEMPLE LYON", example.com).
+
+## License
+
+MIT

lacentrale_pros_scraper-0.1.0/README.md

@@ -0,0 +1,81 @@
+# La Centrale Pros Scraper
+
+[![PyPI](https://img.shields.io/pypi/v/lacentrale-pros-scraper)](https://pypi.org/project/lacentrale-pros-scraper/)
+[![Python](https://img.shields.io/pypi/pyversions/lacentrale-pros-scraper)](https://pypi.org/project/lacentrale-pros-scraper/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Scrape [La Centrale's](https://www.lacentrale.fr) dealer directory and dealer pages ([pros.lacentrale.fr](https://pros.lacentrale.fr)) into structured data. List every car dealer in a **city, department, region or brand network**, open a dealer for its **SIREN and SIRET, founding year, verified badge, address with coordinates, opening hours, website and stock size**, and pull **every vehicle in its stock**: make, model, version, year, mileage, fuel, gearbox, price, monthly price, La Centrale's **deal rating** (very good, good, fair, bad), warranty and listing dates. JSON or CSV.
+
+```bash
+pip install lacentrale-pros-scraper
+export SCRAPEDO_TOKEN=your_token
+lacentrale-pros --city lyon -f csv -o lyon_dealers.csv          # directory cards
+lacentrale-pros --city lyon --details -o lyon_dealers.json      # + SIREN/SIRET, hours, website
+lacentrale-pros --city lyon --stock -f csv -o lyon_cars.csv     # every car of every dealer
+lacentrale-pros C045088 --stock -o stock.json                   # one dealer
+```
+
+## Why plain requests fail
+
+```python
+import requests
+
+r = requests.get("https://pros.lacentrale.fr/C045088")
+print(r.status_code)   # 403
+print(r.text[:200])    # ... Please enable JS and disable any ad blocker ... dd={'rt':'c' ...
+```
+
+lacentrale.fr is protected by DataDome, which answers a script with `403` and a JavaScript challenge. This package sends each request through [Scrape.do](https://scrape.do/?utm_source=github&utm_medium=readme&utm_campaign=lacentrale-pros-scraper), which returns the real page. A plain request is enough, no extra parameters: **1 credit per page**.
+
+## Where the data is
+
+* **Directory** (`www.lacentrale.fr/annuaire/garages-villes/<city>`, `garages-departements/<dept>`, `garages-regions/<region>`, `marques/<brand>`, `?page=N&perPage=20`): server-rendered cards with the dealer name, postcode and city, number of ads, a "Marques" badge for franchised dealers, and the dealer reference (`C` + 6 digits) in `data-tracking-meta`. Some dealers link to their own website instead of their La Centrale page, but the reference is still there.
+* **Dealer page** (`pros.lacentrale.fr/C045088`):
+  * an `AutoDealer` JSON-LD block with name, address and coordinates. Its `openingHoursSpecification` is a **JSON string inside the JSON**: decode it a second time.
+  * an identity card ("Vendeur vérifié", "Date de création", "Stock"; big groups show "Stock national" instead).
+  * a footer with **SIREN / SIRET** and the dealer's website.
+  * `window.__PRELOADED_STATE_LISTING__`, whose `search.hits` is the first page of stock (9 vehicles) and `search.total` the stock size.
+* **More stock**: `pros.lacentrale.fr/C045088/index?options=&page=2&vertical=car`, same state object.
+
+In a live test, Lyon had 17 dealers in the directory and 228 cars in stock, scraped for 37 credits. 42 of those cars carried La Centrale's "very good deal" badge and 52 "good deal"; the median price was €28,940.
+
+## Python
+
+```python
+from lacentrale_pros import LaCentralePros
+
+lc = LaCentralePros(token="YOUR_SCRAPEDO_TOKEN")   # or set SCRAPEDO_TOKEN
+
+for card in lc.directory("city", "Lyon"):
+    print(card.ref, card.name, card.postcode, card.ads)
+
+dealer, cars = lc.dealer_with_stock("C045088")
+print(dealer.name, dealer.siret, dealer.founded, dealer.opening_hours)
+for car in cars:
+    print(car.make, car.model, car.year, car.mileage, car.price, car.deal)
+print(lc.credits_used)
+```
+
+## Fields
+
+**Directory card:** `ref`, `name`, `postcode`, `city`, `ads`, `franchise`, `url`, `own_site`.
+
+**Dealer:** `ref`, `url`, `name`, `dealer_type` (`CONCESSIONNAIRE`, `CENTRE_MULTIMARQUES`, ...), `verified`, `founded`, `stock`, `stock_national`, `street`, `postcode`, `city`, `country`, `latitude`, `longitude`, `opening_hours`, `siren`, `siret`, `website`, `phone`.
+
+**Vehicle:** `reference`, `url`, `make`, `model`, `version`, `year`, `mileage`, `energy`, `gearbox`, `category`, `color`, `doors`, `price`, `monthly_from`, `deal` (`VERY_GOOD_DEAL`, `GOOD_DEAL`, `EQUITABLE_DEAL`, `BAD_DEAL`, `NOT_COMPUTED`), `warranty_months`, `first_online`, `last_update`, `department`, `pictures`, `photo`, `is_new`, `dealer_ref`, `dealer_name`.
+
+## Use it responsibly
+
+This is business data published by professional sellers. Some dealers are sole traders, so treat names and phone numbers as personal data under the GDPR: use them for legitimate purposes, honour objection requests, and respect La Centrale's terms. Don't republish vehicle photos. This is not legal advice.
+
+## Tests
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests
+```
+
+The fixtures are fictional ("GARAGE EXEMPLE LYON", example.com).
+
+## License
+
+MIT

lacentrale_pros_scraper-0.1.0/examples/good_deals.py

@@ -0,0 +1,28 @@
+"""Every car rated "very good deal" by La Centrale among a city's dealers, cheapest first.
+
+    SCRAPEDO_TOKEN=... python examples/good_deals.py lyon
+"""
+
+import csv
+import sys
+
+from lacentrale_pros import LaCentralePros
+
+city = sys.argv[1] if len(sys.argv) > 1 else "lyon"
+lc = LaCentralePros()
+
+deals = []
+for card in lc.directory("city", city):
+    if not card.ads:
+        continue
+    dealer, cars = lc.dealer_with_stock(card.ref)
+    deals += [c for c in cars if c.deal == "VERY_GOOD_DEAL"]
+    print(f"{dealer.name}: {len(cars)} cars", file=sys.stderr)
+
+deals.sort(key=lambda c: c.price or 0)
+with open(f"{city}_very_good_deals.csv", "w", newline="", encoding="utf-8") as fh:
+    writer = csv.DictWriter(fh, fieldnames=["make", "model", "version", "year", "mileage", "price", "dealer_name", "url"],
+                            extrasaction="ignore")
+    writer.writeheader()
+    writer.writerows(c.to_dict() for c in deals)
+print(f"{len(deals)} very good deals, {lc.credits_used} credits", file=sys.stderr)

lacentrale_pros_scraper-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lacentrale-pros-scraper"
+version = "0.1.0"
+description = "Scrape La Centrale's dealer directory (pros.lacentrale.fr): French car dealers, SIREN/SIRET, opening hours and every vehicle in stock with Python."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Buğrahan Saka" }]
+keywords = ["lacentrale", "la centrale", "pros.lacentrale.fr", "car dealers", "used cars", "france", "web scraping", "scraper", "scrapedo"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://github.com/bugrahansss/lacentrale-pros-scraper"
+Source = "https://github.com/bugrahansss/lacentrale-pros-scraper"
+Issues = "https://github.com/bugrahansss/lacentrale-pros-scraper/issues"
+
+[project.scripts]
+lacentrale-pros = "lacentrale_pros.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

lacentrale_pros_scraper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lacentrale_pros_scraper-0.1.0/src/lacentrale_pros/__init__.py

@@ -0,0 +1,25 @@
+"""Scrape La Centrale's dealer directory (pros.lacentrale.fr): dealers, profiles and stock."""
+
+from .client import LaCentralePros, ScrapeError
+from .parser import (
+    Dealer,
+    DealerCard,
+    DirectoryPage,
+    StockPage,
+    Vehicle,
+    dealer_ref,
+    dealer_url,
+    directory_url,
+    opening_hours,
+    parse_dealer,
+    parse_directory,
+    parse_stock,
+    stock_url,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "LaCentralePros", "ScrapeError", "Dealer", "DealerCard", "DirectoryPage", "StockPage", "Vehicle",
+    "dealer_ref", "dealer_url", "directory_url", "opening_hours", "parse_dealer", "parse_directory",
+    "parse_stock", "stock_url", "__version__",
+]

lacentrale_pros_scraper-0.1.0/src/lacentrale_pros/cli.py

@@ -0,0 +1,120 @@
+"""Command line entry point.
+
+    lacentrale-pros --city lyon -f csv -o lyon_dealers.csv
+    lacentrale-pros --city lyon --details -o lyon_dealers.json
+    lacentrale-pros --city lyon --stock -f csv -o lyon_cars.csv
+    lacentrale-pros C045088 --stock -o stock.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from typing import Any, List, Optional
+
+from . import __version__
+from .client import TOKEN_ENV, LaCentralePros, ScrapeError
+from .parser import CARD_FIELDS, DEALER_FIELDS, VEHICLE_FIELDS
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="lacentrale-pros",
+                                description="Scrape La Centrale's dealer directory, dealer profiles and dealer stock.")
+    p.add_argument("dealers", nargs="*", help="Dealer references or URLs (C045088, https://pros.lacentrale.fr/C045088)")
+    p.add_argument("--city", action="append", default=[], help="Directory by city (lyon, paris, ...)")
+    p.add_argument("--department", action="append", default=[], help="Directory by department (rhone, nord, ...)")
+    p.add_argument("--region", action="append", default=[], help="Directory by region (bretagne, ile-de-france, ...)")
+    p.add_argument("--brand", action="append", default=[], help="Directory by brand (peugeot, bmw, ...)")
+    p.add_argument("--pages", type=int, default=0, help="Directory pages per search, 20 dealers each (default: all)")
+    p.add_argument("--details", action="store_true", help="Open every dealer page: SIREN/SIRET, founding year, hours, website")
+    p.add_argument("--stock", action="store_true", help="Output every vehicle in each dealer's stock (9 per page)")
+    p.add_argument("--limit", type=int, default=0, help="Stop after this many dealers")
+    p.add_argument("-t", "--token", help=f"Scrape.do API token (default: ${TOKEN_ENV})")
+    p.add_argument("-f", "--format", choices=("json", "csv"), default="json")
+    p.add_argument("-o", "--output", help="Write to this file instead of stdout")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def _write(rows: List[dict], fields: List[str], fmt: str, output: Optional[str]) -> None:
+    out = open(output, "w", newline="", encoding="utf-8") if output else sys.stdout
+    try:
+        if fmt == "json":
+            json.dump(rows, out, ensure_ascii=False, indent=2)
+            out.write("\n")
+        else:
+            writer = csv.DictWriter(out, fieldnames=fields, extrasaction="ignore")
+            writer.writeheader()
+            for row in rows:
+                writer.writerow({k: json.dumps(v, ensure_ascii=False) if isinstance(v, (list, dict)) else v
+                                 for k, v in row.items()})
+    finally:
+        if output:
+            out.close()
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    searches = [("city", v) for v in args.city] + [("department", v) for v in args.department] + \
+               [("region", v) for v in args.region] + [("brand", v) for v in args.brand]
+    if not args.dealers and not searches:
+        build_parser().print_usage(sys.stderr)
+        print("Give dealer references or a --city/--department/--region/--brand.", file=sys.stderr)
+        return 2
+    try:
+        lc = LaCentralePros(token=args.token)
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    cards: List[Any] = []
+    refs: List[str] = list(args.dealers)
+    failures = 0
+    for kind, name in searches:
+        try:
+            found = list(lc.directory(kind, name, args.pages))
+        except ScrapeError as exc:
+            failures += 1
+            print(f"fail  {kind} {name}: {exc}", file=sys.stderr)
+            continue
+        print(f"{kind} {name}: {len(found)} dealers", file=sys.stderr)
+        cards.extend(found)
+        refs.extend(c.ref for c in found)
+    refs = list(dict.fromkeys(refs))
+    if args.limit:
+        refs = refs[: args.limit]
+        cards = [c for c in cards if c.ref in refs]
+
+    if not args.details and not args.stock:
+        rows, fields = [c.to_dict() for c in cards], CARD_FIELDS
+        if args.dealers:
+            for ref in args.dealers:
+                try:
+                    rows.append(lc.dealer(ref).to_dict())
+                    fields = DEALER_FIELDS
+                except (ScrapeError, ValueError) as exc:
+                    failures += 1
+                    print(f"fail  {ref}: {exc}", file=sys.stderr)
+    else:
+        rows, fields = [], VEHICLE_FIELDS if args.stock else DEALER_FIELDS
+        for ref in refs:
+            try:
+                if args.stock:
+                    dealer, vehicles = lc.dealer_with_stock(ref)
+                    rows.extend(v.to_dict() for v in vehicles)
+                    print(f"{ref} {dealer.name}: {len(vehicles)} vehicles", file=sys.stderr)
+                else:
+                    rows.append(lc.dealer(ref).to_dict())
+            except (ScrapeError, ValueError) as exc:
+                failures += 1
+                print(f"fail  {ref}: {exc}", file=sys.stderr)
+
+    _write(rows, fields, args.format, args.output)
+    print(f"saved {len(rows)} rows ({lc.credits_used} credits)", file=sys.stderr)
+    return 1 if failures and not rows else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lacentrale_pros_scraper-0.1.0/src/lacentrale_pros/client.py

@@ -0,0 +1,164 @@
+"""Fetch La Centrale's dealer directory and dealer pages through the Scrape.do API.
+
+lacentrale.fr sits behind DataDome: a plain ``requests.get`` from a script gets
+``403`` and a "Please enable JS and disable any ad blocker" page. A plain
+Scrape.do request (no extra parameters) returns the real server-rendered HTML.
+Each page costs 1 Scrape.do credit.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Iterator, List, Optional, Tuple
+
+import requests
+
+from .parser import (
+    Dealer,
+    DealerCard,
+    Vehicle,
+    dealer_ref,
+    dealer_url,
+    directory_url,
+    parse_dealer,
+    parse_directory,
+    parse_stock,
+    stock_url,
+)
+
+API_URL = "https://api.scrape.do/"
+TOKEN_ENV = "SCRAPEDO_TOKEN"
+BLOCK_MARKERS = ("Please enable JS and disable any ad blocker", "captcha-delivery.com")
+
+
+class ScrapeError(RuntimeError):
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class LaCentralePros:
+    """Read La Centrale's dealer directory, dealer profiles and every vehicle a dealer has in stock.
+
+    >>> lc = LaCentralePros(token="YOUR_SCRAPEDO_TOKEN")
+    >>> for card in lc.directory("city", "Lyon"):
+    ...     print(card.ref, card.name, card.ads)
+    >>> dealer, cars = lc.dealer_with_stock("C045088")
+    """
+
+    def __init__(self, token: Optional[str] = None, timeout: float = 60.0, retries: int = 2,
+                 session: Optional[requests.Session] = None):
+        self.token = token or os.environ.get(TOKEN_ENV, "")
+        if not self.token:
+            raise ValueError(f"A Scrape.do API token is required. Pass token=... or set {TOKEN_ENV}.")
+        self.timeout = timeout
+        self.retries = max(0, retries)
+        self.session = session or requests.Session()
+        self.requests_made = 0
+
+    def fetch(self, url: str) -> str:
+        params = {"token": self.token, "url": url}
+        last: Optional[ScrapeError] = None
+        for attempt in range(self.retries + 1):
+            try:
+                response = self.session.get(API_URL, params=params, timeout=self.timeout)
+            except requests.RequestException as exc:
+                last = ScrapeError(f"Request failed: {exc}")
+            else:
+                if response.status_code == 200:
+                    self.requests_made += 1
+                    if not any(marker in response.text for marker in BLOCK_MARKERS):
+                        return response.text
+                    last = ScrapeError(f"Blocked page for {url} (DataDome)", 200)
+                else:
+                    last = ScrapeError(f"Request for {url} failed with status {response.status_code}",
+                                       response.status_code)
+                    if response.status_code in (400, 401, 404, 410):
+                        break
+            if attempt < self.retries:
+                time.sleep(2 * (attempt + 1))
+        assert last is not None
+        raise last
+
+    # ---- directory -----------------------------------------------------------
+
+    def directory(self, kind: str, name: str, pages: int = 0) -> Iterator[DealerCard]:
+        """Dealers listed for a ``city``, ``department``, ``region`` or ``brand`` (20 per page).
+
+        ``pages=0`` follows every page.
+        """
+        seen = set()
+        page, last_page = 0, None
+        while True:
+            if last_page is not None and page >= last_page:
+                break
+            if pages and page >= pages:
+                break
+            result = parse_directory(self.fetch(directory_url(kind, name, page)))
+            last_page = result.pages
+            fresh = [c for c in result.dealers if c.ref not in seen]
+            if not fresh:
+                break
+            for card in fresh:
+                seen.add(card.ref)
+                yield card
+            page += 1
+
+    # ---- dealer --------------------------------------------------------------
+
+    def dealer(self, ref: str) -> Dealer:
+        ref = dealer_ref(ref)
+        dealer = parse_dealer(self.fetch(dealer_url(ref)), ref)
+        if dealer is None:
+            raise ScrapeError(f"No dealer data on {dealer_url(ref)}")
+        return dealer
+
+    def stock(self, ref: str, vertical: str = "car", pages: int = 0) -> Iterator[Vehicle]:
+        """Every vehicle a dealer lists (9 per page). ``pages=0`` follows every page."""
+        ref = dealer_ref(ref)
+        seen = set()
+        page, last_page = 1, None
+        while True:
+            if (last_page is not None and page > last_page) or (pages and page > pages):
+                break
+            result = parse_stock(self.fetch(stock_url(ref, page, vertical)), ref)
+            if result is None:
+                raise ScrapeError(f"No stock data on {stock_url(ref, page, vertical)}")
+            last_page = result.pages
+            fresh = [v for v in result.vehicles if v.reference not in seen]
+            if not fresh:
+                break
+            for vehicle in fresh:
+                seen.add(vehicle.reference)
+                yield vehicle
+            page += 1
+
+    def dealer_with_stock(self, ref: str, pages: int = 0) -> Tuple[Dealer, List[Vehicle]]:
+        """Dealer profile plus its car stock. The dealer page doubles as stock page 1."""
+        ref = dealer_ref(ref)
+        html = self.fetch(dealer_url(ref))
+        dealer = parse_dealer(html, ref)
+        if dealer is None:
+            raise ScrapeError(f"No dealer data on {dealer_url(ref)}")
+        first = parse_stock(html, ref)
+        vehicles: List[Vehicle] = list(first.vehicles) if first else []
+        seen = {v.reference for v in vehicles}
+        last_page = first.pages if first else 1
+        page = 2
+        while page <= last_page and not (pages and page > pages):
+            result = parse_stock(self.fetch(stock_url(ref, page)), ref)
+            if result is None:
+                break
+            fresh = [v for v in result.vehicles if v.reference not in seen]
+            if not fresh:
+                break
+            for v in fresh:
+                seen.add(v.reference)
+                vehicles.append(v)
+            page += 1
+        return dealer, vehicles
+
+    @property
+    def credits_used(self) -> int:
+        return self.requests_made