timeweave 1.0.0__tar.gz

timeweave-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vxmpingz_
+
+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.

timeweave-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: timeweave
+Version: 1.0.0
+Summary: Timezone detection, conversion, and self-maintaining IANA rule cache.
+Author: vxmpingz_
+License: MIT
+Project-URL: Homepage, https://github.com/vxmpingz/timeweave
+Project-URL: Issues, https://github.com/vxmpingz/timeweave/issues
+Keywords: timezone,tzdata,zoneinfo,iana,dst,zic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: tzdata
+Requires-Dist: tzdata>=2024.1; extra == "tzdata"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# timeweave
+
+Timezone detection, conversion, and a self-maintaining IANA rule cache.
+Zero runtime dependencies. Python 3.9+.
+
+## Install
+
+```bash
+pip install timeweave
+```
+
+## Layers
+
+| Module | Role |
+|---|---|
+| `timeweave.tzkit` | Detect, convert, parse, list zones (read path) |
+| `timeweave.updater` | Fetch + SHA-256 verify + cache the rules DB |
+| `timeweave.compiler` | Fetch + verify + `zic`-compile tz source into a zoneinfo tree |
+
+
+## Library use
+
+```python
+import timeweave
+
+info = timeweave.detect_timezone()
+print(info["timezone"], info["utc_offset"], info["dst_active"])
+
+result = timeweave.convert_timezone(
+    "2024-03-10 02:30", ["UTC", "Asia/Tokyo"], from_zone="America/New_York"
+)
+print(result["instant_utc"], result["local_time_kind"])
+
+parsed = timeweave.parse_datetime("Sun, 10 Mar 2024 07:30:00 +0000")
+```
+
+## CLI
+
+```bash
+tzkit detect --use-ip
+tzkit convert '2024-03-10 02:30' --from America/New_York --to UTC --to Asia/Tokyo
+tzkit parse 'Sun, 10 Mar 2024 07:30:00 +0000'
+tzkit list Europe --transitions --sort offset
+
+tz-update check --json
+tz-compile refresh --force
+tz-compile status
+```
+
+## DST policy
+
+Wall-clock times that fall in a DST gap or fold are classified, never guessed
+silently:
+
+* `--ambiguous earliest|latest|raise` — repeated wall times (fold)
+* `--nonexistent shift_forward|shift_backward|raise` — skipped wall times (gap)
+
+`raise` exits `6` so CI catches the case.
+
+## Auto-update
+
+`detect_timezone()` and `convert_timezone()` start a non-blocking daemon-thread
+update check, at most once per 24h, gated by a marker file. Failures are logged
+and swallowed; the caller's result is never affected.
+
+Disable it:
+
+| Variable | Effect |
+|---|---|
+| `TIMEWEAVE_NO_AUTO_UPDATE=1` | Disable the on-use check only |
+| `TIMEWEAVE_OFFLINE=1` | Disable all outbound network from the package |
+| `TIMEWEAVE_NO_NETWORK=1` | Same as `OFFLINE` |
+| `TIMEWEAVE_AUTO_INTERVAL` | Seconds between checks (default `86400`) |
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `TIMEWEAVE_SRC_URL` | Source endpoint (compiler) |
+| `TIMEWEAVE_CHECKSUM_URL` | Published SHA-256 (default `<url>.sha256`) |
+| `TIMEWEAVE_SIGNATURE_URL` + `TIMEWEAVE_GPG_KEYRING` | Authenticity verification |
+| `TIMEWEAVE_ZIC_PATH` | Absolute `zic` path (trusted config only) |
+| `TIMEWEAVE_CACHE_DIR` | Cache directory |
+| `TZDIR` | Compiled zoneinfo tree; prepended to `zoneinfo.TZPATH` on import |
+| `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` | Custom CA bundle |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Standard proxy settings |
+
+## Security notes
+
+* **SHA-256 proves integrity, not authenticity.** If the same host serves the
+  payload and the checksum, it controls both. Set `TIMEWEAVE_SIGNATURE_URL` and
+  `TIMEWEAVE_GPG_KEYRING` against a trusted key for real authenticity.
+* **The compiler targets an app-owned directory by default.** Writing into
+  `/usr/share/zoneinfo` requires `--system`, needs root, and affects every
+  process on the host. Prefer your OS's signed `tzdata` package for the system
+  tree; use this module for isolated, air-gapped, or version-pinned caches.
+* **Archive members and `Zone`/`Link` names are validated before `zic` runs**,
+  and compiler output is re-checked for containment afterwards.
+* The `zic` path is a fixed absolute constant, validated executable, and is
+  never read from a network response.
+
+## License
+
+MIT

timeweave-1.0.0/README.md

@@ -0,0 +1,104 @@
+# timeweave
+
+Timezone detection, conversion, and a self-maintaining IANA rule cache.
+Zero runtime dependencies. Python 3.9+.
+
+## Install
+
+```bash
+pip install timeweave
+```
+
+## Layers
+
+| Module | Role |
+|---|---|
+| `timeweave.tzkit` | Detect, convert, parse, list zones (read path) |
+| `timeweave.updater` | Fetch + SHA-256 verify + cache the rules DB |
+| `timeweave.compiler` | Fetch + verify + `zic`-compile tz source into a zoneinfo tree |
+
+
+## Library use
+
+```python
+import timeweave
+
+info = timeweave.detect_timezone()
+print(info["timezone"], info["utc_offset"], info["dst_active"])
+
+result = timeweave.convert_timezone(
+    "2024-03-10 02:30", ["UTC", "Asia/Tokyo"], from_zone="America/New_York"
+)
+print(result["instant_utc"], result["local_time_kind"])
+
+parsed = timeweave.parse_datetime("Sun, 10 Mar 2024 07:30:00 +0000")
+```
+
+## CLI
+
+```bash
+tzkit detect --use-ip
+tzkit convert '2024-03-10 02:30' --from America/New_York --to UTC --to Asia/Tokyo
+tzkit parse 'Sun, 10 Mar 2024 07:30:00 +0000'
+tzkit list Europe --transitions --sort offset
+
+tz-update check --json
+tz-compile refresh --force
+tz-compile status
+```
+
+## DST policy
+
+Wall-clock times that fall in a DST gap or fold are classified, never guessed
+silently:
+
+* `--ambiguous earliest|latest|raise` — repeated wall times (fold)
+* `--nonexistent shift_forward|shift_backward|raise` — skipped wall times (gap)
+
+`raise` exits `6` so CI catches the case.
+
+## Auto-update
+
+`detect_timezone()` and `convert_timezone()` start a non-blocking daemon-thread
+update check, at most once per 24h, gated by a marker file. Failures are logged
+and swallowed; the caller's result is never affected.
+
+Disable it:
+
+| Variable | Effect |
+|---|---|
+| `TIMEWEAVE_NO_AUTO_UPDATE=1` | Disable the on-use check only |
+| `TIMEWEAVE_OFFLINE=1` | Disable all outbound network from the package |
+| `TIMEWEAVE_NO_NETWORK=1` | Same as `OFFLINE` |
+| `TIMEWEAVE_AUTO_INTERVAL` | Seconds between checks (default `86400`) |
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `TIMEWEAVE_SRC_URL` | Source endpoint (compiler) |
+| `TIMEWEAVE_CHECKSUM_URL` | Published SHA-256 (default `<url>.sha256`) |
+| `TIMEWEAVE_SIGNATURE_URL` + `TIMEWEAVE_GPG_KEYRING` | Authenticity verification |
+| `TIMEWEAVE_ZIC_PATH` | Absolute `zic` path (trusted config only) |
+| `TIMEWEAVE_CACHE_DIR` | Cache directory |
+| `TZDIR` | Compiled zoneinfo tree; prepended to `zoneinfo.TZPATH` on import |
+| `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` | Custom CA bundle |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Standard proxy settings |
+
+## Security notes
+
+* **SHA-256 proves integrity, not authenticity.** If the same host serves the
+  payload and the checksum, it controls both. Set `TIMEWEAVE_SIGNATURE_URL` and
+  `TIMEWEAVE_GPG_KEYRING` against a trusted key for real authenticity.
+* **The compiler targets an app-owned directory by default.** Writing into
+  `/usr/share/zoneinfo` requires `--system`, needs root, and affects every
+  process on the host. Prefer your OS's signed `tzdata` package for the system
+  tree; use this module for isolated, air-gapped, or version-pinned caches.
+* **Archive members and `Zone`/`Link` names are validated before `zic` runs**,
+  and compiler output is re-checked for containment afterwards.
+* The `zic` path is a fixed absolute constant, validated executable, and is
+  never read from a network response.
+
+## License
+
+MIT

timeweave-1.0.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "timeweave"
+version = "1.0.0"
+description = "Timezone detection, conversion, and self-maintaining IANA rule cache."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "vxmpingz_" }]
+keywords = ["timezone", "tzdata", "zoneinfo", "iana", "dst", "zic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = []
+
+[project.optional-dependencies]
+tzdata = ["tzdata>=2024.1"]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/vxmpingz/timeweave"
+Issues = "https://github.com/vxmpingz/timeweave/issues"
+
+[project.scripts]
+tzkit = "timeweave.tzkit:main"
+tz-update = "timeweave.updater:main"
+tz-compile = "timeweave.compiler:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+timeweave = ["py.typed"]
+
+[tool.ruff]
+line-length = 92
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S"]
+ignore = ["S603", "S607"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_unused_ignores = true
+warn_redundant_casts = true

timeweave-1.0.0/setup.cfg

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

timeweave-1.0.0/src/timeweave/__init__.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from ._logging import get_logger, log_event
+from ._state import should_run_periodic, touch_marker
+
+from . import tzkit as _tzkit
+from . import updater as _updater
+from . import compiler as _compiler
+
+from .updater import _sync_database, get_cached_database
+from .compiler import (refresh_zoneinfo, activate_cache,
+                       get_cache_status, compile_source)
+
+__version__ = "1.0.0"
+__all__ = [
+    "detect_timezone", "convert_timezone", "parse_datetime",
+    "_sync_database", "refresh_zoneinfo", "activate_cache",
+    "get_cached_database", "get_cache_status", "compile_source",
+    "use_compiled_cache", "_ensure_cache", "auto_update_enabled",
+    "__version__",
+]
+
+LOG = get_logger("timeweave")
+
+_DEFAULT_INTERVAL = 24 * 3600
+_AUTO_LOCK = threading.Lock()
+_AUTO_THREAD: Optional[threading.Thread] = None
+
+
+# --------------------------------------------------------------------------
+# Environment helpers
+# --------------------------------------------------------------------------
+
+def _is_truthy(value: Optional[str]) -> bool:
+    return bool(value) and value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def auto_update_enabled() -> bool:
+    if _is_truthy(os.environ.get("TIMEWEAVE_NO_AUTO_UPDATE")):
+        return False
+    if _is_truthy(os.environ.get("TIMEWEAVE_OFFLINE")):
+        return False
+    if _is_truthy(os.environ.get("TIMEWEAVE_NO_NETWORK")):
+        return False
+    return True
+
+
+def _auto_interval() -> float:
+    raw = os.environ.get("TIMEWEAVE_AUTO_INTERVAL")
+    if raw is None:
+        return _DEFAULT_INTERVAL
+    try:
+        value = float(raw)
+    except ValueError:
+        log_event(LOG, logging.WARNING, "invalid_env_value",
+                  variable="TIMEWEAVE_AUTO_INTERVAL", value=raw)
+        return _DEFAULT_INTERVAL
+    return value if value > 0 else _DEFAULT_INTERVAL
+
+
+def _cache_dir() -> Path:
+    override = os.environ.get("TIMEWEAVE_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CACHE_HOME")
+    if base:
+        return Path(base).expanduser() / "timeweave"
+    if os.name == "nt":
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            return Path(local) / "timeweave" / "cache"
+    return Path.home() / ".cache" / "timeweave"
+
+
+def _marker_path() -> Path:
+    return _cache_dir() / ".cache_freshness"
+
+def _refresh_cache() -> None:
+    try:
+        result = _sync_database()
+        log_event(LOG, logging.INFO, "auto_update_finished",
+                  status=getattr(result, "status", None),
+                  changed=getattr(result, "changed", None),
+                  db_version=getattr(result, "db_version", None))
+    except Exception as exc:
+        log_event(LOG, logging.DEBUG, "auto_update_error",
+                  error=f"{type(exc).__name__}: {exc}")
+
+
+def _ensure_cache(force: bool = False) -> bool:
+    global _AUTO_THREAD
+    try:
+        if not force and not auto_update_enabled():
+            return False
+        marker = _marker_path()
+        if not force and not should_run_periodic(marker, _auto_interval()):
+            return False
+        with _AUTO_LOCK:
+            if _AUTO_THREAD is not None and _AUTO_THREAD.is_alive():
+                return False
+            touch_marker(marker)
+            thread = threading.Thread(target=_refresh_cache,
+                                      name="curls-autoupdate", daemon=True)
+            thread.start()
+            _AUTO_THREAD = thread
+        log_event(LOG, logging.DEBUG, "auto_update_started", force=force)
+        return True
+    except Exception as exc:
+        log_event(LOG, logging.DEBUG, "auto_update_trigger_failed",
+                  error=f"{type(exc).__name__}: {exc}")
+        return False
+
+def _apply_tzpath(directory: str) -> bool:
+    path = Path(directory).expanduser()
+    if not path.is_dir():
+        log_event(LOG, logging.WARNING, "tzdir_missing", path=str(path))
+        return False
+    try:
+        import zoneinfo
+        existing = [p for p in zoneinfo.TZPATH if p != str(path)]
+        zoneinfo.reset_tzpath([str(path), *existing])
+        log_event(LOG, logging.INFO, "tzpath_applied", path=str(path))
+        return True
+    except Exception as exc:
+        log_event(LOG, logging.WARNING, "tzpath_apply_failed",
+                  path=str(path), error=str(exc))
+        return False
+
+
+def use_compiled_cache(config: Optional[Any] = None) -> bool:
+    return activate_cache(config)
+
+
+def _init_tzdir() -> None:
+    tzdir = os.environ.get("TZDIR")
+    if tzdir:
+        _apply_tzpath(tzdir)
+
+def _tzkit_config(config: Optional[Any]) -> Any:
+    if config is not None:
+        return config
+    cfg = _tzkit.Config()
+    if not auto_update_enabled():
+        cfg.no_network = True
+    return cfg
+
+def detect_timezone(use_ip: bool = False, config: Optional[Any] = None) -> Dict[str, Any]:
+    _ensure_cache()
+    cfg = _tzkit_config(config)
+    return _tzkit.detect_timezone(cfg, use_ip=use_ip and auto_update_enabled())
+
+
+def parse_datetime(text: str, *, assume_tz: Optional[str] = None,
+                   ambiguous: str = "earliest", nonexistent: str = "shift_forward",
+                   strict_abbrev: bool = False, dayfirst: bool = False,
+                   config: Optional[Any] = None) -> Any:
+    cfg = _tzkit_config(config)
+    if dayfirst:
+        cfg.dayfirst = True
+    return _tzkit.parse_datetime(text, cfg, assume_tz=assume_tz,
+                                 ambiguous=ambiguous, nonexistent=nonexistent,
+                                 strict_abbrev=strict_abbrev)
+
+
+def convert_timezone(datetime_string: str, to_zones: Sequence[str], *,
+                     from_zone: Optional[str] = None, ambiguous: str = "earliest",
+                     nonexistent: str = "shift_forward", strict_abbrev: bool = False,
+                     config: Optional[Any] = None) -> Dict[str, Any]:
+    _ensure_cache()
+    cfg = _tzkit_config(config)
+
+    if not to_zones:
+        detected = _tzkit.detect_timezone(cfg, use_ip=False)["timezone"]
+        to_zones = [detected]
+
+    parsed = _tzkit.parse_datetime(
+        datetime_string, cfg, assume_tz=from_zone, ambiguous=ambiguous,
+        nonexistent=nonexistent, strict_abbrev=strict_abbrev)
+
+    from datetime import timezone as _timezone
+    rows: List[Dict[str, Any]] = []
+    for name in to_zones:
+        zone = _tzkit.get_zone(name)
+        local = parsed.dt.astimezone(zone)
+        rows.append({
+            "zone": zone.key,
+            "local_time": local.isoformat(),
+            "utc_offset": _tzkit.offset_str(local.utcoffset()),
+            "abbreviation": local.tzname() or "?",
+            "dst_active": _tzkit.is_dst(local),
+        })
+
+    return {
+        "input": datetime_string,
+        "instant_utc": parsed.dt.astimezone(_timezone.utc).isoformat(),
+        "epoch": parsed.dt.timestamp(),
+        "source_zone": parsed.tz_source,
+        "matched_format": parsed.matched,
+        "local_time_kind": parsed.kind,
+        "warnings": list(parsed.warnings),
+        "targets": rows,
+    }
+
+_init_tzdir()

timeweave-1.0.0/src/timeweave/_http.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import logging
+import re
+import ssl
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from ._logging import get_logger, log_event
+
+__all__ = [
+    "HttpError", "TlsConfigError", "FetchResult",
+    "build_ssl_context", "build_opener", "fetch",
+    "CHUNK", "redact_proxy",
+]
+
+LOG = get_logger("timeweave.http")
+
+CHUNK = 1024 * 256
+_RETRYABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})
+_TERMINAL_STATUS = frozenset({400, 401, 403, 404, 410})
+
+
+class HttpError(Exception):
+    pass
+
+
+class TlsConfigError(HttpError):
+    pass
+
+
+@dataclass
+class FetchResult:
+    status: int
+    body: Optional[bytes]
+    etag: Optional[str]
+    last_modified: Optional[str]
+    headers: Dict[str, str]
+    url: str
+
+
+def redact_proxy(value: str) -> str:
+    return re.sub(r"://[^@/]+@", "://***@", value)
+
+
+def build_ssl_context(ca_file: Optional[str] = None) -> ssl.SSLContext:
+    context = ssl.create_default_context()
+    context.check_hostname = True
+    context.verify_mode = ssl.CERT_REQUIRED
+    if ca_file:
+        try:
+            context.load_verify_locations(cafile=ca_file)
+            log_event(LOG, logging.INFO, "ca_bundle_loaded", path=ca_file)
+        except (ssl.SSLError, OSError) as exc:
+            raise TlsConfigError(f"cannot load CA bundle {ca_file}: {exc}") from exc
+    return context
+
+
+def build_opener(ca_file: Optional[str] = None) -> urllib.request.OpenerDirector:
+    context = build_ssl_context(ca_file)
+    handlers: List[urllib.request.BaseHandler] = [
+        urllib.request.HTTPSHandler(context=context)
+    ]
+    proxies = urllib.request.getproxies()
+    if proxies:
+        redacted = {k: redact_proxy(v) for k, v in proxies.items()}
+        log_event(LOG, logging.INFO, "proxy_configured", proxies=redacted)
+        handlers.append(urllib.request.ProxyHandler(proxies))
+    else:
+        handlers.append(urllib.request.ProxyHandler({}))
+    opener = urllib.request.build_opener(*handlers)
+    opener.addheaders = []
+    return opener
+
+
+def _read_capped(resp: Any, cap: int) -> bytes:
+    chunks: List[bytes] = []
+    total = 0
+    while True:
+        chunk = resp.read(CHUNK)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > cap:
+            raise HttpError(f"payload exceeds {cap} bytes; aborting")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def fetch(opener: urllib.request.OpenerDirector, url: str, *,
+          headers: Optional[Dict[str, str]] = None, timeout: float = 10.0,
+          retries: int = 2, cap: int = 64 * 1024 * 1024,
+          user_agent: str = "timeweave") -> FetchResult:
+    base_headers = {"User-Agent": user_agent}
+    if headers:
+        base_headers.update(headers)
+
+    last_exc: Optional[Exception] = None
+    for attempt in range(retries + 1):
+        request = urllib.request.Request(url, headers=base_headers, method="GET")
+        started = time.monotonic()
+        try:
+            with opener.open(request, timeout=timeout) as resp:
+                status = resp.getcode()
+                body = _read_capped(resp, cap)
+                result = FetchResult(
+                    status=status, body=body,
+                    etag=resp.headers.get("ETag"),
+                    last_modified=resp.headers.get("Last-Modified"),
+                    headers=dict(resp.headers.items()), url=url,
+                )
+                log_event(LOG, logging.INFO, "http_response", url=url,
+                          status=status, etag=result.etag, bytes=len(body),
+                          duration_ms=round((time.monotonic() - started) * 1000),
+                          attempt=attempt + 1)
+                return result
+        except urllib.error.HTTPError as exc:
+            if exc.code == 304:
+                etag = exc.headers.get("ETag") if exc.headers else None
+                log_event(LOG, logging.INFO, "http_not_modified", url=url,
+                          status=304, etag=etag, attempt=attempt + 1)
+                return FetchResult(304, None, etag, None,
+                                   dict(exc.headers.items()) if exc.headers else {},
+                                   url)
+            last_exc = exc
+            log_event(LOG, logging.WARNING, "http_error", url=url, status=exc.code,
+                      reason=str(exc.reason), attempt=attempt + 1)
+            if exc.code in _TERMINAL_STATUS or exc.code not in _RETRYABLE_STATUS:
+                break
+        except (urllib.error.URLError, ssl.SSLError, TimeoutError, OSError) as exc:
+            last_exc = exc
+            log_event(LOG, logging.WARNING, "network_error", url=url,
+                      error=str(getattr(exc, "reason", exc)), attempt=attempt + 1)
+        if attempt < retries:
+            time.sleep(min(1.5 * (attempt + 1), 5.0))
+    raise HttpError(f"request failed for {url}: {last_exc}")