polite-http 0.1.0__py3-none-any.whl

polite_http/__init__.py

@@ -0,0 +1,49 @@
+# Copyright 2026 polite-http contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""polite-http — a courteous, dependency-free HTTP client.
+
+Rate limiting, automatic retries, exponential backoff with jitter,
+`Retry-After` support, and proactive `X-Throttling-Control` backpressure —
+built entirely on the Python standard library.
+"""
+
+from polite_http.http_client import (
+    DEFAULT_BACKOFF_BASE_SECS,
+    DEFAULT_BACKOFF_MAX_SECS,
+    DEFAULT_JITTER_SECS,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT_SECS,
+    RETRYABLE_STATUS_CODES,
+    USER_AGENT_ENV_VAR,
+    HttpClient,
+    HttpError,
+    HttpResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HttpClient",
+    "HttpError",
+    "HttpResponse",
+    "DEFAULT_BACKOFF_BASE_SECS",
+    "DEFAULT_BACKOFF_MAX_SECS",
+    "DEFAULT_JITTER_SECS",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_TIMEOUT_SECS",
+    "RETRYABLE_STATUS_CODES",
+    "USER_AGENT_ENV_VAR",
+    "__version__",
+]

polite_http/http_client.py

@@ -0,0 +1,924 @@
+# Copyright 2026 Google LLC
+# Copyright 2026 polite-http contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# This file is derived from `http_client.py` in google-deepmind/science-skills
+# (https://github.com/google-deepmind/science-skills). See the NOTICE file in
+# the project root for a description of the modifications.
+
+"""Unified HTTP client with rate limiting, retries, and backoff.
+
+Provides `HttpClient` — a single entry-point that combines:
+
+* **Per-host rate limiting** via `_RateLimiter` (cross-process file-lock).
+* **Automatic retries** on transient errors (HTTP 429, 5xx).
+* **Exponential backoff** with optional *jitter*.
+* **Retry-After header** support (server-directed backoff).
+* **X-Throttling-Control** proactive backpressure (PubChem / NCBI).
+* **Configurable timeouts** per request.
+
+Transport is `urllib.request` (stdlib) — no third-party dependencies.
+
+Typical usage:
+
+```python
+from polite_http import HttpClient
+
+# Scoped to a specific base URL.
+api_client = HttpClient(
+    "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/",
+    qps=3,
+)
+
+# Simple GET with relative path (returns parsed JSON).
+data = api_client.fetch_json("esummary.fcgi?db=pubmed&id=123456")
+
+# POST with a JSON body.
+data = api_client.fetch_json(
+    "esearch.fcgi",
+    method="POST",
+    json_body={"db": "pubmed", "term": "cancer"},
+)
+
+# Raw bytes (e.g. file / PDF download).
+pdf = api_client.fetch_bytes(
+    "efetch.fcgi?db=pubmed&id=123456&rettype=abstract",
+    timeout=60,
+)
+```
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import email.utils
+import gzip
+import http.client
+import json
+import logging
+import os
+import random
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Iterator
+from typing import Any
+
+# Cross-process exclusive file locking, implemented on the standard library
+# only.  POSIX uses ``fcntl.flock``; Windows uses ``msvcrt.locking`` (byte-range
+# lock).  If neither is available (rare sandboxed runtimes), the limiter falls
+# back to a best-effort in-process timer.
+if sys.platform == "win32":  # pragma: no cover - exercised only on Windows
+    import msvcrt
+
+    def _lock(f) -> None:
+        # Lock one byte at offset 0 as a whole-file mutex.  ``LK_LOCK`` blocks,
+        # retrying for ~10s per call before raising, so loop until acquired.
+        f.seek(0)
+        while True:
+            try:
+                msvcrt.locking(f.fileno(), msvcrt.LK_LOCK, 1)
+                return
+            except OSError:
+                continue
+
+    def _unlock(f) -> None:
+        f.seek(0)
+        msvcrt.locking(f.fileno(), msvcrt.LK_UNLCK, 1)
+
+    _HAS_FILE_LOCK = True
+else:
+    try:
+        import fcntl
+
+        def _lock(f) -> None:
+            fcntl.flock(f, fcntl.LOCK_EX)
+
+        def _unlock(f) -> None:
+            fcntl.flock(f, fcntl.LOCK_UN)
+
+        _HAS_FILE_LOCK = True
+    except ImportError:  # pragma: no cover - rare sandboxed runtimes
+        _HAS_FILE_LOCK = False
+
+__all__ = [
+    "HttpClient",
+    "HttpError",
+    "HttpResponse",
+    "DEFAULT_BACKOFF_BASE_SECS",
+    "DEFAULT_BACKOFF_MAX_SECS",
+    "DEFAULT_JITTER_SECS",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_TIMEOUT_SECS",
+    "RETRYABLE_STATUS_CODES",
+    "USER_AGENT_ENV_VAR",
+]
+
+RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+DEFAULT_TIMEOUT_SECS: float = 60.0
+DEFAULT_MAX_RETRIES: int = 7
+DEFAULT_BACKOFF_BASE_SECS: float = 3.0
+DEFAULT_BACKOFF_MAX_SECS: float = 180.0
+DEFAULT_JITTER_SECS: float = 0.5
+DEFAULT_CHARSET: str = "utf-8"
+PROJECT_NAME: str = "polite-http"
+USER_AGENT_ENV_VAR: str = "POLITE_HTTP_USER_AGENT"
+
+# Regex for parsing X-Throttling-Control status entries.
+# Matches e.g. "Request Count status: Red (82%)".
+_THROTTLE_STATUS_RE = re.compile(
+    r"(\w[\w ]*?) status:\s*(Green|Yellow|Red|Black)\s*\((\d+)%\)"
+)
+
+# Backpressure delays (seconds) keyed by throttle colour.
+_THROTTLE_BACKPRESSURE: dict[str, float] = {
+    "Green": 0.0,
+    "Yellow": 1.0,
+    "Red": 5.0,
+    "Black": 30.0,
+}
+
+
+class _RateLimiter:
+    """Enforces a minimum interval between requests.
+
+    Uses a shared lock file so multiple processes respect the same rate limit
+    (the lock file path is derived from the hostname, e.g.
+    ``/tmp/polite-http-ncbi.nlm.nih.gov.lock``).  The cross-process lock works
+    on POSIX (``fcntl``) and Windows (``msvcrt``).  On the rare platform that
+    provides neither, it falls back to a best-effort, in-process timer.
+
+    The shared timestamp is `time.monotonic()`, whose clock is system-wide on
+    every supported platform, so the value is comparable across processes on
+    the same host.
+
+    Example:
+      limiter = _RateLimiter('ncbi.nlm.nih.gov', qps=10)
+    """
+
+    def __init__(self, hostname: str, qps: float):
+        """Initialize rate limiter.
+
+        Args:
+          hostname: Hostname of the API.
+          qps: Maximum queries per second.
+        """
+        if qps <= 0:
+            raise ValueError(f"qps must be positive, got {qps!r}")
+        self._min_interval = 1.0 / qps
+        self._lock_file = os.path.join(_lock_dir(), f"{PROJECT_NAME}-{hostname}.lock")
+        # Used only when no cross-process file lock is available.
+        self._last_ts = 0.0
+
+    def wait(self, min_sleep: float = 0.0):
+        """Block until the next request is allowed.
+
+        Args:
+          min_sleep: Additional minimum sleep in seconds.  The actual delay is
+            `max(rate_limit_gap, min_sleep)`, which lets callers fold retry back-off
+            into the same call.
+        """
+        if not _HAS_FILE_LOCK:  # pragma: no cover - rare sandboxed runtimes
+            now = time.monotonic()
+            gap = self._min_interval - (now - self._last_ts)
+            delay = max(gap, min_sleep)
+            if delay > 0:
+                time.sleep(delay)
+            self._last_ts = time.monotonic()
+            return
+
+        # Open read/write in binary mode (no append semantics) so the same
+        # seek/truncate/byte-lock logic behaves identically on POSIX and
+        # Windows.  ``O_CREAT`` makes the first caller create the lock file.
+        fd = os.open(self._lock_file, os.O_RDWR | os.O_CREAT, 0o644)
+        with os.fdopen(fd, "r+b") as f:
+            _lock(f)
+            try:
+                f.seek(0)
+                content = f.read().strip()
+                last_ts = float(content) if content else 0.0
+                now = time.monotonic()
+                gap = self._min_interval - (now - last_ts)
+                delay = max(gap, min_sleep)
+                if delay > 0:
+                    time.sleep(delay)
+                f.seek(0)
+                f.truncate()
+                f.write(str(time.monotonic()).encode("ascii"))
+                f.flush()
+            finally:
+                _unlock(f)
+
+
+def _lock_dir() -> str:
+    """Return the directory used for cross-process rate-limit lock files."""
+    return os.environ.get("POLITE_HTTP_LOCK_DIR") or _default_tmp_dir()
+
+
+def _default_tmp_dir() -> str:
+    import tempfile
+
+    return tempfile.gettempdir()
+
+
+def _maybe_decompress(
+    response: http.client.HTTPResponse,
+) -> http.client.HTTPResponse | gzip.GzipFile:
+    """Wrap the response in a gzip decompressor if Content-Encoding says so.
+
+    Args:
+      response: The response to wrap. Must support .read() and .headers.
+
+    Returns:
+      A `GzipFile` wrapper if the response is gzip-encoded, otherwise the
+      original response unchanged.
+    """
+    encoding = response.headers.get("Content-Encoding", "").lower()
+    if encoding in ("gzip", "x-gzip"):
+        return gzip.GzipFile(fileobj=response)
+    return response
+
+
+class HttpError(Exception):
+    """Raised when an HTTP request fails with a non-retryable or exhausted error.
+
+    Attributes:
+      status_code: HTTP status code (`None` for network-level failures).
+      body: Raw error response body bytes, if available.
+      url: The URL that was requested.
+    """
+
+    MAX_BODY_SUMMARY_LEN = 500
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: bytes | None = None,
+        url: str | None = None,
+    ):
+        # Append server body to message to help callers debug any errors.
+        if summary := self._summarize_body(body):
+            message = f"{message}\nServer body: {summary}"
+
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.url = url
+
+    def json(self) -> Any:
+        """Attempt to parse the error body as JSON."""
+        # Let the JSON decode fail with JSONDecodeError if the body is empty.
+        body = self.body or b""
+        return json.loads(body.decode("utf-8"))
+
+    @classmethod
+    def _summarize_body(cls, body: bytes | None) -> str | None:
+        """Return a short summary of the error body if available."""
+        if not body:
+            return None
+        if body.startswith(b"\x1f\x8b"):  # Gzip encoding.
+            try:
+                body = gzip.decompress(body)
+            except gzip.BadGzipFile:
+                return None
+
+        decoded = body.decode("utf-8", errors="replace").strip()
+        if len(decoded) > cls.MAX_BODY_SUMMARY_LEN:
+            return decoded[: cls.MAX_BODY_SUMMARY_LEN] + "..."
+        return decoded
+
+
+class HttpResponse:
+    """Lightweight wrapper around an HTTP response.
+
+    Attributes:
+      data: Raw response body bytes (decompressed if the server sent
+        `Content-Encoding: gzip`).
+      status_code: HTTP status code.
+      headers: Response headers as a dict.
+      url: The final URL after any redirects.
+      encoding: Character encoding parsed from the `Content-Type` header.  Falls
+        back to `"utf-8"` when absent.
+    """
+
+    __slots__ = ("data", "status_code", "headers", "url", "encoding")
+
+    def __init__(
+        self,
+        data: bytes,
+        status_code: int,
+        headers: dict[str, str],
+        url: str,
+        encoding: str | None = None,
+    ):
+        self.data = data
+        self.status_code = status_code
+        self.headers = headers
+        self.url = url
+        self.encoding = encoding or "utf-8"
+
+    def json(self) -> Any:
+        """Parse the response body as JSON."""
+        return json.loads(self.data.decode(self.encoding))
+
+    @property
+    def text(self) -> str:
+        """Decode the response body using the detected charset."""
+        return self.data.decode(self.encoding)
+
+    def __repr__(self) -> str:
+        return (
+            f"HttpResponse(status={self.status_code}, "
+            f"url={self.url!r}, size={len(self.data)})"
+        )
+
+
+def _parse_retry_after(headers) -> float | None:
+    """Extract `Retry-After` value from HTTP response headers.
+
+    Handles both formats defined in RFC 7231 §7.1.3:
+
+    * **delta-seconds** — `Retry-After: 120`
+    * **HTTP-date** — `Retry-After: Mon, 31 Mar 2026 15:10:00 GMT`
+
+    Args:
+      headers: Response headers (dict-like or `http.client.HTTPMessage`).
+
+    Returns:
+      Delay in seconds, or `None` if the header is absent or not parseable.
+    """
+    value = headers.get("Retry-After")
+    if value is None:
+        return None
+
+    try:
+        return float(value)
+    except ValueError:
+        pass
+
+    try:
+        retry_dt = email.utils.parsedate_to_datetime(value)
+        delta = (
+            retry_dt - datetime.datetime.now(datetime.timezone.utc)
+        ).total_seconds()
+        return max(0.0, delta)
+    except (TypeError, ValueError, OverflowError):
+        logging.warning("Failed to parse Retry-After header value: %r", value)
+        return None
+
+
+def _parse_throttle_control(headers) -> float:
+    """Parse `X-Throttling-Control` header for proactive backpressure.
+
+    The header (used by PubChem / NCBI) reports real-time usage across three
+    dimensions:
+
+        X-Throttling-Control: Request Count status: Green (12%),
+            Request Time status: Yellow (55%), Service status: Green (8%)
+
+    Each dimension has a colour: Green (<50%), Yellow (50–75%), Red (>75%), Black
+    (blocked).  We return the worst-case backpressure delay across all dimensions
+    so the client can slow down **before** hitting a hard 429/503.
+
+    Args:
+      headers: Mapping of response headers.
+
+    Returns:
+      Recommended additional delay in seconds (0.0 if Green or header
+      is absent).
+    """
+    value = headers.get("X-Throttling-Control")
+    if not value:
+        return 0.0
+
+    max_delay = 0.0
+    for match in _THROTTLE_STATUS_RE.finditer(value):
+        colour = match.group(2)
+        delay = _THROTTLE_BACKPRESSURE.get(colour, 0.0)
+        if delay > max_delay:
+            max_delay = delay
+    return max_delay
+
+
+class HttpClient:
+    """Rate-limited HTTP client with automatic retries and backoff.
+
+    Uses `urllib.request` as the transport layer. Handles gzip decompression,
+    charset detection, and streaming iteration internally.
+
+    Example:
+
+        chembl_api = HttpClient(
+            "https://www.ebi.ac.uk/chembl/api/data/",
+            qps=5,
+            jitter=0.5,
+        )
+        data = chembl_api.fetch_json("molecule/CHEMBL25.json")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        qps: float,
+        *,
+        default_headers: dict[str, str] | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT_SECS,
+        backoff_base: float = DEFAULT_BACKOFF_BASE_SECS,
+        backoff_max: float = DEFAULT_BACKOFF_MAX_SECS,
+        jitter: float = DEFAULT_JITTER_SECS,
+        user_agent: str | None = None,
+        retryable_status_codes: frozenset[int] = RETRYABLE_STATUS_CODES,
+        referer: str | None = None,
+    ):
+        """Rate-limited HTTP client with automatic retries and backoff.
+
+        Args:
+          base_url: Base URL of the API (e.g. "https://eutils.ncbi.nlm.nih.gov/").
+          qps: Maximum queries per second (steady-state).
+          default_headers: Default HTTP headers to include in every request.
+          max_retries: Maximum retry attempts for transient errors.  The total
+            number of attempts is `max_retries + 1`.
+          timeout: Default per-request timeout in seconds.
+          backoff_base: Base delay (seconds) for exponential backoff.
+          backoff_max: Cap on backoff delay (seconds).
+          jitter: Maximum random jitter (seconds) added uniformly to each backoff
+            delay.
+          user_agent: Default `User-Agent` header value.  Falls back to the
+            `POLITE_HTTP_USER_AGENT` env var.
+          retryable_status_codes: HTTP status codes that trigger a retry.
+          referer: Optional value for the HTTP `Referer` header sent with every
+            request.
+        """
+        self.base_url = base_url
+        parsed = urllib.parse.urlparse(base_url)
+        if not parsed.scheme or not parsed.netloc or not parsed.hostname:
+            raise ValueError(f"base_url must be an absolute URL: {base_url!r}")
+        self.hostname: str = parsed.hostname
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self.backoff_base = backoff_base
+        self.backoff_max = backoff_max
+        self.jitter = jitter
+        self.user_agent = user_agent or os.environ.get(USER_AGENT_ENV_VAR, "")
+        self.retryable_status_codes = retryable_status_codes
+        self.default_headers = default_headers or {}
+        self._limiter = _RateLimiter(self.hostname, qps=qps)
+        self._next_min_sleep = 0.0
+        self._referer = referer
+
+    def wait(self, min_sleep: float = 0.0) -> None:
+        """Wait for the rate limiter without making a request.
+
+        Useful for non-`fetch` operations that still need to respect the
+        cross-process rate limit — for example, polling loops or pre-streaming
+        handshakes.
+
+        Args:
+          min_sleep: Minimum time to sleep in seconds before returning.
+        """
+        self._limiter.wait(min_sleep=min_sleep)
+
+    def _compute_backoff(self, attempt: int, retry_after: float | None = None) -> float:
+        """Compute the delay before the next retry.
+
+        Uses exponential backoff `base * 2^attempt` capped at `backoff_max`, with
+        optional uniform jitter.  If the server provided a `Retry-After` value, the
+        returned delay is at least that large.
+
+        Args:
+          attempt: Zero-based retry attempt number (0 = first *retry*).
+          retry_after: Optional server `Retry-After` value in seconds.
+
+        Returns:
+          Delay in seconds.
+        """
+        delay = self.backoff_base * (2**attempt)
+        if retry_after is not None:
+            delay = max(delay, retry_after)
+        delay = min(delay, self.backoff_max)
+        if self.jitter > 0:
+            delay += random.uniform(0, self.jitter)
+        return delay
+
+    def _resolve_url(self, url: str) -> str:
+        """Resolve *url* against `base_url`."""
+        if "://" not in url:
+            return urllib.parse.urljoin(self.base_url, url)
+        if not url.startswith(self.base_url):
+            raise ValueError(f"URL {url!r} does not match base_url {self.base_url!r}")
+        return url
+
+    def _build_request(
+        self,
+        url: str,
+        method: str,
+        headers: dict[str, str] | None,
+        data: bytes | None,
+        json_body: Any | None,
+    ) -> urllib.request.Request:
+        """Build a `urllib.request.Request` from the given parameters."""
+        merged_headers = {
+            "User-Agent": self.user_agent,
+            "Accept-Encoding": "gzip",
+        }
+        if self._referer:
+            merged_headers["Referer"] = self._referer
+        # Must be last: Give priority to user-provided headers.
+        merged_headers.update(self.default_headers)
+        if headers:
+            merged_headers.update(headers)
+
+        body: bytes | None = data
+        if json_body is not None:
+            body = json.dumps(json_body).encode("utf-8")
+            merged_headers.setdefault("Content-Type", "application/json")
+
+        req = urllib.request.Request(
+            url,
+            data=body,
+            headers=merged_headers,
+            method=method,
+        )
+        return req
+
+    def fetch(
+        self,
+        url: str,
+        *,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        data: bytes | None = None,
+        json_body: Any | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> HttpResponse:
+        """Execute an HTTP request with rate limiting and retries.
+
+        On each attempt the client:
+
+        1. Waits for the rate limiter (cross-process file-lock).
+        2. Sends the request via `urllib.request`.
+        3. On success (2xx), returns an `HttpResponse`.
+        4. On a retryable HTTP error (429, 5xx) or a network error, sleeps for an
+           exponential backoff delay (with optional jitter and `Retry-After`
+           support) before retrying.
+        5. On a non-retryable HTTP error, raises `HttpError` immediately.
+
+        Args:
+          url: Request URL.
+          method: HTTP method (`GET`, `POST`, etc.).
+          headers: Extra HTTP headers (merged with the default User-Agent).
+          data: Raw request body bytes (mutually exclusive with *json_body*).
+          json_body: JSON-serializable request body.  Automatically sets
+            `Content-Type: application/json`.
+          timeout: Per-request timeout in seconds (overrides the client-level
+            default).
+          max_retries: Override for the maximum number of retry attempts.
+
+        Returns:
+          `HttpResponse` containing the response data.
+
+        Raises:
+          HttpError: On non-retryable HTTP errors or after exhausting all
+              retry attempts.
+          ValueError: If both *data* and *json_body* are provided.
+        """
+        with self._open_stream(
+            url, method, headers, data, json_body, timeout, max_retries
+        ) as resp:
+            stream = _maybe_decompress(resp)
+            body = stream.read()
+            encoding = resp.headers.get_content_charset() or DEFAULT_CHARSET
+            return HttpResponse(
+                data=body,
+                status_code=resp.status,
+                headers=dict(resp.headers),
+                url=resp.url,
+                encoding=encoding,
+            )
+
+    def fetch_json(self, url: str, **kwargs) -> Any:
+        """Fetch a URL and parse the response as JSON.
+
+        Convenience wrapper around `fetch()` that adds an
+        `Accept: application/json` header (if not already set) and returns the
+        parsed JSON body.
+
+        Args:
+          url: URL to fetch.
+          **kwargs: Keyword arguments to pass to `fetch()`.
+
+        Returns:
+          Parsed JSON (dict, list, str, etc.).
+
+        Raises:
+          HttpError: On HTTP or network errors.
+          json.JSONDecodeError: If the response body is not valid JSON.
+        """
+        hdrs = kwargs.pop("headers", None) or {}
+        hdrs.setdefault("Accept", "application/json")
+        resp = self.fetch(url, headers=hdrs, **kwargs)
+        return resp.json()
+
+    def fetch_bytes(self, url: str, **kwargs) -> bytes:
+        """Fetch a URL and return the raw response body.
+
+        Convenience wrapper for binary downloads (PDFs, images, archives, etc.).
+
+        Args:
+          url: URL to fetch.
+          **kwargs: Keyword arguments to pass to `fetch()`.
+
+        Returns:
+          Raw response bytes.
+
+        Raises:
+          HttpError: On HTTP or network errors.
+        """
+        return self.fetch(url, **kwargs).data
+
+    def fetch_text(self, url: str, **kwargs) -> str:
+        """Fetch a URL and return the response body as a decoded string.
+
+        Convenience wrapper for text-based APIs (XML, TSV, plain text).
+
+        Args:
+          url: URL to fetch.
+          **kwargs: Keyword arguments to pass to `fetch()`.
+
+        Returns:
+          Response body decoded using the charset from Content-Type.
+
+        Raises:
+          HttpError: On HTTP or network errors.
+        """
+        return self.fetch(url, **kwargs).text
+
+    @contextlib.contextmanager
+    def _open_stream(
+        self,
+        url: str,
+        method: str,
+        headers: dict[str, str] | None,
+        data: bytes | None,
+        json_body: Any | None,
+        timeout: float | None,
+        max_retries: int | None = None,
+    ) -> Iterator[http.client.HTTPResponse]:
+        """Open an HTTP response with rate limiting and retries (internal).
+
+        Handles argument validation, rate limiting, request dispatch, and
+        error checking.  Yields the raw `http.client.HTTPResponse` and
+        guarantees `response.close()` on exit.
+
+        The **connection phase** (before any data flows) is retried on
+        transient errors (429, 5xx) with the same backoff logic as
+        `fetch()`.  Once a 2xx response is yielded, no further retries
+        are attempted — streaming data is not idempotently resumable.
+
+        On **2xx responses** that include an `X-Throttling-Control`
+        header, proactive backpressure is applied so the next request
+        is delayed before hitting a hard limit.
+
+        Args:
+          url: Request URL.
+          method: HTTP method.
+          headers: Extra HTTP headers.
+          data: Raw request body bytes.
+          json_body: JSON-serializable request body.
+          timeout: Per-request timeout override.
+          max_retries: Override for maximum connection retry attempts.
+
+        Yields:
+          An open `http.client.HTTPResponse` ready for streaming reads.
+
+        Raises:
+          HttpError: On HTTP errors (non-2xx status) or network errors.
+          ValueError: If both *data* and *json_body* are provided.
+        """
+        if data is not None and json_body is not None:
+            raise ValueError("Cannot specify both 'data' and 'json_body'.")
+
+        url = self._resolve_url(url)
+
+        effective_timeout = timeout if timeout is not None else self.timeout
+        effective_retries = max_retries if max_retries is not None else self.max_retries
+
+        last_exc: Exception | None = None
+        next_min_sleep = 0.0
+        for attempt in range(effective_retries + 1):
+            current_min_sleep = max(next_min_sleep, self._next_min_sleep)
+            self._limiter.wait(min_sleep=current_min_sleep)
+            self._next_min_sleep = 0.0
+            req = self._build_request(url, method, headers, data, json_body)
+
+            try:
+                response = urllib.request.urlopen(req, timeout=effective_timeout)
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                error_body = exc.read()
+                retry_after = _parse_retry_after(exc.headers)
+                exc.close()
+
+                if (
+                    status in self.retryable_status_codes
+                    and attempt < effective_retries
+                ):
+                    next_min_sleep = self._compute_backoff(attempt, retry_after)
+                    logging.info(
+                        "HttpClient[%s]: HTTP %d from %s — retrying in ≥%.1fs"
+                        " (attempt %d/%d)",
+                        self.hostname,
+                        status,
+                        url,
+                        next_min_sleep,
+                        attempt + 1,
+                        effective_retries + 1,
+                    )
+                    last_exc = HttpError(
+                        f"HTTP Error {status} while fetching {url}",
+                        status_code=status,
+                        body=error_body,
+                        url=url,
+                    )
+                    continue
+
+                hint = ""
+                if status == 403:
+                    hint = (
+                        f" (Hint: this may be caused by the User-Agent"
+                        f" '{self.user_agent}'. Override it by setting the environment"
+                        f" variable {USER_AGENT_ENV_VAR}, e.g.:"
+                        f' {USER_AGENT_ENV_VAR}="<enter_your_custom_user_agent>"'
+                        f" python3 script.py ...)"
+                    )
+                raise HttpError(
+                    f"HTTP Error {status} while fetching {url}{hint}",
+                    status_code=status,
+                    body=error_body,
+                    url=url,
+                ) from exc
+            except (urllib.error.URLError, OSError) as exc:
+                if attempt < effective_retries:
+                    next_min_sleep = self._compute_backoff(attempt)
+                    logging.info(
+                        "HttpClient[%s]: Network error (%s) — retrying in ≥%.1fs"
+                        " (attempt %d/%d)",
+                        self.hostname,
+                        exc,
+                        next_min_sleep,
+                        attempt + 1,
+                        effective_retries + 1,
+                    )
+                    last_exc = exc
+                    continue
+                raise HttpError(
+                    f"Network error fetching {url}: {exc}", url=url
+                ) from exc
+
+            # 2xx success.
+            throttle_delay = _parse_throttle_control(response.headers)
+            if throttle_delay > 0:
+                logging.info(
+                    "HttpClient[%s]: X-Throttling-Control backpressure %.1fs from %s",
+                    self.hostname,
+                    throttle_delay,
+                    url,
+                )
+                self._next_min_sleep = throttle_delay
+
+            try:
+                yield response
+            finally:
+                response.close()
+            return
+
+        # Should not be reachable.
+        raise HttpError(
+            f"Max retries ({effective_retries}) exceeded for {url}",
+            url=url,
+        ) from last_exc
+
+    def stream_lines(
+        self,
+        url: str,
+        *,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        data: bytes | None = None,
+        json_body: Any | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> Iterator[str]:
+        """Stream an HTTP response line-by-line without buffering.
+
+        Useful for large result sets (e.g. UniProt `/stream` which can
+        return up to 10M lines).  The response is streamed via
+        `urllib.request` with automatic gzip decompression.
+
+        Rate-limits before each attempt.  The **connection phase** is
+        retried on transient errors (429, 5xx), but once data starts
+        streaming, no further retries are attempted.
+
+        Args:
+          url: Request URL.
+          method: HTTP method.
+          headers: Extra HTTP headers.
+          data: Raw request body bytes (mutually exclusive with *json_body*).
+          json_body: JSON-serializable request body.
+          timeout: Per-request timeout in seconds (overrides the client default).
+            This is the timeout for the initial connection, not for reading
+            individual lines.
+          max_retries: Override for maximum connection retry attempts.
+
+        Yields:
+          Each line of the response body, decoded as text (trailing newline
+          stripped).
+
+        Raises:
+          HttpError: On HTTP errors (non-2xx status).
+        """
+        with self._open_stream(
+            url, method, headers, data, json_body, timeout, max_retries
+        ) as response:
+            stream = _maybe_decompress(response)
+            encoding = response.headers.get_content_charset() or DEFAULT_CHARSET
+            for raw_line in stream:
+                line = raw_line.decode(encoding).rstrip("\r\n")
+                yield line
+
+    def stream_bytes(
+        self,
+        url: str,
+        *,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        data: bytes | None = None,
+        json_body: Any | None = None,
+        timeout: float | None = None,
+        chunk_size: int = 8192,
+        max_retries: int | None = None,
+    ) -> Iterator[bytes]:
+        """Stream an HTTP response as raw byte chunks without buffering.
+
+        Symmetric with `stream_lines` but for binary content (PDFs, archives,
+        images, etc.).  Each iteration yields a chunk of up to *chunk_size* bytes.
+        Chunks are **transfer-decoded**: if the server applied
+        `Content-Encoding: gzip` in transit, the yielded bytes are the
+        decompressed content.
+
+        Rate-limits before each attempt.  The **connection phase** is retried on
+        transient errors (429, 5xx), but once data starts streaming, no further
+        retries are attempted.
+
+        Example:
+
+            with open("paper.pdf", "wb") as f:
+                for chunk in client.stream_bytes(url):
+                    f.write(chunk)
+
+        Args:
+          url: Request URL.
+          method: HTTP method.
+          headers: Extra HTTP headers.
+          data: Raw request body bytes (mutually exclusive with *json_body*).
+          json_body: JSON-serializable request body.
+          timeout: Per-request timeout in seconds (overrides the client default).
+            This is the timeout for the initial connection, not for reading
+            individual chunks.
+          chunk_size: Maximum number of bytes per yielded chunk.
+          max_retries: Override for maximum connection retry attempts.
+
+        Yields:
+          Non-empty `bytes` chunks of the response body.
+
+        Raises:
+          HttpError: On HTTP errors (non-2xx status).
+        """
+        with self._open_stream(
+            url, method, headers, data, json_body, timeout, max_retries
+        ) as response:
+            stream = _maybe_decompress(response)
+            while True:
+                chunk = stream.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk

polite_http-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: polite-http
+Version: 0.1.0
+Summary: A courteous, dependency-free HTTP client with rate limiting, retries, and backoff.
+Project-URL: Homepage, https://github.com/doug/polite-http
+Project-URL: Repository, https://github.com/doug/polite-http
+Project-URL: Issues, https://github.com/doug/polite-http/issues
+Project-URL: Changelog, https://github.com/doug/polite-http/blob/main/CHANGELOG.md
+Author-email: Doug Fritz <dougfritz@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: backoff,client,http,rate-limiting,retry,throttling,urllib
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# polite-http
+
+[![CI](https://github.com/doug/polite-http/actions/workflows/ci.yml/badge.svg)](https://github.com/doug/polite-http/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/polite-http.svg)](https://pypi.org/project/polite-http/)
+[![Python versions](https://img.shields.io/pypi/pyversions/polite-http.svg)](https://pypi.org/project/polite-http/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+A courteous, **dependency-free** HTTP client for Python. It plays nice with
+rate-limited APIs out of the box:
+
+- **Per-host rate limiting** — cross-process, via a shared file lock.
+- **Automatic retries** on transient errors (HTTP 429, 5xx) and network errors.
+- **Exponential backoff** with optional jitter.
+- **`Retry-After`** support (server-directed backoff, both seconds and
+  HTTP-date forms).
+- **`X-Throttling-Control`** proactive backpressure (as used by PubChem / NCBI).
+- **Streaming** helpers for large line-oriented and binary responses.
+- **Zero third-party dependencies** — built entirely on the standard library
+  (`urllib.request`).
+
+## Installation
+
+```bash
+pip install polite-http
+```
+
+Requires Python 3.9+. Cross-process rate limiting works on Linux, macOS, and
+Windows — it uses `fcntl` on POSIX and `msvcrt` on Windows for the shared file
+lock (both standard library). On the rare platform that provides neither, it
+falls back to a best-effort in-process timer.
+
+## Quick start
+
+```python
+from polite_http import HttpClient
+
+# Scope a client to a base URL and a steady-state rate of 3 requests/second.
+client = HttpClient("https://eutils.ncbi.nlm.nih.gov/entrez/eutils/", qps=3)
+
+# GET + parse JSON (relative paths are resolved against the base URL).
+data = client.fetch_json("esummary.fcgi?db=pubmed&id=123456")
+
+# POST a JSON body.
+result = client.fetch_json(
+    "esearch.fcgi",
+    method="POST",
+    json_body={"db": "pubmed", "term": "cancer"},
+)
+
+# Download raw bytes with a custom timeout.
+pdf = client.fetch_bytes(
+    "efetch.fcgi?db=pubmed&id=123456&rettype=abstract",
+    timeout=60,
+)
+```
+
+## Streaming
+
+```python
+# Stream a large response line-by-line without buffering it all in memory.
+for line in client.stream_lines("large-export.tsv"):
+    process(line)
+
+# Stream binary content in chunks (e.g. to a file).
+with open("paper.pdf", "wb") as f:
+    for chunk in client.stream_bytes("paper.pdf"):
+        f.write(chunk)
+```
+
+## Configuration
+
+`HttpClient` accepts the following keyword arguments:
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `qps` | _required_ | Maximum queries per second (steady state). |
+| `default_headers` | `None` | Headers added to every request. |
+| `max_retries` | `7` | Retry attempts for transient errors (total attempts = `max_retries + 1`). |
+| `timeout` | `60.0` | Per-request timeout in seconds. |
+| `backoff_base` | `3.0` | Base delay for exponential backoff. |
+| `backoff_max` | `180.0` | Cap on backoff delay. |
+| `jitter` | `0.5` | Max uniform random jitter added to each backoff. |
+| `user_agent` | env / `""` | `User-Agent` header; falls back to `POLITE_HTTP_USER_AGENT`. |
+| `retryable_status_codes` | `{429, 500, 502, 503, 504}` | Status codes that trigger a retry. |
+| `referer` | `None` | Optional `Referer` header sent with every request. |
+
+### Environment variables
+
+- `POLITE_HTTP_USER_AGENT` — default `User-Agent` when one isn't passed
+  explicitly. Many APIs (e.g. NCBI) reject requests without a descriptive
+  User-Agent, so setting this is recommended.
+- `POLITE_HTTP_LOCK_DIR` — directory for the cross-process rate-limit lock
+  files (defaults to the system temp directory).
+
+## Error handling
+
+Failed requests raise `HttpError`, which carries the `status_code`, raw `body`
+bytes, and `url`:
+
+```python
+from polite_http import HttpClient, HttpError
+
+client = HttpClient("https://api.example.com/", qps=5)
+try:
+    data = client.fetch_json("widgets/42")
+except HttpError as exc:
+    print(exc.status_code, exc.url)
+    if exc.body:
+        print(exc.json())  # parse the error body as JSON, if applicable
+```
+
+## Acknowledgements
+
+The HTTP client at the heart of this package is derived from the
+[`science-skills`](https://github.com/google-deepmind/science-skills) project by
+Google DeepMind, used under the Apache License 2.0. See [`NOTICE`](NOTICE) for
+details of the changes.
+
+## License
+
+[Apache License 2.0](LICENSE).

polite_http-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+polite_http/__init__.py,sha256=LtTyWZmJ90euuXweYPcRHZxGKQ_JdoTG4kECuelGmas,1440
+polite_http/http_client.py,sha256=2fuYy-zh4XWSufHNHHyhF6EeGEl3n4CRFDRELat41xI,32369
+polite_http/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polite_http-0.1.0.dist-info/METADATA,sha256=-VqUDgXS8Ud2Y6cWgnQoSKMTjYwvyt-EG2iBUWmhp70,5955
+polite_http-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+polite_http-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+polite_http-0.1.0.dist-info/licenses/NOTICE,sha256=DIzzTLYPkNV3zIAqWqrHkxQ_TCGTyKI41Vq9oUi7lh0,1312
+polite_http-0.1.0.dist-info/RECORD,,

polite_http-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

polite_http-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

polite_http-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,27 @@
+polite-http
+Copyright 2026 polite-http contributors
+
+This product includes software developed by Google LLC as part of the
+science-skills project (https://github.com/google-deepmind/science-skills),
+licensed under the Apache License, Version 2.0.
+
+The file `src/polite_http/http_client.py` is derived from
+`skills/scienceskillscommon/http_client.py` in that project.
+
+Modifications made by the polite-http contributors include:
+
+  * Repackaged as the standalone, installable `polite_http` Python package.
+  * Renamed the project/lock-file prefix from "science-skills" to
+    "polite-http".
+  * Renamed the User-Agent environment variable from
+    "SCIENCE_SKILLS_USER_AGENT" to "POLITE_HTTP_USER_AGENT" (exposed as
+    `polite_http.USER_AGENT_ENV_VAR`).
+  * Replaced the science-skills-specific `referer_skill` parameter and Referer
+    template with a generic `referer` string parameter.
+  * Added cross-platform cross-process locking: `fcntl` on POSIX and `msvcrt`
+    on Windows, with a best-effort in-process timer fallback on the rare
+    platform that provides neither (still standard-library only).
+  * Made the rate-limit lock directory configurable via the
+    "POLITE_HTTP_LOCK_DIR" environment variable (defaulting to the system temp
+    directory).
+  * Added input validation for non-positive `qps`.