scrapely-python 0.1.38__tar.gz → 0.1.40__tar.gz

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.40] - 2026-10-28
+
+0.1.39 was never published to PyPI. This release includes the 0.1.39 change below, plus these fixes to `scrapely.http` from the fingerprint test on staging (2026-10-27):
+
+- **Accept-Language matches the exit IP.** Before, a client without a proxy country sent `en-US` on every identity: 8 of 20 residential sessions did so from Brazil, France, Spain, Mexico or Taiwan.
+  - **Residential platform proxy without a country:** each identity now picks an exit country, weighted like real web traffic, asks the proxy for it and sends that country's language.
+  - **Proxy with a country:** each identity gets one of the language setups common there (for example `de-DE,de;q=0.9` or `de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7`).
+  - **Several `locales`:** each identity uses one of them, not all of them in one header. With a residential proxy without a country, the exit follows the locale's country.
+  - **Unchanged:** no proxy, your own proxy URLs and the `DATACENTER` group (US exits only) keep `en-US,en;q=0.9`.
+  - `ProxyConfiguration.new_url()` takes an optional `country_code` for one URL (residential platform proxy without a country only). Sessions expose `accept_language` and `country`.
+- **No more `400` on `https://host?q`.** A URL with a query and no path is sent with the path `/`. wreq 0.13 sent `:path: ?q` over HTTP/2, which Cloudflare and nginx reject.
+- **Chrome 155 and 156.** The default profiles are Chrome 156, 155, 154 and 153, weighted 55 / 30 / 10 / 5. 155 and 156 use the Chrome 154 TLS and HTTP/2 profile, which is the same as real Chrome 156's, with their own User-Agent, `sec-ch-ua` and Accept (with `image/jxl`, which real 155 and 156 send).
+- **Firefox 153 ESR.** Added Firefox 153 (ESR) next to 152. Both match real Firefox 153.6 ESR and 152 builds byte for byte in the TLS ClientHello and HTTP/2 settings, and are now marked verified.
+
+## [0.1.39] - 2026-10-27 (not published)
+
+- A key-value store record write (`Actor.set_value`, `KeyValueStore.set_value`) is no longer lost to one failed answer. Each write now sends an `Idempotency-Key`, and when its answer is lost (a `502`/`504` page from the edge or load balancer, a dropped connection, a timeout) it is sent again with the same key; the API applies and counts it once. Before, the write was never re-sent, so one such page on the final `OUTPUT` write failed the whole run. An API that answers a keyed write without `X-Scrapely-Idempotency` (an older server) gets no re-sends, as before.
+
 ## [0.1.38] - 2026-10-27
 
 0.1.37 was never published to PyPI. This release includes everything listed under 0.1.37 below, plus these changes to `scrapely.http`:

{scrapely_python-0.1.38/src/scrapely_python.egg-info → scrapely_python-0.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrapely-python
-Version: 0.1.38
+Version: 0.1.40
 Summary: Scrapely Python SDK - A toolkit for building Actors on the Scrapely platform
 Author-email: Scrapely <hello@scrape.ly>
 License-Expression: MIT AND Apache-2.0

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scrapely-python"
-version = "0.1.38"
+version = "0.1.40"
 description = "Scrapely Python SDK - A toolkit for building Actors on the Scrapely platform"
 readme = "README.md"
 license = "MIT AND Apache-2.0"

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/__init__.py

@@ -227,7 +227,7 @@ if TYPE_CHECKING:  # Static analysers and IDEs see the lazy names as plain impor
         set_api_storage,
     )
 
-__version__ = '0.1.38'
+__version__ = '0.1.40'
 __all__ = [
     # Core
     'Actor',

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/charging.py

@@ -308,7 +308,8 @@ class ChargingManager:
 
     def _remaining_budget_usd(self) -> Decimal:
         """maxTotalChargeUsd minus this SDK's charges and the platform's other run spend."""
-        assert self._max_total_charge_usd is not None
+        if self._max_total_charge_usd is None:
+            raise RuntimeError('maxTotalChargeUsd is not set')
         return self._max_total_charge_usd - self._total_charged_usd - self._platform_other_usd
 
     def _sync_platform_budget(self) -> None:

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/events/event_manager.py

@@ -122,13 +122,15 @@ class ScrapelyEventManager(CrawleeEventManager):
         # Run tasks but don't await them
         ws_url = self._configuration.get('actor_events_ws_url')
         if ws_url:
-            # Append authentication parameters to the WebSocket URL
-            # This matches the Node SDK behavior in events-client.ts
+            # Authenticate with the token in a header and the runId in the URL (URLs end up in access
+            # logs). This matches the Node SDK behavior in events-client.ts
             token = self._configuration.get('token')
             run_id = self._configuration.get('actor_run_id')
+            headers: dict[str, str] = {}
             if token and run_id:
                 separator = '&' if '?' in ws_url else '?'
-                ws_url = f"{ws_url}{separator}{urlencode({'token': token, 'runId': run_id})}"
+                ws_url = f"{ws_url}{separator}{urlencode({'runId': run_id})}"
+                headers['Authorization'] = f'Bearer {token}'
                 logger.debug(f'Connecting to platform events websocket with runId={run_id}')
             else:
                 logger.warning(
@@ -139,7 +141,7 @@ class ScrapelyEventManager(CrawleeEventManager):
             # Connect in the background without blocking init, matching the Node SDK: a slow or failed
             # connection is retried and must not crash the Actor.
             self._process_platform_messages_task = asyncio.create_task(
-                self._process_platform_messages(ws_url)
+                self._process_platform_messages(ws_url, headers)
             )
         else:
             logger.debug(
@@ -170,7 +172,7 @@ class ScrapelyEventManager(CrawleeEventManager):
 
         await super().__aexit__(exc_type, exc_value, exc_traceback)
 
-    async def _process_platform_messages(self, ws_url: str) -> None:
+    async def _process_platform_messages(self, ws_url: str, headers: Optional[dict[str, str]] = None) -> None:
         """Process messages from the platform WebSocket with reconnect logic."""
         try:
             import websockets.asyncio.client
@@ -189,7 +191,7 @@ class ScrapelyEventManager(CrawleeEventManager):
         try:
             # Used as an async iterator, `connect` reconnects with exponential backoff on failed connection attempts,
             # including the first one (timeouts, network errors and 5xx responses are retried).
-            async for websocket in websockets.asyncio.client.connect(ws_url):
+            async for websocket in websockets.asyncio.client.connect(ws_url, additional_headers=headers or None):
                 self._platform_events_websocket = websocket
                 if self._connected_to_platform_websocket and not self._connected_to_platform_websocket.done():
                     self._connected_to_platform_websocket.set_result(True)

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/http/_client.py

@@ -11,7 +11,7 @@ from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple
 from urllib.parse import urlencode, urlsplit, urlunsplit
 
 from ._detect import detect_block, parse_retry_after
-from ._headers import accept_language_for, encode_body, prepare
+from ._headers import accept_language_for, country_for_locale, encode_body, pick_accept_language, pick_country, prepare
 from ._options import FingerprintOptions
 from ._policy import BackoffPolicy, HostState, Identity, RetryPolicy, country_from_proxy, decide, new_session_id
 from ._profiles import BrowserProfile, impersonate_to_options, load_table, pick, select_candidates
@@ -58,6 +58,29 @@ def _with_params(url: str, params: Any) -> str:
     return urlunsplit((parts.scheme, parts.netloc, parts.path, joined, parts.fragment))
 
 
+def _normalize_url(url: str) -> str:
+    """``https://host?q`` → ``https://host/?q``: an empty path is sent as ``/``, as browsers do.
+
+    wreq 0.13 sends ``:path: ?q`` over HTTP/2 for such URLs, and servers
+    (Cloudflare, nginx) answer 400 Bad Request.
+    """
+    parts = urlsplit(url)
+    if parts.scheme.lower() in ('http', 'https') and parts.netloc and not parts.path:
+        return urlunsplit((parts.scheme, parts.netloc, '/', parts.query, parts.fragment))
+    return url
+
+
+def _can_pick_country(proxy_configuration: Any) -> bool:
+    """True for a platform proxy that lets each identity choose its exit country."""
+    check = getattr(proxy_configuration, '_can_pick_country', None)
+    if not callable(check):
+        return False
+    try:
+        return bool(check())
+    except Exception:  # noqa: BLE001 - a foreign proxy configuration: keep its own behaviour
+        return False
+
+
 def _rotations(max_rotations: Optional[int], max_retries: Optional[int], default: Optional[int]) -> Optional[int]:
     """``max_rotations`` wins; ``max_retries`` is its older name."""
     if max_rotations is not None:
@@ -198,7 +221,12 @@ class _Base:
         # Only a proxy configuration gives each identity its own exit IP.
         self.rotates_ip = proxy_configuration is not None
         country = country_from_proxy(proxy_configuration if proxy_configuration is not None else self.fixed_proxy)
+        self.proxy_country = country
+        # Default Accept-Language of this client (identities draw their own, see _identity_geo).
         self.accept_language = accept_language_for(country, self.options.locales)
+        # A platform proxy without a country: every identity picks its exit
+        # country and sends the matching Accept-Language.
+        self.picks_country = country is None and proxy_configuration is not None and _can_pick_country(proxy_configuration)
         if backoff is None and polite:
             backoff = BackoffPolicy()
         self.policy = RetryPolicy(max_rotations=_rotations(max_rotations, max_retries, 6), backoff=backoff)
@@ -244,14 +272,44 @@ class _Base:
     def _pick_profile(self, avoid: Optional[BrowserProfile]) -> BrowserProfile:
         return pick(self.candidates, self.rng, avoid)
 
-    def _new_identity(self, client: Any, profile: BrowserProfile, session_id: str, proxy_url: Optional[str]) -> Identity:
+    def _identity_geo(self) -> Tuple[Optional[str], str]:
+        """(exit country to request from the proxy or None, Accept-Language) for a new identity.
+
+        - ``locales``: one of them per identity, as a browser has one language
+          setup; with a country-pickable proxy the exit is that locale's country.
+        - proxy with a country: a language setup common in that country.
+        - platform proxy without a country: a country weighted like real
+          traffic, used for both the proxy session and the language.
+        - otherwise (no proxy, own proxy URLs, datacenter): the client default.
+        """
+        locales = self.options.locales
+        if locales:
+            loc = locales[0] if len(locales) == 1 else self.rng.choice(locales)
+            return (country_for_locale(loc) if self.picks_country else None), accept_language_for(None, [loc])
+        if self.proxy_country:
+            return None, pick_accept_language(self.proxy_country, self.rng)
+        if self.picks_country:
+            cc = pick_country(self.rng)
+            return cc, pick_accept_language(cc, self.rng)
+        return None, self.accept_language
+
+    def _new_identity(
+        self,
+        client: Any,
+        profile: BrowserProfile,
+        session_id: str,
+        proxy_url: Optional[str],
+        accept_language: Optional[str] = None,
+        country: Optional[str] = None,
+    ) -> Identity:
         ident = Identity(
             session_id=session_id,
             profile=profile,
             proxy_url=proxy_url,
             client=client,
-            accept_language=self.accept_language,
+            accept_language=accept_language or self.accept_language,
             created_at=self._clock(),
+            country=country or self.proxy_country,
         )
         for name, value, domain, path in self._caller_cookies._cookies:
             self._apply_cookie(ident, name, value, domain, path)
@@ -428,18 +486,22 @@ class AsyncClient(_Base):
             self._cond = asyncio.Condition()
         return self._cond
 
-    async def _proxy_url(self, session_id: str) -> Optional[str]:
+    async def _proxy_url(self, session_id: str, country: Optional[str] = None) -> Optional[str]:
         if self.proxy_configuration is not None:
-            url = await self.proxy_configuration.new_url(session_id=session_id)
+            if country:
+                url = await self.proxy_configuration.new_url(session_id=session_id, country_code=country)
+            else:
+                url = await self.proxy_configuration.new_url(session_id=session_id)
             return str(url) if url else None
         return self.fixed_proxy
 
     async def _open(self, avoid: Optional[BrowserProfile]) -> Identity:
         profile = self._pick_profile(avoid)
         sid = new_session_id(self.rng)
-        proxy_url = await self._proxy_url(sid)
+        country, al = self._identity_geo()
+        proxy_url = await self._proxy_url(sid, country)
         client = self.transport.new_client(profile, proxy_url, self.timeout, self.verify, self.http1_only)
-        return self._new_identity(client, profile, sid, proxy_url)
+        return self._new_identity(client, profile, sid, proxy_url, al, country)
 
     async def _retire(self, ident: Identity, force: bool = False) -> None:
         """Retire an identity; its client closes once no request uses it any more."""
@@ -536,7 +598,7 @@ class AsyncClient(_Base):
     ) -> Response:
         """Send a request; a block or error rotates to a fresh identity at once. Returns the last response."""
         method = method.upper()
-        url = _with_params(url, params)
+        url = _normalize_url(_with_params(url, params))
         body, ctype = encode_body(data, json, content)
         host, hs = self._host(url)
         started = self._clock()
@@ -684,6 +746,16 @@ class AsyncHttpSession:
     def session_id(self) -> Optional[str]:
         return self._pin.identity.session_id if self._pin.identity else None
 
+    @property
+    def accept_language(self) -> Optional[str]:
+        """Accept-Language of the current identity."""
+        return self._pin.identity.accept_language if self._pin.identity else None
+
+    @property
+    def country(self) -> Optional[str]:
+        """Exit country the current identity asked the proxy for (None when the proxy chooses)."""
+        return self._pin.identity.country if self._pin.identity else None
+
     async def request(self, method: str, url: str, **kwargs: Any) -> Response:
         return await self._client.request(method, url, _pin=self._pin, **kwargs)
 
@@ -755,18 +827,18 @@ class Client(_Base):
     def _make_transport(self, backend: str) -> Any:
         return WreqSyncTransport() if backend == 'wreq' else CurlSyncTransport(self.table.curl_cffi_targets)
 
-    def _proxy_url(self, session_id: str) -> Optional[str]:
+    def _proxy_url(self, session_id: str, country: Optional[str] = None) -> Optional[str]:
         pc = self.proxy_configuration
         if pc is None:
             return self.fixed_proxy
         sync = getattr(pc, '_new_url_sync', None)
         if sync is not None and not getattr(pc, '_new_url_function', None):
-            url = sync(session_id)
+            url = sync(session_id, country_code=country) if country else sync(session_id)
         else:
             try:
                 asyncio.get_running_loop()
             except RuntimeError:
-                url = asyncio.run(pc.new_url(session_id=session_id))
+                url = asyncio.run(pc.new_url(session_id=session_id, country_code=country) if country else pc.new_url(session_id=session_id))
             else:
                 raise RuntimeError('scrapely.http.Client: use AsyncClient inside async code (this proxy configuration needs await)')
         return str(url) if url else None
@@ -775,10 +847,11 @@ class Client(_Base):
         profile = self._pick_profile(avoid)
         with self._lock:
             sid = new_session_id(self.rng)
-        proxy_url = self._proxy_url(sid)
+            country, al = self._identity_geo()
+        proxy_url = self._proxy_url(sid, country)
         client = self.transport.new_client(profile, proxy_url, self.timeout, self.verify, self.http1_only)
         with self._lock:
-            return self._new_identity(client, profile, sid, proxy_url)
+            return self._new_identity(client, profile, sid, proxy_url, al, country)
 
     def _retire(self, ident: Identity, force: bool = False) -> None:
         """Retire an identity; its client closes once no request uses it any more."""
@@ -885,7 +958,7 @@ class Client(_Base):
     ) -> Response:
         """Send a request; a block or error rotates to a fresh identity at once. Returns the last response."""
         method = method.upper()
-        url = _with_params(url, params)
+        url = _normalize_url(_with_params(url, params))
         body, ctype = encode_body(data, json, content)
         with self._lock:
             host, hs = self._host(url)
@@ -1030,6 +1103,16 @@ class HttpSession:
     def session_id(self) -> Optional[str]:
         return self._pin.identity.session_id if self._pin.identity else None
 
+    @property
+    def accept_language(self) -> Optional[str]:
+        """Accept-Language of the current identity."""
+        return self._pin.identity.accept_language if self._pin.identity else None
+
+    @property
+    def country(self) -> Optional[str]:
+        """Exit country the current identity asked the proxy for (None when the proxy chooses)."""
+        return self._pin.identity.country if self._pin.identity else None
+
     def request(self, method: str, url: str, **kwargs: Any) -> Response:
         return self._client.request(method, url, _pin=self._pin, **kwargs)
 

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/http/_headers.py

@@ -107,6 +107,74 @@ def accept_language_for(country_code: Optional[str] = None, locales: Sequence[st
     return f'{lang}-{cc},{lang};q=0.9,en;q=0.8'
 
 
+# ─── per-identity geo: exit country + matching Accept-Language ──────────────
+
+# Exit countries for identities whose proxy has no country set, weighted like
+# desktop web traffic (rough shares by country; only countries the residential
+# pool serves well). The proxy session and Accept-Language use the same draw,
+# so the language always matches the exit IP.
+TRAFFIC_COUNTRIES: Tuple[Tuple[str, float], ...] = (
+    ('US', 32.0), ('GB', 7.0), ('DE', 7.0), ('FR', 5.0), ('CA', 4.0), ('BR', 4.0), ('IN', 3.0),
+    ('IT', 3.5), ('ES', 3.5), ('NL', 2.5), ('PL', 2.5), ('MX', 2.5), ('AU', 2.5), ('JP', 2.0),
+    ('TR', 1.5), ('SE', 1.0), ('BE', 1.0), ('AT', 1.0), ('CH', 1.0), ('PT', 1.0), ('AR', 1.0),
+    ('CO', 1.0), ('RO', 1.0), ('CZ', 1.0), ('ID', 1.0),
+)
+
+# Main country for a bare language (``locales=["de"]``): where its speakers mostly are.
+_LANG_COUNTRY: Dict[str, str] = {
+    'en': 'US', 'de': 'DE', 'fr': 'FR', 'es': 'ES', 'it': 'IT', 'pt': 'BR', 'nl': 'NL', 'pl': 'PL',
+    'cs': 'CZ', 'sk': 'SK', 'hu': 'HU', 'ro': 'RO', 'bg': 'BG', 'el': 'GR', 'tr': 'TR', 'ru': 'RU',
+    'uk': 'UA', 'sv': 'SE', 'nb': 'NO', 'no': 'NO', 'da': 'DK', 'fi': 'FI', 'ja': 'JP', 'ko': 'KR',
+    'zh': 'TW', 'vi': 'VN', 'th': 'TH', 'id': 'ID', 'ms': 'MY', 'he': 'IL', 'ar': 'SA', 'hi': 'IN',
+}
+
+
+def pick_country(rng: Any) -> str:
+    """A country drawn from ``TRAFFIC_COUNTRIES``."""
+    names = [c for c, _ in TRAFFIC_COUNTRIES]
+    return rng.choices(names, weights=[w for _, w in TRAFFIC_COUNTRIES], k=1)[0]
+
+
+def country_for_locale(locale: str) -> Optional[str]:
+    """The country a locale points at: ``de-AT`` → AT, ``de`` → DE, ``en`` → US."""
+    parts = str(locale).strip().replace('_', '-').split('-')
+    for p in parts[1:]:
+        if len(p) == 2 and p.isalpha():
+            return p.upper()
+    return _LANG_COUNTRY.get(parts[0].lower())
+
+
+def accept_language_variants(country_code: Optional[str]) -> List[Tuple[str, float]]:
+    """Accept-Language values real Chrome users in a country send, with rough weights.
+
+    All variants put the country's language first (``de-DE,de;q=0.9`` with or
+    without English after it), so any of them matches an exit IP in that
+    country. Chrome builds the header from the user's language list: the
+    regional tag, its base language, then further languages 0.1 lower each.
+    """
+    cc = (country_code or '').strip().upper()
+    if cc == 'UK':
+        cc = 'GB'
+    if not cc or cc == 'US':
+        return [(DEFAULT_ACCEPT_LANGUAGE, 0.92), ('en-US,en;q=0.9,es;q=0.8', 0.08)]
+    if cc in _ENGLISH_COUNTRIES:
+        return [(f'en-{cc},en;q=0.9', 0.5), (f'en-{cc},en-US;q=0.9,en;q=0.8', 0.2), (DEFAULT_ACCEPT_LANGUAGE, 0.3)]
+    lang = _COUNTRY_LANG.get(cc)
+    if not lang:
+        return [(DEFAULT_ACCEPT_LANGUAGE, 1.0)]
+    return [
+        (f'{lang}-{cc},{lang};q=0.9,en-US;q=0.8,en;q=0.7', 0.45),
+        (f'{lang}-{cc},{lang};q=0.9', 0.30),
+        (f'{lang}-{cc},{lang};q=0.9,en;q=0.8', 0.25),
+    ]
+
+
+def pick_accept_language(country_code: Optional[str], rng: Any) -> str:
+    """One Accept-Language for an identity whose exit is in ``country_code``."""
+    variants = accept_language_variants(country_code)
+    return rng.choices([v for v, _ in variants], weights=[w for _, w in variants], k=1)[0]
+
+
 # ─── sec-fetch-site ─────────────────────────────────────────────────────────
 
 _TWO_LEVEL_SUFFIXES = frozenset(
@@ -257,6 +325,10 @@ def prepare(
     if kind == 'navigate':
         # Backend default headers; we only adjust values that depend on the request.
         prep.default_headers = True
+        for h in profile.header_overrides:
+            # Newer version on the backend's TLS profile: its own UA, client hints and Accept.
+            if h in native:
+                out[h] = native[h]
         if al != native.get('accept-language'):
             out['accept-language'] = al
         site = fetch_site(referer, url)

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/http/_options.py

@@ -99,16 +99,16 @@ class FingerprintOptions:
     """Which browsers, operating systems, devices and locales a client may present.
 
     All fields are optional. The defaults are desktop Chrome on Windows, macOS
-    and Linux (weighted toward real traffic), with Accept-Language taken from
-    the proxy country.
+    and Linux (weighted toward real traffic), with Accept-Language matching
+    each identity's exit country.
 
     Attributes:
         browsers: ``"chrome"``, ``"edge"``, ``"firefox"``, ``"safari"``, or
             ``{"name": "chrome", "min_version": 150}``.
         operating_systems: ``"windows"``, ``"macos"``, ``"linux"``, ``"android"``, ``"ios"``.
         devices: ``"desktop"`` (default) and/or ``"mobile"``.
-        locales: e.g. ``["de-DE"]``; the first is the primary language. Wins over
-            the proxy country.
+        locales: e.g. ``["de-DE"]``. Each identity uses one of them, as a
+            browser has one language setup. Wins over the proxy country.
         strict: only profiles whose fingerprint was verified against the real
             browser, and fail instead of relaxing options that match nothing.
         http_version: ``"2"`` (default) or ``"1"`` to force HTTP/1.1.

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/http/_policy.py

@@ -198,6 +198,7 @@ class Identity:
     retired: bool = False
     in_flight: int = 0  # requests using it right now (a session's identity is shared)
     closed: bool = False
+    country: Optional[str] = None  # exit country requested from the proxy, when known
 
     def expired(self, now: float, max_usage: int, max_age: float) -> bool:
         if self.retired:

{scrapely_python-0.1.38 → scrapely_python-0.1.40}/src/scrapely/http/_profiles.py

@@ -39,6 +39,10 @@ class BrowserProfile:
     weight: float
     headers: Dict[str, str] = field(default_factory=dict, compare=False, hash=False)
     note: str = field(default='', compare=False, hash=False)
+    # Headers whose value differs from the backend profile's own default
+    # (a newer browser version on the same TLS/HTTP2 profile: User-Agent,
+    # client hints, Accept). They are sent explicitly on every request.
+    header_overrides: Tuple[str, ...] = field(default=(), compare=False, hash=False)
 
     @property
     def label(self) -> str:
@@ -83,6 +87,7 @@ def _parse_table(raw: Dict[str, Any]) -> ProfileTable:
                 weight=float(row.get('weight') or 0.0),
                 headers={k.lower(): v for k, v in (row.get('headers') or {}).items()},
                 note=row.get('note') or '',
+                header_overrides=tuple(h.lower() for h in (row.get('header_overrides') or ())),
             )
         )
     return ProfileTable(