contextbase-shared-plugins 0.0.0a1__py3-none-any.whl

shared_plugins/values.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+
+
+def as_mapping(value: object) -> Mapping[str, Any] | None:
+    if not isinstance(value, Mapping):
+        return None
+    return value
+
+
+def as_string(value: object) -> str | None:
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def non_empty_string(value: object) -> str | None:
+    text = as_string(value)
+    if text is None:
+        return None
+    stripped = text.strip()
+    return stripped or None
+
+
+def coerce_non_empty_string_mapping(value: object) -> dict[str, str]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise ValueError(
+            "Expected a mapping of non-empty string keys to non-empty string values."
+        )
+
+    mapping: dict[str, str] = {}
+    for key, raw_value in value.items():
+        if not isinstance(key, str) or key == "" or key != key.strip():
+            raise ValueError(
+                "Expected a mapping of non-empty string keys to non-empty string values."
+            )
+        if (
+            not isinstance(raw_value, str)
+            or raw_value == ""
+            or raw_value != raw_value.strip()
+        ):
+            raise ValueError(
+                "Expected a mapping of non-empty string keys to non-empty string values."
+            )
+        mapping[key] = raw_value
+    return mapping
+
+
+def load_json_value(value: object) -> Any:
+    if isinstance(value, (dict, list)):
+        return value
+    if isinstance(value, str):
+        return json.loads(value)
+    return None
+
+
+def require_non_empty_text(
+    value: object,
+    *,
+    label: str,
+    context: str = "payload",
+) -> str:
+    if isinstance(value, str):
+        text = value.strip() or None
+    elif value is None:
+        text = None
+    else:
+        text = str(value).strip() or None
+    if text is None:
+        raise RuntimeError(f"{context} is missing required field '{label}'.")
+    return text
+
+
+def require_non_negative_int(
+    value: object,
+    *,
+    message: str = "must be a non-negative integer",
+) -> int:
+    if value is None or isinstance(value, bool):
+        raise ValueError(message)
+    if isinstance(value, int):
+        if value >= 0:
+            return value
+        raise ValueError(message)
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped == "":
+            raise ValueError(message)
+        try:
+            parsed = int(stripped)
+        except ValueError as exc:
+            raise ValueError(message) from exc
+        if parsed >= 0:
+            return parsed
+    raise ValueError(message)
+
+
+def parse_utc_datetime_from_str(value: str) -> datetime | None:
+    if not isinstance(value, str):
+        raise TypeError(f"Expected str, got {type(value).__name__}")
+
+    text = value.strip()
+    if not text:
+        return None
+
+    normalized = f"{text[:-1]}+00:00" if text.endswith("Z") else text
+    parsed = datetime.fromisoformat(normalized)
+
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)