hushscript 1.0.0__py3-none-any.whl

hushscript/_clock.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    import threading
+
+
+class Clock(Protocol):
+    """Time source for pacing, backoff and polling; tests and the runner inject their own."""
+
+    def now(self) -> float: ...
+
+    def sleep(self, seconds: float) -> None: ...
+
+    def wait(self, stop: threading.Event, seconds: float) -> bool:
+        """Sleeps up to `seconds` but wakes as soon as `stop` is set; True when it was set."""
+        ...
+
+    async def asleep(self, seconds: float) -> None: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.monotonic()
+
+    def sleep(self, seconds: float) -> None:
+        time.sleep(seconds)
+
+    def wait(self, stop: threading.Event, seconds: float) -> bool:
+        return stop.wait(seconds)
+
+    async def asleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)

hushscript/_config.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+from urllib.parse import urlsplit
+
+from ._errors import ConfigurationError
+from ._log import LOG_LEVELS
+from ._redact import Credentials
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+DEFAULT_BASE_URL: Final = "https://api.hushscript.com"
+DEFAULT_TIMEOUT: Final = 60.0
+PART_TIMEOUT: Final = 300.0
+DEFAULT_MAX_RETRIES: Final = 3
+TOKEN_ENV: Final = "HUSHSCRIPT_TOKEN"  # noqa: S105  # the name of an environment variable
+BASE_URL_ENV: Final = "HUSHSCRIPT_BASE_URL"
+LOG_ENV: Final = "HUSHSCRIPT_LOG"
+TOKEN_PREFIX: Final = "hsr"  # noqa: S105  # the token family prefix, not a secret
+PRINTABLE_FIRST: Final = 0x21
+PRINTABLE_LAST: Final = 0x7E
+LOOPBACK_HOSTS: Final = frozenset({"localhost", "127.0.0.1", "::1"})
+
+SETUP_HINT: Final = (
+    "Set HUSHSCRIPT_TOKEN or pass a token. Create one in the Hushscript app: "
+    "Account → MCP (app.hushscript.com/account/mcp)."
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    credentials: Credentials
+    base_url: str
+    timeout: float
+    max_retries: int
+    log_level: str
+
+
+def _set(value: str | None) -> str | None:
+    """R85: None, "" and whitespace-only text all mean "not set"."""
+    return value if value is not None and value.strip() else None
+
+
+def _validate_base_url(raw: str) -> str:
+    parts = urlsplit(raw)
+    if parts.path not in {"", "/"} or "?" in raw or "#" in raw:
+        # Requests are classified by their path relative to the base URL (spec 7.4), so it has none.
+        raise ConfigurationError("base_url must not have a path, query or fragment.")
+    host = parts.hostname or ""
+    secure = parts.scheme == "https"
+    loopback = parts.scheme == "http" and host in LOOPBACK_HOSTS
+    if not (secure or loopback) or not host or parts.username or parts.password:
+        raise ConfigurationError(
+            "base_url must be https://, or http:// to localhost, 127.0.0.1 or [::1]."
+        )
+    return raw.rstrip("/")
+
+
+def _is_positive_number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0
+
+
+def _is_non_negative_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+def acceptable_token(token: str) -> bool:
+    """The check every token passes, at construction and after a claim or a rotation: printable
+    ASCII only, and the `hsr` prefix."""
+    return token.startswith(TOKEN_PREFIX) and all(
+        PRINTABLE_FIRST <= ord(char) <= PRINTABLE_LAST for char in token
+    )
+
+
+def resolve_tokenless_config(  # mirrors the keyword surface of the static agent calls
+    *,
+    base_url: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT,
+    log_level: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Config:
+    """The config of a call that needs no token: HUSHSCRIPT_TOKEN is neither read nor sent."""
+    environment = os.environ if env is None else env
+    resolved_url = _validate_base_url(
+        _set(base_url) or _set(environment.get(BASE_URL_ENV)) or DEFAULT_BASE_URL
+    )
+    if not _is_positive_number(timeout):
+        raise ConfigurationError("timeout must be a positive number of seconds.")
+    level = _set(log_level) or _set(environment.get(LOG_ENV)) or "off"
+    if level not in LOG_LEVELS:
+        raise ConfigurationError(f"log_level must be one of {', '.join(LOG_LEVELS)}.")
+    return Config(
+        credentials=Credentials(),
+        base_url=resolved_url,
+        timeout=float(timeout),
+        max_retries=0,
+        log_level=level,
+    )
+
+
+def resolve_config(  # mirrors the public constructor
+    token: str | None = None,
+    *,
+    base_url: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    log_level: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Config:
+    environment = os.environ if env is None else env
+    chosen_token = _set(token) or _set(environment.get(TOKEN_ENV))
+    if chosen_token is None:
+        raise ConfigurationError("No Hushscript token was provided.", hint=SETUP_HINT)
+    resolved_token = chosen_token.strip()
+    if any(not PRINTABLE_FIRST <= ord(char) <= PRINTABLE_LAST for char in resolved_token):
+        # The message never echoes the token (spec 7.4).
+        raise ConfigurationError("The token contains control or non-printable characters.")
+    if not resolved_token.startswith(TOKEN_PREFIX):
+        raise ConfigurationError("This doesn't look like a Hushscript token.")
+    resolved_url = _validate_base_url(
+        _set(base_url) or _set(environment.get(BASE_URL_ENV)) or DEFAULT_BASE_URL
+    )
+    if not _is_positive_number(timeout):
+        raise ConfigurationError("timeout must be a positive number of seconds.")
+    if not _is_non_negative_int(max_retries):
+        raise ConfigurationError("max_retries must be a non-negative integer.")
+    level = _set(log_level) or _set(environment.get(LOG_ENV)) or "off"
+    if level not in LOG_LEVELS:
+        raise ConfigurationError(f"log_level must be one of {', '.join(LOG_LEVELS)}.")
+    return Config(
+        credentials=Credentials(resolved_token),
+        base_url=resolved_url,
+        timeout=float(timeout),
+        max_retries=max_retries,
+        log_level=level,
+    )