timeweave 1.0.0__py3-none-any.whl

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/_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}")

timeweave/_logging.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, Optional
+
+__all__ = [
+    "StructuredFormatter", "get_logger", "setup_logging",
+    "log_event", "operation",
+]
+
+
+class StructuredFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload: Dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
+            "level": record.levelname,
+            "logger": record.name,
+            "event": record.getMessage(),
+        }
+        ctx = getattr(record, "context", None)
+        if isinstance(ctx, dict):
+            for key, value in ctx.items():
+                if value is not None:
+                    payload[key] = value
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        return json.dumps(payload, ensure_ascii=False, default=str)
+
+
+_TEXT_FORMAT = logging.Formatter(
+    "%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+    datefmt="%Y-%m-%dT%H:%M:%S%z",
+)
+
+
+def get_logger(name: str) -> logging.Logger:
+    return logging.getLogger(name)
+
+
+def setup_logging(logger: logging.Logger, verbose: int = 0, quiet: bool = False,
+                  log_file: Optional[str] = None, structured: bool = True) -> None:
+    if quiet:
+        level = logging.ERROR
+    elif verbose >= 2:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+
+    logger.setLevel(logging.DEBUG)
+    logger.handlers.clear()
+    logger.propagate = False
+
+    stream = logging.StreamHandler(sys.stderr)
+    stream.setLevel(level)
+    stream.setFormatter(StructuredFormatter() if structured else _TEXT_FORMAT)
+    logger.addHandler(stream)
+
+    if log_file:
+        try:
+            handler = logging.FileHandler(log_file, encoding="utf-8")
+        except OSError as exc:
+            logger.error("cannot open log file %s: %s", log_file, exc)
+        else:
+            handler.setLevel(logging.DEBUG)
+            handler.setFormatter(StructuredFormatter())
+            logger.addHandler(handler)
+
+
+def log_event(logger: logging.Logger, level: int, event: str, **context: Any) -> None:
+    logger.log(level, event, extra={"context": context})
+
+
+@contextlib.contextmanager
+def operation(logger: logging.Logger, name: str, **ctx: Any) -> Iterator[None]:
+    start = time.monotonic()
+    log_event(logger, logging.INFO, "operation_start", operation=name, **ctx)
+    try:
+        yield
+    except BaseException as exc:  # re-raised after logging
+        duration = round((time.monotonic() - start) * 1000)
+        log_event(logger, logging.ERROR, "operation_complete", operation=name,
+                  status="error", duration_ms=duration,
+                  error=f"{type(exc).__name__}: {exc}")
+        raise
+    else:
+        duration = round((time.monotonic() - start) * 1000)
+        log_event(logger, logging.INFO, "operation_complete", operation=name,
+                  status="ok", duration_ms=duration)

timeweave/_state.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ._logging import get_logger, log_event
+
+__all__ = [
+    "StateError", "atomic_write_bytes", "load_json", "save_json_atomic",
+    "ProcessLock", "should_run_periodic", "touch_marker", "marker_age_seconds",
+]
+
+LOG = get_logger("timeweave.state")
+
+
+class StateError(Exception):
+    pass
+
+
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=str(path.parent),
+                                    prefix=path.name + ".", suffix=".tmp")
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(str(tmp_path), str(path))
+    except OSError:
+        with contextlib.suppress(OSError):
+            tmp_path.unlink()
+        raise
+
+
+def load_json(path: Path) -> Optional[Dict[str, Any]]:
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        log_event(LOG, logging.WARNING, "state_unreadable",
+                  path=str(path), error=str(exc))
+        return None
+    if not isinstance(data, dict):
+        log_event(LOG, logging.WARNING, "state_malformed", path=str(path))
+        return None
+    return data
+
+
+def save_json_atomic(path: Path, obj: Dict[str, Any]) -> None:
+    atomic_write_bytes(path, json.dumps(obj, indent=2, default=str).encode("utf-8"))
+
+
+class ProcessLock:
+
+    def __init__(self, path: Path, timeout: float = 30.0) -> None:
+        self.path = path
+        self.timeout = timeout
+        self._handle: Optional[Any] = None
+        self._posix = os.name == "posix"
+
+    def __enter__(self) -> "ProcessLock":
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._handle = open(self.path, "a+")
+        deadline = time.time() + self.timeout
+        while True:
+            try:
+                if self._posix:
+                    import fcntl
+                    fcntl.flock(self._handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                else:
+                    import msvcrt
+                    msvcrt.locking(self._handle.fileno(), msvcrt.LK_NBLCK, 1)
+                return self
+            except ImportError as exc:
+                log_event(LOG, logging.DEBUG, "lock_unsupported", error=str(exc))
+                return self
+            except OSError as exc:
+                if time.time() >= deadline:
+                    self._handle.close()
+                    self._handle = None
+                    raise StateError(
+                        f"another operation holds the lock ({self.path})") from exc
+                time.sleep(0.25)
+
+    def __exit__(self, *exc: Any) -> None:
+        if self._handle is None:
+            return
+        try:
+            if self._posix:
+                import fcntl
+                fcntl.flock(self._handle.fileno(), fcntl.LOCK_UN)
+            else:
+                with contextlib.suppress(OSError):
+                    import msvcrt
+                    self._handle.seek(0)
+                    msvcrt.locking(self._handle.fileno(), msvcrt.LK_UNLCK, 1)
+        finally:
+            self._handle.close()
+            self._handle = None
+
+
+def marker_age_seconds(marker_path: Path, now: Optional[float] = None) -> Optional[float]:
+    try:
+        mtime = marker_path.stat().st_mtime
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+    return max(0.0, (now if now is not None else time.time()) - mtime)
+
+
+def should_run_periodic(marker_path: Path, interval_seconds: float,
+                        now: Optional[float] = None) -> bool:
+    age = marker_age_seconds(marker_path, now)
+    return age is None or age >= interval_seconds
+
+
+def touch_marker(marker_path: Path) -> None:
+    try:
+        marker_path.parent.mkdir(parents=True, exist_ok=True)
+        marker_path.touch(exist_ok=True)
+        os.utime(marker_path, None)
+    except OSError as exc:
+        log_event(LOG, logging.WARNING, "marker_touch_failed",
+                  path=str(marker_path), error=str(exc))