UGOS 1.0.0__py3-none-any.whl

ugos/_dynamic.py

@@ -0,0 +1,221 @@
+"""Dynamic access to every controller action."""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator, Mapping
+from typing import Any, cast
+
+from .exceptions import UGOSError
+
+
+class ActionCaller:
+    """Callable for one exact ``controller/action`` pair."""
+
+    def __init__(
+        self,
+        invoker: Any,
+        controller: str,
+        action: str,
+        *,
+        strict: bool | None = None,
+    ) -> None:
+        self._invoker = invoker
+        self.controller = controller
+        self.action = action
+        self._strict = strict
+
+    def __call__(
+        self,
+        payload: Mapping[str, Any] | None = None,
+        /,
+        *,
+        json_fields: Any = (),
+        method: str | None = None,
+        expect: str | None = None,
+        idempotent: bool | None = None,
+        timeout: Any = None,
+        strict: bool | None = None,
+        **params: Any,
+    ) -> Any:
+        kwargs: dict[str, Any] = {
+            "payload": payload,
+            "json_fields": json_fields,
+            "method": method,
+            "expect": expect,
+            "idempotent": idempotent,
+            "strict": self._strict if strict is None else strict,
+            **params,
+        }
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return self._invoker.call(self.controller, self.action, **kwargs)
+
+    def download(self, **kwargs: Any) -> Any:
+        kwargs.setdefault("strict", self._strict)
+        return self._invoker.download(self.controller, self.action, **kwargs)
+
+    def upload(self, **kwargs: Any) -> Any:
+        kwargs.setdefault("strict", self._strict)
+        return self._invoker.upload(self.controller, self.action, **kwargs)
+
+    def iter_all(self, **kwargs: Any) -> Iterator[Any]:
+        kwargs.setdefault("strict", self._strict)
+        result: Iterator[Any] = self._invoker.iter_all(self.controller, self.action, **kwargs)
+        return result
+
+    def __repr__(self) -> str:
+        return f"ActionCaller({self.controller!r}, {self.action!r})"
+
+
+class ActionNamespace:
+    """Exact action names for a controller."""
+
+    def __init__(
+        self,
+        invoker: Any,
+        controller: str,
+        *,
+        strict: bool | None = None,
+    ) -> None:
+        self._invoker = invoker
+        self._controller = controller
+        self._strict = strict
+
+    def __getattr__(self, name: str) -> ActionCaller:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return ActionCaller(
+            self._invoker,
+            self._controller,
+            name,
+            strict=self._strict,
+        )
+
+    def __getitem__(self, name: str) -> ActionCaller:
+        return ActionCaller(
+            self._invoker,
+            self._controller,
+            name,
+            strict=self._strict,
+        )
+
+    def __repr__(self) -> str:
+        return f"ActionNamespace({self._controller!r})"
+
+
+class ControllerProxy:
+    """Generic proxy for a controller.
+
+    Typed resources inherit from this class, so ``users.list()`` and
+    ``users.UsersList()`` can coexist.
+    """
+
+    controller: str
+
+    def __init__(
+        self,
+        invoker: Any,
+        controller: str | None = None,
+        *,
+        strict: bool | None = None,
+    ) -> None:
+        self._invoker = invoker
+        if controller is not None:
+            self.controller = controller
+        self._strict = strict
+
+    def call(
+        self,
+        action: str,
+        /,
+        *,
+        payload: Mapping[str, Any] | None = None,
+        json_fields: Any = (),
+        method: str | None = None,
+        expect: str | None = None,
+        idempotent: bool | None = None,
+        timeout: Any = None,
+        strict: bool | None = None,
+        **params: Any,
+    ) -> Any:
+        kwargs: dict[str, Any] = {
+            "payload": payload,
+            "json_fields": json_fields,
+            "method": method,
+            "expect": expect,
+            "idempotent": idempotent,
+            "strict": self._strict if strict is None else strict,
+            **params,
+        }
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        return self._invoker.call(self.controller, action, **kwargs)
+
+    def download(self, action: str, /, **kwargs: Any) -> Any:
+        kwargs.setdefault("strict", self._strict)
+        return self._invoker.download(self.controller, action, **kwargs)
+
+    def upload(self, action: str, /, **kwargs: Any) -> Any:
+        kwargs.setdefault("strict", self._strict)
+        return self._invoker.upload(self.controller, action, **kwargs)
+
+    def iter_all(self, action: str, /, **kwargs: Any) -> Iterator[Any]:
+        kwargs.setdefault("strict", self._strict)
+        result: Iterator[Any] = self._invoker.iter_all(self.controller, action, **kwargs)
+        return result
+
+    @property
+    def actions(self) -> ActionNamespace:
+        return ActionNamespace(self._invoker, self.controller, strict=self._strict)
+
+    @staticmethod
+    def _known_actions(invoker: Any, controller: str) -> frozenset[str] | None:
+        try:
+            return invoker.available_actions(controller)
+        except UGOSError:
+            return None
+
+    @staticmethod
+    def _is_reserved(name: str) -> bool:
+        return name.startswith("_") or name == "controller"
+
+    @staticmethod
+    def _missing_context(invoker: Any, controller: str | None) -> bool:
+        return invoker is None or controller is None
+
+    def _raise_if_unknown(self, name: str, invoker: Any, controller: str) -> None:
+        known = self._known_actions(invoker, controller)
+        if known is not None and name not in known:
+            raise AttributeError(f"unknown action {name!r} for controller {controller!r}")
+
+    def _validate_attr(self, name: str, invoker: Any, controller: str | None) -> None:
+        if self._is_reserved(name):
+            raise AttributeError(name)
+        if self._missing_context(invoker, controller):
+            raise AttributeError(name)
+        if self.__dict__.get("_strict") is False:
+            return
+        self._raise_if_unknown(name, invoker, cast(str, controller))
+
+    def __getattr__(self, name: str) -> ActionCaller:
+        invoker = self.__dict__.get("_invoker")
+        controller = self.__dict__.get("controller")
+        self._validate_attr(name, invoker, controller)
+        if invoker is None or controller is None:  # pragma: no cover - checked above
+            raise AttributeError(name)
+        return ActionCaller(
+            invoker,
+            controller,
+            name,
+            strict=self.__dict__.get("_strict"),
+        )
+
+    def __dir__(self) -> list[str]:
+        names = set(super().__dir__())
+        with contextlib.suppress(UGOSError):
+            names.update(self._invoker.available_actions(self.controller))
+        return sorted(names)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(controller={self.controller!r})"

ugos/_encoding.py

@@ -0,0 +1,159 @@
+"""Form encoding used by the web console."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from collections.abc import Collection, Iterable, Mapping
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+from urllib.parse import quote, urlencode
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, os.PathLike):
+        return str(os.fspath(value))
+    raise TypeError(f"value of type {type(value).__name__} is not JSON serializable")
+
+
+def _format_float(value: float, key: str) -> str:
+    if math.isnan(value) or math.isinf(value):
+        raise ValueError(f"parameter {key!r} must be a finite number")
+    return repr(value)
+
+
+def _scalar_complex(value: Any, key: str) -> str:
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, Enum):
+        return _scalar(value.value, key)
+    if isinstance(value, os.PathLike):
+        return str(os.fspath(value))
+    raise TypeError(f"parameter {key!r} has unsupported type {type(value).__name__}")
+
+
+def _scalar_text(value: Any) -> str | None:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def _scalar_number(value: Any, key: str) -> str | None:
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return _format_float(value, key)
+    return None
+
+
+def _scalar_simple(value: Any, key: str) -> str | None:
+    text = _scalar_text(value)
+    if text is not None:
+        return text
+    return _scalar_number(value, key)
+
+
+def _scalar(value: Any, key: str) -> str:
+    simple = _scalar_simple(value, key)
+    if simple is not None:
+        return simple
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    return _scalar_complex(value, key)
+
+
+def _json_dumps(value: Any) -> str:
+    return json.dumps(value, default=_json_default, ensure_ascii=False, separators=(",", ":"))
+
+
+def _encode_none(key: str, none: str) -> list[tuple[str, str]]:
+    if none == "omit":
+        return []
+    return [(key, "" if none == "empty" else "null")]
+
+
+def _sequence_as_json(values: list[Any], list_mode: str) -> bool:
+    if list_mode == "json":
+        return True
+    return any(isinstance(item, (Mapping, list, tuple, set, frozenset)) for item in values)
+
+
+def _encode_sequence(
+    key: str,
+    value: Any,
+    list_mode: str,
+) -> list[tuple[str, str]]:
+    values = list(value)
+    if _sequence_as_json(values, list_mode):
+        return [(key, _json_dumps(values))]
+    return [(key, _scalar(item, key)) for item in values if item is not None]
+
+
+def _encode_value(
+    key: str,
+    value: Any,
+    json_fields: Collection[str],
+    none: str,
+    list_mode: str,
+) -> list[tuple[str, str]]:
+    if value is None:
+        return _encode_none(key, none)
+    if key in json_fields:
+        return [(key, _json_dumps(value))]
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return _encode_sequence(key, value, list_mode)
+    if isinstance(value, Mapping):
+        return [(key, _json_dumps(value))]
+    return [(key, _scalar(value, key))]
+
+
+def encode_pairs(
+    params: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None,
+    *,
+    json_fields: Collection[str] = (),
+    none: str = "omit",
+    list_mode: str = "repeat",
+) -> list[tuple[str, str]]:
+    """Convert Python values into form pairs.
+
+    Scalars become strings, booleans become ``true``/``false``, lists are sent
+    as repeated keys, and mappings are JSON encoded.  ``json_fields`` forces
+    JSON encoding for individual keys.
+    """
+
+    if params is None:
+        return []
+    source: Iterable[tuple[str, Any]] = params.items() if isinstance(params, Mapping) else params
+    pairs: list[tuple[str, str]] = []
+    for raw_key, value in source:
+        pairs.extend(_encode_value(str(raw_key), value, json_fields, none, list_mode))
+    return pairs
+
+
+def encode_params(
+    params: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None,
+    *,
+    json_fields: Collection[str] = (),
+    none: str = "omit",
+    list_mode: str = "repeat",
+) -> str:
+    """Return an ``application/x-www-form-urlencoded`` body."""
+
+    pairs = encode_pairs(
+        params,
+        json_fields=json_fields,
+        none=none,
+        list_mode=list_mode,
+    )
+    return urlencode(pairs, doseq=False, quote_via=quote)

ugos/_pagination.py

@@ -0,0 +1,158 @@
+"""Pagination helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from .exceptions import UGOSError
+from .models.common import ListResult
+
+
+def _stable_key(item: Any) -> str | None:
+    if isinstance(item, dict):
+        for key in ("id", "guid"):
+            value = item.get(key)
+            if value is not None and value != "":
+                return f"{key}:{value!r}"
+    return None
+
+
+def _validate_sizes(page_size: int, start: int, max_pages: int) -> None:
+    if page_size <= 0:
+        raise ValueError("page_size must be positive")
+    if start < 0:
+        raise ValueError("start must be non-negative")
+    if max_pages <= 0:
+        raise ValueError("max_pages must be positive")
+
+
+def _validate_max_items(max_items: int | None) -> None:
+    if max_items is not None and max_items < 0:
+        raise ValueError("max_items must be non-negative")
+
+
+def _validate_reserved(params: dict[str, Any]) -> None:
+    for reserved in ("start", "limit"):
+        if reserved in params:
+            raise ValueError(f"{reserved!r} is managed by iter_all")
+
+
+def _page_signature(items: list[Any]) -> tuple[str, ...]:
+    return tuple(_stable_key(item) or f"repr:{item!r}" for item in items)
+
+
+def _record_page(signature: tuple[str, ...], seen_pages: set[tuple[str, ...]]) -> bool:
+    if signature in seen_pages:
+        return False
+    seen_pages.add(signature)
+    return True
+
+
+def _max_reached(max_items: int | None, yielded: int, accepted: int) -> bool:
+    return max_items is not None and yielded + accepted >= max_items
+
+
+def _should_take_item(
+    item: Any,
+    seen_items: set[str],
+    max_items: int | None,
+    yielded: int,
+    accepted: int,
+) -> bool:
+    if _max_reached(max_items, yielded, accepted):
+        return False
+    key = _stable_key(item)
+    if key is not None and key in seen_items:
+        return False
+    if key is not None:
+        seen_items.add(key)
+    return True
+
+
+def _new_items(
+    items: list[Any],
+    seen_items: set[str],
+    max_items: int | None,
+    yielded: int,
+) -> list[Any]:
+    result: list[Any] = []
+    for item in items:
+        if not _should_take_item(item, seen_items, max_items, yielded, len(result)):
+            break
+        result.append(item)
+    return result
+
+
+def _reached_total(result: ListResult[Any], yielded: int) -> bool:
+    return result.total is not None and yielded >= result.total
+
+
+def _process_page(
+    result: ListResult[Any],
+    seen_pages: set[tuple[str, ...]],
+    seen_items: set[str],
+    max_items: int | None,
+    yielded: int,
+) -> tuple[list[Any], bool]:
+    if not result.items:
+        return [], True
+    if not _record_page(_page_signature(result.items), seen_pages):
+        return [], True
+    new_items = _new_items(result.items, seen_items, max_items, yielded)
+    if not new_items:
+        return [], True
+    if _max_reached(max_items, yielded, len(new_items)):
+        return new_items, True
+    return new_items, _reached_total(result, yielded + len(new_items))
+
+
+def paginate(
+    invoker: Any,
+    controller: str,
+    action: str,
+    *,
+    page_size: int = 100,
+    start: int = 0,
+    max_items: int | None = None,
+    max_pages: int = 1000,
+    strict: bool | None = None,
+    **params: Any,
+) -> Iterator[Any]:
+    """Yield items page by page.
+
+    Stops on an empty page or when a page repeats.  The latter protects
+    against actions such as ``netzones/ZonesList`` that ignore ``start``.
+    """
+
+    _validate_sizes(page_size, start, max_pages)
+    _validate_max_items(max_items)
+    if max_items == 0:
+        return
+    _validate_reserved(params)
+
+    seen_pages: set[tuple[str, ...]] = set()
+    seen_items: set[str] = set()
+    current = start
+    yielded = 0
+    pages = 0
+
+    while pages < max_pages:
+        pages += 1
+        data = invoker.call(
+            controller,
+            action,
+            start=current,
+            limit=page_size,
+            strict=strict,
+            **params,
+        )
+        result: ListResult[Any] = ListResult.from_response(data)
+        new_items, stop = _process_page(result, seen_pages, seen_items, max_items, yielded)
+        yield from new_items
+        yielded += len(new_items)
+        if stop:
+            return
+        current += len(result.items)
+
+    raise UGOSError(f"pagination limit exceeded for {controller}/{action}")

ugos/_redaction.py

@@ -0,0 +1,158 @@
+"""Helpers that keep secrets out of logs and ``repr()`` output."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any
+
+_SENSITIVE_PARTS = {
+    "password",
+    "passwd",
+    "pwd",
+    "secret",
+    "token",
+    "csrfmiddlewaretoken",
+    "session",
+    "cookie",
+    "authorization",
+    "api",
+    "key",
+    "privatekey",
+    "licensekey",
+    "accesskey",
+    "credential",
+    "credentials",
+}
+_SENSITIVE_WORDS = (
+    "password|passwd|pwd|secret|token|csrfmiddlewaretoken|csrf_token|"
+    "auth_token|session|session_id|_console_session|api_key|apikey|"
+    "private_key|license_key|access_key|authorization|cookie"
+)
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+
+_TEXT_PATTERNS = (
+    (re.compile(r"(CSRF_TOKEN\s*=\s*['\"])[^'\"]+(['\"])", re.IGNORECASE), r"\1***\2"),
+    (re.compile(r"(csrfmiddlewaretoken=)[^&\s]+", re.IGNORECASE), r"\1***"),
+    (re.compile(r"(_console_session=)[^;\s]+", re.IGNORECASE), r"\1***"),
+    (
+        re.compile(
+            rf'("[\w.-]*(?:{_SENSITIVE_WORDS})[\w.-]*"\s*:\s*")[^"]+(")',
+            re.IGNORECASE,
+        ),
+        r"\1***\2",
+    ),
+    (
+        re.compile(
+            rf"('[\w.-]*(?:{_SENSITIVE_WORDS})[\w.-]*'\s*:\s*')[^']+(')",
+            re.IGNORECASE,
+        ),
+        r"\1***\2",
+    ),
+    (
+        re.compile(
+            r"((?:password|passwd|secret|token|api[_-]?key|license[_-]?key)"
+            r"\s*[:=]\s*['\"])[^'\"]+(['\"])",
+            re.IGNORECASE,
+        ),
+        r"\1***\2",
+    ),
+    (
+        re.compile(
+            r"((?:password|passwd|secret|token|api[_-]?key|license[_-]?key)"
+            r"\s*[:=]\s*)[^\s,;]+",
+            re.IGNORECASE,
+        ),
+        r"\1***",
+    ),
+    (
+        re.compile(r"(authorization\s*[:=]\s*)(?:bearer\s+)?[^\s,;]+", re.IGNORECASE),
+        r"\1***",
+    ),
+    (
+        re.compile(r"((?:set-)?cookie\s*[:=]\s*)[^\s,;]+", re.IGNORECASE),
+        r"\1***",
+    ),
+    (
+        re.compile(
+            r"([?&](?:api[_-]?key|apikey|token|password|secret|session_id|access_token)=)[^&\s]+",
+            re.IGNORECASE,
+        ),
+        r"\1***",
+    ),
+    (
+        re.compile(
+            r'(name=["\']?(?:csrfmiddlewaretoken|password|passwd|secret|token)'
+            r'["\']?[^>]*value=["\'])[^"\']+(["\'])',
+            re.IGNORECASE,
+        ),
+        r"\1***\2",
+    ),
+)
+
+
+def _key_parts(key: object) -> list[str]:
+    text = _CAMEL_BOUNDARY.sub("_", str(key))
+    normalized = re.sub(r"[^A-Za-z0-9]+", "_", text).strip("_").lower()
+    return [part for part in normalized.split("_") if part]
+
+
+def is_sensitive_key(key: object) -> bool:
+    parts = _key_parts(key)
+    return bool(set(parts) & _SENSITIVE_PARTS)
+
+
+def redact_value(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return redact_mapping(value)
+    if isinstance(value, (list, tuple)):
+        return [redact_value(item) for item in value]
+    if isinstance(value, str):
+        return redact_text(value)
+    return value
+
+
+def redact_mapping(data: Mapping[Any, Any]) -> dict[Any, Any]:
+    result: dict[Any, Any] = {}
+    for key, value in data.items():
+        if is_sensitive_key(key):
+            result[key] = "***"
+        else:
+            result[key] = redact_value(value)
+    return result
+
+
+def redact_text(text: str) -> str:
+    stripped = text.lstrip()
+    if stripped.startswith(("{", "[")):
+        try:
+            payload = json.loads(text)
+        except json.JSONDecodeError:
+            pass
+        else:
+            return json.dumps(redact_value(payload), ensure_ascii=False)
+    result = text
+    for pattern, replacement in _TEXT_PATTERNS:
+        result = pattern.sub(replacement, result)
+    return result
+
+
+def redact_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    allowed = {
+        "content-type",
+        "content-length",
+        "content-disposition",
+        "accept",
+        "location",
+        "retry-after",
+        "x-requested-with",
+    }
+    result: dict[str, str] = {}
+    for key, value in headers.items():
+        lower = key.lower()
+        if lower in allowed:
+            result[key] = redact_text(value)
+        elif lower in {"set-cookie", "cookie", "authorization"}:
+            result[key] = "***"
+    return result