statoss 0.1.0__py3-none-any.whl

statoss/__init__.py

@@ -0,0 +1,60 @@
+"""Error tracking for StatOSS: sentry-sdk with the app's own levels, categories and fields."""
+
+from sentry_sdk import add_breadcrumb, flush, set_context, set_tag, set_user
+
+from ._client import (
+    Client,
+    FieldValue,
+    capture_exception,
+    capture_message,
+    init,
+    set_category,
+)
+from ._schema import (
+    CATEGORY_TAG,
+    LEVEL_TAG,
+    Category,
+    Field,
+    FieldType,
+    Level,
+    Like,
+    Rule,
+    RuleMatch,
+    RuleSubject,
+    Schema,
+    SchemaColor,
+    SchemaError,
+    SentryLevel,
+    define_schema,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CATEGORY_TAG",
+    "LEVEL_TAG",
+    "Category",
+    "Client",
+    "Field",
+    "FieldType",
+    "FieldValue",
+    "Level",
+    "Like",
+    "Rule",
+    "RuleMatch",
+    "RuleSubject",
+    "Schema",
+    "SchemaColor",
+    "SchemaError",
+    "SentryLevel",
+    "add_breadcrumb",
+    "capture_exception",
+    "capture_message",
+    "define_schema",
+    "flush",
+    "init",
+    "set_category",
+    "set_context",
+    "set_tag",
+    "set_user",
+]

statoss/_client.py

@@ -0,0 +1,284 @@
+"""init and the capture functions: sentry-sdk's, with StatOSS levels and categories.
+
+On the wire an event carries the nearest Sentry level, its own level as the
+tag statoss.level and its category as statoss.category, as @statoss/sdk
+sends them (sdk/src/levels.ts), so any Sentry-compatible tool reads it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Mapping,
+    Optional,
+    Tuple,
+    Union,
+    overload,
+)
+
+import sentry_sdk
+
+from ._schema import (
+    BUILTIN_LEVELS,
+    CATEGORY_TAG,
+    LEVEL_TAG,
+    SENTRY_LEVELS,
+    C,
+    L,
+    Schema,
+    SentryLevel,
+    is_category_name,
+    is_level_name,
+)
+
+logger = logging.getLogger("statoss")
+
+FieldValue = Union[str, int, float, bool, None]
+"""A field's value; it travels as a tag, so as text."""
+
+Error = Union[BaseException, Tuple[Any, Any, Any], None]
+
+
+def _debug() -> bool:
+    try:
+        return bool(sentry_sdk.get_client().options.get("debug"))
+    except Exception:
+        return False
+
+
+def _warn(message: str, *args: object) -> None:
+    if _debug():
+        logger.warning(message, *args)
+
+
+def _tag_text(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return value if isinstance(value, str) else str(value)
+
+
+class Client(Generic[L, C]):
+    """The capture functions, typed by a schema's level and category names.
+
+    `init` hands one back. With a schema made as
+    `Schema[Literal["payment-failed"], Literal["billing"]]`, a type checker
+    refuses `level="payment-faild"`.
+    """
+
+    def __init__(self, schema: Optional[Schema[L, C]] = None) -> None:
+        self.schema = schema
+
+    def _level(self, level: Optional[str]) -> Tuple[Optional[str], Dict[str, str]]:
+        """The Sentry level to send, and the tag naming the app's own level."""
+        if level is None:
+            return None, {}
+        if not is_level_name(level) and level not in SENTRY_LEVELS:
+            _warn(
+                "Ignored level %r: use a Sentry level or 1 to 32 lowercase letters, "
+                "digits, dots, dashes or underscores.",
+                level,
+            )
+            return None, {}
+        if level in BUILTIN_LEVELS:
+            return level, {}
+        schema = self.schema
+        sent_as = schema.sentry_level(level) if schema is not None else None
+        if sent_as is not None:
+            return sent_as, {LEVEL_TAG: level}
+        if level in SENTRY_LEVELS:
+            return level, {}
+        if schema is not None:
+            _warn("Level %r is not in the schema, so it is sent as error.", level)
+        return "error", {LEVEL_TAG: level}
+
+    def _tags(
+        self,
+        level: Optional[str],
+        category: Optional[str],
+        fields: Optional[Mapping[str, FieldValue]],
+    ) -> Tuple[Optional[str], Dict[str, str]]:
+        tags: Dict[str, str] = {}
+        for key, value in (fields or {}).items():
+            if not isinstance(key, str) or key == "" or key.startswith("statoss."):
+                _warn("Ignored field %r: a field is a tag key not starting statoss.", key)
+            elif value is not None:
+                tags[key] = _tag_text(value)
+        sentry_level, level_tags = self._level(level)
+        tags.update(level_tags)
+        name = self._category(category)
+        if name is not None:
+            tags[CATEGORY_TAG] = name
+        return sentry_level, tags
+
+    def _category(self, category: Optional[str]) -> Optional[str]:
+        if category is None:
+            return None
+        if not is_category_name(category):
+            _warn(
+                "Ignored category %r: use 1 to 64 lowercase letters, digits, dots, "
+                "dashes or underscores.",
+                category,
+            )
+            return None
+        schema = self.schema
+        if schema is not None and category not in schema.categories:
+            _warn("Category %r is not in the schema; it is sent all the same.", category)
+        return category
+
+    def capture_exception(
+        self,
+        error: Error = None,
+        level: Union[L, SentryLevel, None] = None,
+        category: Optional[C] = None,
+        fields: Optional[Mapping[str, FieldValue]] = None,
+        **scope_kwargs: Any,
+    ) -> Optional[str]:
+        """sentry_sdk.capture_exception with a level, a category and fields.
+
+        Without an error, the one being handled is captured. Returns the
+        event id, or None when nothing was sent.
+        """
+        sentry_level, tags = self._tags(level, category, fields)
+        return sentry_sdk.capture_exception(error, **_with(scope_kwargs, sentry_level, tags))
+
+    def capture_message(
+        self,
+        message: str,
+        level: Union[L, SentryLevel, None] = None,
+        category: Optional[C] = None,
+        fields: Optional[Mapping[str, FieldValue]] = None,
+        **scope_kwargs: Any,
+    ) -> Optional[str]:
+        """sentry_sdk.capture_message with a level, a category and fields."""
+        sentry_level, tags = self._tags(level, category, fields)
+        return sentry_sdk.capture_message(message, **_with(scope_kwargs, sentry_level, tags))
+
+    def set_category(self, category: Optional[C], scope: Optional[sentry_sdk.Scope] = None) -> None:
+        """Gives later events a category: on `scope`, else the isolation scope
+        as sentry_sdk.set_tag does. None takes it off."""
+        target = scope if scope is not None else sentry_sdk.Scope.get_isolation_scope()
+        if category is None:
+            target.remove_tag(CATEGORY_TAG)
+            return
+        name = self._category(category)
+        if name is not None:
+            target.set_tag(CATEGORY_TAG, name)
+
+    def _before_send(self, event: Dict[str, Any], hint: Any) -> Dict[str, Any]:
+        """Sends an event whose level is one of the schema's own (as
+        scope.set_level or sentry_sdk.capture_message can leave it) as its
+        Sentry level with the statoss.level tag."""
+        level = event.get("level")
+        schema = self.schema
+        if isinstance(level, str) and schema is not None:
+            sent_as = schema.sentry_level(level)
+            if sent_as is not None:
+                event["level"] = sent_as
+                tags = event.get("tags")
+                event["tags"] = {**(tags if isinstance(tags, dict) else {}), LEVEL_TAG: level}
+        return event
+
+
+def _with(
+    scope_kwargs: Dict[str, Any], level: Optional[str], tags: Dict[str, str]
+) -> Dict[str, Any]:
+    """The caller's scope arguments with the level and tags put last.
+
+    They go on through a scope callback, which sentry-sdk applies to the
+    event's scope after the current ones, so the level given here wins
+    over one set on a scope, as in @statoss/sdk.
+    """
+    if level is None and not tags:
+        return scope_kwargs
+    kwargs = dict(scope_kwargs)
+    scope = kwargs.pop("scope", None)
+    if scope is not None and kwargs:
+        raise TypeError("cannot provide scope and kwargs")
+
+    def apply(final: sentry_sdk.Scope) -> None:
+        if scope is None:
+            final.update_from_kwargs(**kwargs)
+        elif callable(scope):
+            scope(final)
+        else:
+            final.update_from_scope(scope)
+        final.update_from_kwargs(level=level, tags=tags)  # type: ignore[arg-type]
+
+    return {"scope": apply}
+
+
+_current: Client[Any, Any] = Client()
+
+
+@overload
+def init(
+    dsn: Optional[str] = None, schema: None = None, **sentry_options: Any
+) -> Client[str, str]: ...
+@overload
+def init(dsn: Optional[str], schema: Schema[L, C], **sentry_options: Any) -> Client[L, C]: ...
+@overload
+def init(
+    dsn: Optional[str] = None, *, schema: Schema[L, C], **sentry_options: Any
+) -> Client[L, C]: ...
+def init(
+    dsn: Optional[str] = None, schema: Optional[Schema[Any, Any]] = None, **sentry_options: Any
+) -> Client[Any, Any]:
+    """sentry_sdk.init, and the capture functions for the schema's levels.
+
+    The options are sentry-sdk's. The DSN is on the app's setup page in
+    StatOSS: https://<key>@ingest.statoss.com/<app number>.
+    """
+    global _current
+    client: Client[Any, Any] = Client(schema)
+    if schema is not None and schema._sent_as:
+        sentry_options["before_send"] = _then(
+            sentry_options.get("before_send"), client._before_send
+        )
+    sentry_sdk.init(dsn, **sentry_options)
+    _current = client
+    return client
+
+
+def _then(
+    first: Optional[Callable[[Any, Any], Any]], second: Callable[[Any, Any], Any]
+) -> Callable[[Any, Any], Any]:
+    if first is None:
+        return second
+
+    def before_send(event: Any, hint: Any) -> Any:
+        event = first(event, hint)
+        return None if event is None else second(event, hint)
+
+    return before_send
+
+
+def capture_exception(
+    error: Error = None,
+    level: Optional[str] = None,
+    category: Optional[str] = None,
+    fields: Optional[Mapping[str, FieldValue]] = None,
+    **scope_kwargs: Any,
+) -> Optional[str]:
+    """Captures an exception (the one being handled, without one) with a
+    level, a category and fields. Returns the event id."""
+    return _current.capture_exception(error, level, category, fields, **scope_kwargs)
+
+
+def capture_message(
+    message: str,
+    level: Optional[str] = None,
+    category: Optional[str] = None,
+    fields: Optional[Mapping[str, FieldValue]] = None,
+    **scope_kwargs: Any,
+) -> Optional[str]:
+    """Captures a message with a level, a category and fields."""
+    return _current.capture_message(message, level, category, fields, **scope_kwargs)
+
+
+def set_category(category: Optional[str], scope: Optional[sentry_sdk.Scope] = None) -> None:
+    """Gives later events a category; None takes it off."""
+    _current.set_category(category, scope)

statoss/_schema.py

@@ -0,0 +1,468 @@
+"""An app's levels, categories, fields and rules, declared in code.
+
+The shape follows the server's desired schema (readDesired in
+src/lib/app-schema.ts and docs/sdk-and-cli.md), and the checks follow what
+the server accepts, so a schema that passes here passes there.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import (
+    Any,
+    Dict,
+    Generic,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+    get_args,
+)
+
+from typing_extensions import TypeVar
+
+SentryLevel = Literal["fatal", "critical", "error", "warning", "info", "debug"]
+"""The levels sentry-sdk sends. StatOSS reads critical as fatal."""
+
+Like = Literal["fatal", "error", "warning", "info", "debug", "trace"]
+"""OpenTelemetry's six severity ranges, which an app's own level ranks inside."""
+
+SchemaColor = Literal[
+    "crimson",
+    "red",
+    "orange",
+    "amber",
+    "yellow",
+    "green",
+    "aqua",
+    "teal",
+    "blue",
+    "violet",
+    "indigo",
+    "magenta",
+    "plum",
+    "grey",
+]
+
+FieldType = Literal["text", "number"]
+RuleSubject = Literal["tag", "logger", "exception", "culprit", "title", "message"]
+RuleMatch = Literal["is", "starts", "contains"]
+
+SENTRY_LEVELS: Tuple[str, ...] = get_args(SentryLevel)
+LIKES: Tuple[str, ...] = get_args(Like)
+SCHEMA_COLORS: Tuple[str, ...] = get_args(SchemaColor)
+FIELD_TYPES: Tuple[str, ...] = get_args(FieldType)
+RULE_SUBJECTS: Tuple[str, ...] = get_args(RuleSubject)
+RULE_MATCHES: Tuple[str, ...] = get_args(RuleMatch)
+
+LEVEL_TAG = "statoss.level"
+CATEGORY_TAG = "statoss.category"
+
+#: Each range's severity numbers, highest first.
+SEVERITY_RANGES: Dict[str, Tuple[int, int]] = {
+    "fatal": (21, 24),
+    "error": (17, 20),
+    "warning": (13, 16),
+    "info": (9, 12),
+    "debug": (5, 8),
+    "trace": (1, 4),
+}
+
+#: Sentry's five levels: always on the server, with these severities.
+BUILTIN_LEVELS: Dict[str, int] = {
+    "fatal": 21,
+    "error": 17,
+    "warning": 13,
+    "info": 9,
+    "debug": 5,
+}
+
+#: The Sentry level an event of a level ranking like this is sent as.
+NEAREST_SENTRY_LEVEL: Dict[str, str] = {
+    "fatal": "fatal",
+    "error": "error",
+    "warning": "warning",
+    "info": "info",
+    "debug": "debug",
+    "trace": "debug",
+}
+
+KEY_MAX = {"level": 32, "category": 64, "field": 200}
+CAPS = {"level": 50, "category": 200, "field": 300}
+RULES_MAX = 50
+LABEL_MAX = 60
+UNIT_MAX = 16
+OWNER_MAX = 320
+RULE_VALUE_MAX = 200
+
+_LEVEL_NAME = re.compile(r"[a-z0-9._-]{1,32}")
+_CATEGORY_NAME = re.compile(r"[a-z0-9._-]{1,64}")
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+
+# A schema's level and category names; str (any name) unless typed with Literal.
+L = TypeVar("L", bound=str, default=str)
+C = TypeVar("C", bound=str, default=str)
+
+
+class SchemaError(ValueError):
+    """A schema, or a part of one, that StatOSS would refuse."""
+
+
+def is_level_name(value: object) -> bool:
+    """1 to 32 lowercase letters, digits, dots, dashes or underscores."""
+    return isinstance(value, str) and _LEVEL_NAME.fullmatch(value) is not None
+
+
+def is_category_name(value: object) -> bool:
+    """1 to 64 lowercase letters, digits, dots, dashes or underscores."""
+    return isinstance(value, str) and _CATEGORY_NAME.fullmatch(value) is not None
+
+
+def _text(value: object, most: int, what: str) -> None:
+    if value is None:
+        return
+    if not isinstance(value, str):
+        raise SchemaError(f"{what} must be text, not {type(value).__name__}.")
+    text = value.strip()
+    if text == "":
+        raise SchemaError(f"{what} is empty; leave it out instead.")
+    if len(text) > most:
+        raise SchemaError(f"{what} is at most {most} characters.")
+    if _CONTROL.search(text):
+        raise SchemaError(f"{what} has a control character.")
+
+
+def _one_of(value: object, options: Tuple[str, ...], what: str, required: bool = False) -> None:
+    if (value is not None or required) and value not in options:
+        raise SchemaError(f"{what} must be one of {', '.join(options)}; got {value!r}.")
+
+
+def _flag(value: object, what: str) -> None:
+    if value is not None and not isinstance(value, bool):
+        raise SchemaError(f"{what} must be True or False.")
+
+
+def _range_of(severity: int) -> str:
+    for like, (low, high) in SEVERITY_RANGES.items():
+        if low <= severity <= high:
+            return like
+    return "error"
+
+
+@dataclass(frozen=True)
+class Level:
+    """A level of the app's own: the range it ranks like, and how it reads."""
+
+    like: Optional[Like] = None
+    label: Optional[str] = None
+    color: Optional[SchemaColor] = None
+    #: OpenTelemetry's severity number, 1 to 24, inside the range of `like`.
+    severity: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        _one_of(self.like, LIKES, "Level like")
+        _text(self.label, LABEL_MAX, "Level label")
+        _one_of(self.color, SCHEMA_COLORS, "Level color")
+        s = self.severity
+        if s is not None:
+            if isinstance(s, bool) or not isinstance(s, int) or not 1 <= s <= 24:
+                raise SchemaError("Level severity must be a whole number from 1 to 24.")
+            if self.like is not None and _range_of(s) != self.like:
+                low, high = SEVERITY_RANGES[self.like]
+                raise SchemaError(
+                    f"Level severity {s} is not in the {self.like} range; "
+                    f"{self.like} runs {low} to {high}."
+                )
+
+    @property
+    def ranks_like(self) -> Optional[str]:
+        """The range it ranks in: `like`, else the range of `severity`."""
+        if self.like is not None:
+            return self.like
+        if self.severity is not None:
+            return _range_of(self.severity)
+        return None
+
+    def to_desired(self) -> Dict[str, Any]:
+        return _given(like=self.like, label=self.label, color=self.color, severity=self.severity)
+
+
+@dataclass(frozen=True)
+class Category:
+    """A category: how it reads, who owns it, and whether lists show it."""
+
+    label: Optional[str] = None
+    color: Optional[SchemaColor] = None
+    hidden: Optional[bool] = None
+    #: A team member's email.
+    owner: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        _text(self.label, LABEL_MAX, "Category label")
+        _one_of(self.color, SCHEMA_COLORS, "Category color")
+        _flag(self.hidden, "Category hidden")
+        _text(self.owner, OWNER_MAX, "Category owner")
+
+    def to_desired(self) -> Dict[str, Any]:
+        return _given(label=self.label, color=self.color, hidden=self.hidden, owner=self.owner)
+
+
+@dataclass(frozen=True)
+class Field:
+    """A tag key: how it reads, and whether filters offer it."""
+
+    label: Optional[str] = None
+    type: Optional[FieldType] = None
+    unit: Optional[str] = None
+    filterable: Optional[bool] = None
+
+    def __post_init__(self) -> None:
+        _text(self.label, LABEL_MAX, "Field label")
+        _one_of(self.type, FIELD_TYPES, "Field type")
+        _text(self.unit, UNIT_MAX, "Field unit")
+        _flag(self.filterable, "Field filterable")
+
+    def to_desired(self) -> Dict[str, Any]:
+        return _given(label=self.label, type=self.type, unit=self.unit, filterable=self.filterable)
+
+
+@dataclass(frozen=True)
+class Rule:
+    """Sets a level, a category or both on events where one thing matches.
+
+    `subject` is what is tested: a tag (named by `tag_key`), the logger, the
+    exception type, the culprit, the title or the message.
+    """
+
+    subject: RuleSubject
+    value: str
+    match: RuleMatch = "is"
+    level: Optional[str] = None
+    category: Optional[str] = None
+    tag_key: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        _one_of(self.subject, RULE_SUBJECTS, "Rule subject", required=True)
+        _one_of(self.match, RULE_MATCHES, "Rule match", required=True)
+        if self.value is None:
+            raise SchemaError("Rule value is required.")
+        _text(self.value, RULE_VALUE_MAX, "Rule value")
+        if self.subject == "tag":
+            if self.tag_key is None:
+                raise SchemaError('Rule tag_key is required when the subject is "tag".')
+            _field_key(self.tag_key, "Rule tag_key")
+        elif self.tag_key is not None:
+            raise SchemaError('Rule tag_key is only for the subject "tag".')
+        if self.level is None and self.category is None:
+            raise SchemaError("A rule sets a level, a category or both.")
+        if self.level is not None and not is_level_name(self.level):
+            raise SchemaError(f"Rule level {self.level!r} is not a level name: {_LEVEL_HELP}")
+        if self.category is not None and not is_category_name(self.category):
+            raise SchemaError(
+                f"Rule category {self.category!r} is not a category name: {_CATEGORY_HELP}"
+            )
+
+    def to_desired(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"subject": self.subject}
+        if self.subject == "tag":
+            out["tagKey"] = self.tag_key
+        out["match"] = self.match
+        out["value"] = self.value
+        out.update(_given(level=self.level, category=self.category))
+        return out
+
+
+_LEVEL_HELP = "use 1 to 32 lowercase letters, digits, dots, dashes or underscores."
+_CATEGORY_HELP = "use 1 to 64 lowercase letters, digits, dots, dashes or underscores."
+
+
+def _given(**settings: Any) -> Dict[str, Any]:
+    return {k: v for k, v in settings.items() if v is not None}
+
+
+def _field_key(key: object, what: str) -> None:
+    if not isinstance(key, str):
+        raise SchemaError(f"{what} must be text, not {type(key).__name__}.")
+    if key != key.strip():
+        raise SchemaError(f"{what} {key!r} has spaces around it.")
+    if key == "":
+        raise SchemaError(f"{what} is empty.")
+    if len(key) > KEY_MAX["field"]:
+        raise SchemaError(f"{what} is at most {KEY_MAX['field']} characters.")
+    if _CONTROL.search(key):
+        raise SchemaError(f"{what} has a control character.")
+    if key.startswith("statoss."):
+        raise SchemaError(f"{what} {key!r}: tags starting with statoss. are not fields.")
+
+
+class Schema(Generic[L, C]):
+    """A schema made by `define_schema`. Level names are typed `L`, categories `C`."""
+
+    def __init__(
+        self,
+        levels: Dict[str, Level],
+        categories: Dict[str, Category],
+        fields: Dict[str, Field],
+        rules: Optional[Tuple[Rule, ...]],
+        given: Tuple[bool, bool, bool],
+    ) -> None:
+        self.levels: Mapping[str, Level] = MappingProxyType(levels)
+        self.categories: Mapping[str, Category] = MappingProxyType(categories)
+        self.fields: Mapping[str, Field] = MappingProxyType(fields)
+        #: None when the code says nothing of rules, so the server leaves them be.
+        self.rules = rules
+        self._given = given
+        self._sent_as = {
+            name: NEAREST_SENTRY_LEVEL[level.ranks_like or "error"]
+            for name, level in levels.items()
+            if name not in BUILTIN_LEVELS
+        }
+
+    def sentry_level(self, name: str) -> Optional[str]:
+        """The Sentry level an app's own level is sent as; None for others."""
+        return self._sent_as.get(name)
+
+    def to_desired(self) -> Dict[str, Any]:
+        """The schema as the server's desired state, ready for JSON."""
+        out: Dict[str, Any] = {}
+        has_levels, has_categories, has_fields = self._given
+        if has_levels:
+            out["levels"] = {k: v.to_desired() for k, v in self.levels.items()}
+        if has_categories:
+            out["categories"] = {k: v.to_desired() for k, v in self.categories.items()}
+        if has_fields:
+            out["fields"] = {k: v.to_desired() for k, v in self.fields.items()}
+        if self.rules is not None:
+            out["rules"] = [r.to_desired() for r in self.rules]
+        return out
+
+    def __repr__(self) -> str:
+        return f"Schema({self.to_desired()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Schema) and other.to_desired() == self.to_desired()
+
+    __hash__ = None  # type: ignore[assignment]
+
+
+def define_schema(
+    levels: Optional[Mapping[L, Union[Level, Like]]] = None,
+    categories: Union[Mapping[C, Category], Sequence[C], None] = None,
+    fields: Union[Mapping[str, Field], Sequence[str], None] = None,
+    rules: Optional[Sequence[Rule]] = None,
+) -> Schema[L, C]:
+    """An app's levels, categories, fields and rules, checked as the server checks them.
+
+    A level may be given as the range it ranks like (`"slow-query": "warning"`),
+    categories and fields as a list of names. Raises SchemaError naming the
+    place of the first problem.
+    """
+    level_map = _levels(levels)
+    category_map = _names("category", categories)
+    rule_list = _rules(rules)
+    # A rule names the schema's own levels and categories, as the
+    # TypeScript types require: one it does not hold could not be pruned.
+    for i, rule in enumerate(rule_list or ()):
+        if (
+            rule.level is not None
+            and rule.level not in SENTRY_LEVELS
+            and rule.level not in level_map
+        ):
+            raise SchemaError(f"rules[{i}]: {rule.level!r} is not a level of the schema.")
+        if rule.category is not None and rule.category not in category_map:
+            raise SchemaError(f"rules[{i}]: {rule.category!r} is not a category of the schema.")
+    return Schema(
+        level_map,
+        category_map,
+        _names("field", fields),
+        rule_list,
+        (levels is not None, categories is not None, fields is not None),
+    )
+
+
+def _levels(raw: object) -> Dict[str, Level]:
+    out: Dict[str, Level] = {}
+    if raw is None:
+        return out
+    if not isinstance(raw, Mapping):
+        raise SchemaError(
+            'levels must be a dict of names, such as {"payment-failed": Level(like="error")}.'
+        )
+    if len(raw) > CAPS["level"]:
+        raise SchemaError(f"levels holds at most {CAPS['level']} levels.")
+    for name, value in raw.items():
+        where = f"levels[{name!r}]"
+        if not is_level_name(name):
+            raise SchemaError(f"{where}: not a level name; {_LEVEL_HELP}")
+        if name == "critical":
+            raise SchemaError(f"{where}: critical is sent as a Sentry level and read as fatal.")
+        if isinstance(value, str):
+            if value not in LIKES:
+                raise SchemaError(
+                    f"{where}: like must be one of {', '.join(LIKES)}; got {value!r}."
+                )
+            value = Level(like=value)  # type: ignore[arg-type]
+        elif not isinstance(value, Level):
+            raise SchemaError(f"{where}: give a Level or the range it ranks like, such as 'error'.")
+        if name in BUILTIN_LEVELS:
+            if value.like is not None and value.like != name:
+                raise SchemaError(f"{where}: the built-in level {name} ranks as {name}.")
+            if value.severity is not None and value.severity != BUILTIN_LEVELS[name]:
+                raise SchemaError(
+                    f"{where}: the built-in level {name} keeps severity {BUILTIN_LEVELS[name]}."
+                )
+        elif value.ranks_like is None:
+            raise SchemaError(f"{where}: give like, the range it ranks like ({', '.join(LIKES)}).")
+        out[name] = value
+    return out
+
+
+def _names(kind: str, raw: object) -> Dict[str, Any]:
+    plural = "categories" if kind == "category" else "fields"
+    settings_type = Category if kind == "category" else Field
+    out: Dict[str, Any] = {}
+    if raw is None:
+        return out
+    entries: List[Tuple[object, object]]
+    if isinstance(raw, Mapping):
+        entries = list(raw.items())
+    elif isinstance(raw, (list, tuple)):
+        entries = [(name, settings_type()) for name in raw]
+    else:
+        raise SchemaError(
+            f"{plural} must be a list of names or a dict of names and "
+            f"{settings_type.__name__} settings."
+        )
+    if len(entries) > CAPS[kind]:
+        raise SchemaError(f"{plural} holds at most {CAPS[kind]} {plural}.")
+    for name, value in entries:
+        where = f"{plural}[{name!r}]"
+        if kind == "category":
+            if not is_category_name(name):
+                raise SchemaError(f"{where}: not a category name; {_CATEGORY_HELP}")
+        else:
+            _field_key(name, where)
+        if not isinstance(value, settings_type):
+            raise SchemaError(f"{where}: give a {settings_type.__name__}.")
+        if name in out:
+            raise SchemaError(f"{where} is named twice.")
+        out[name] = value  # type: ignore[index]
+    return out
+
+
+def _rules(raw: object) -> Optional[Tuple[Rule, ...]]:
+    if raw is None:
+        return None
+    if not isinstance(raw, (list, tuple)):
+        raise SchemaError("rules must be a list of Rule.")
+    if len(raw) > RULES_MAX:
+        raise SchemaError(f"rules holds at most {RULES_MAX} rules.")
+    for i, rule in enumerate(raw):
+        if not isinstance(rule, Rule):
+            raise SchemaError(f"rules[{i}]: give a Rule.")
+    return tuple(raw)

statoss-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: statoss
+Version: 0.1.0
+Summary: Error tracking for StatOSS: sentry-sdk with your app's own levels, categories and fields.
+Keywords: statoss,errors,error-tracking,sentry,monitoring
+Author: StatOSS
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Dist: sentry-sdk>=2.0.0,<3
+Requires-Dist: typing-extensions>=4.12
+Requires-Python: >=3.9
+Project-URL: Homepage, https://statoss.com
+Project-URL: Source, https://github.com/kroqdotdev/statoss/tree/main/sdk-python
+Description-Content-Type: text/markdown
+
+# statoss
+
+Error tracking for [StatOSS](https://statoss.com) in Python: a thin layer
+over [`sentry-sdk`](https://pypi.org/project/sentry-sdk/) that adds your
+app's own levels, categories and fields. Python 3.9 or later, sentry-sdk 2.
+
+## Install
+
+```sh
+pip install statoss    # or: uv add statoss, poetry add statoss
+```
+
+## Start
+
+Call `init` once, as early as you can, with your app's DSN. The DSN is on the
+app's setup page in StatOSS and looks like
+`https://<key>@ingest.statoss.com/<app number>`.
+
+```python
+import os
+import statoss
+
+statoss.init(
+    dsn=os.environ["STATOSS_DSN"],
+    environment="production",
+    release="shop@1.4.0",
+)
+```
+
+The options are sentry-sdk's, and without a schema `statoss.init` is
+`sentry_sdk.init`: integrations, scopes and everything else work as its
+documentation says. `statoss.flush`, `set_user`, `set_tag`, `set_context` and
+`add_breadcrumb` are sentry-sdk's own; import `sentry_sdk` for the rest.
+
+## Levels, categories and fields
+
+Sentry has five levels: `fatal`, `error`, `warning`, `info` and `debug`.
+StatOSS lets you name your own, and adds a category and fields.
+
+```python
+schema = statoss.define_schema(
+    levels={
+        "payment-failed": statoss.Level(like="error", label="Payment failed"),
+        "slow-query": "warning",
+    },
+    categories={
+        "billing": statoss.Category(label="Billing", color="plum"),
+        "auth": statoss.Category(),
+    },
+    fields={
+        "route": statoss.Field(label="Route", filterable=True),
+        "duration_ms": statoss.Field(type="number", unit="ms", label="Duration"),
+    },
+)
+
+statoss.init(dsn=os.environ["STATOSS_DSN"], schema=schema)
+
+try:
+    charge(order)
+except CardError as error:
+    statoss.capture_exception(
+        error, level="payment-failed", category="billing", fields={"route": "/pay"}
+    )
+    # level "error", tags statoss.level=payment-failed, statoss.category=billing, route=/pay
+
+statoss.capture_message("Search took 2.4 s", level="slow-query", fields={"duration_ms": 2400})
+# level "warning", tags statoss.level=slow-query, duration_ms=2400
+
+statoss.set_category("billing")  # every later event in this scope
+```
+
+- An event is sent at the nearest Sentry level, with its own level in the tag
+  `statoss.level` and its category in `statoss.category`, so Sentry and other
+  Sentry-compatible tools still read it. Fields are sent as tags.
+- `level` takes a Sentry level or a level of the schema. A name the schema
+  does not hold is sent as `error` and, with `debug=True`, logged. A level or
+  category with characters a name cannot have (see below) is left out and
+  logged the same way.
+- The level given to a capture wins over a level set on a scope.
+- `set_category(name, scope=None)` sets it on the scope you pass, else on the
+  isolation scope as `sentry_sdk.set_tag` does. `set_category(None)` takes it
+  off.
+- An event whose level is one of the schema's own, as `scope.set_level` or
+  `sentry_sdk.capture_message` may leave it, is sent the same way, after your
+  `before_send`.
+
+## The schema
+
+`define_schema` checks everything as StatOSS does and raises `SchemaError`
+naming the place of the first problem.
+
+| Kind     | Name                                                           | Settings                                                                                                                          |
+| -------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Level    | 1 to 32 lowercase letters, digits, dots, dashes or underscores | `like` (`fatal`, `error`, `warning`, `info`, `debug` or `trace`), `label`, `color`, `severity` (1 to 24, inside the `like` range) |
+| Category | 1 to 64 of the same                                            | `label`, `color`, `hidden`, `owner` (a team member's email)                                                                       |
+| Field    | any tag key not starting `statoss.`                            | `label`, `type` (`text` or `number`), `unit`, `filterable`                                                                        |
+
+- A level may be given as its `like` alone (`"slow-query": "warning"`);
+  categories and fields as a list of names (`categories=["billing", "auth"]`).
+- A level ranking like `trace` is sent as `debug`. Sentry's own levels take a
+  label and a colour (`"error": statoss.Level(label="Error")`).
+- Colours: crimson, red, orange, amber, yellow, green, aqua, teal, blue,
+  violet, indigo, magenta, plum, grey.
+- Rules sort events that name no level or category of their own:
+
+  ```python
+  rules = [
+      statoss.Rule(subject="logger", value="payments", category="billing"),
+      statoss.Rule(subject="tag", tag_key="db", match="starts", value="pg", level="slow-query"),
+  ]
+  ```
+
+  `subject` is `tag`, `logger`, `exception`, `culprit`, `title` or
+  `message`; `match` is `is` (the default), `starts` or `contains`.
+
+`schema.to_desired()` gives the schema as StatOSS's desired state, the JSON
+that `POST /api/v1/apps/{app}/schema/plan` takes as `desired`. Rules left out
+(`rules=None`) leave the app's rules as they are; `rules=[]` says there are
+none.
+
+## Typing
+
+The package ships type hints. Name your levels and categories with `Literal`
+and a type checker (mypy, pyright) refuses a name the schema does not hold:
+
+```python
+from typing import Literal
+
+import statoss
+
+LevelName = Literal["payment-failed", "slow-query"]
+CategoryName = Literal["billing", "auth"]
+
+schema: statoss.Schema[LevelName, CategoryName] = statoss.define_schema(
+    levels={"payment-failed": "error", "slow-query": "warning"},
+    categories=["billing", "auth"],
+)
+client = statoss.init(dsn=os.environ["STATOSS_DSN"], schema=schema)
+
+client.capture_exception(error, level="payment-failed", category="billing")
+client.capture_exception(error, level="payment-faild")  # error: not a LevelName
+```
+
+`init` returns a `statoss.Client[LevelName, CategoryName]` whose
+`capture_exception`, `capture_message` and `set_category` take only those
+names and Sentry's levels. The module functions take any name.
+
+## Developing
+
+From `sdk-python/`, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv run pytest                      # tests, including the mypy check of tests/typing_check.py
+uv run --with pyright pytest       # the same, with pyright as well
+uv build                           # wheel and sdist in dist/
+```
+
+`tests/fixtures` holds a schema's desired state and the lists and limits the
+package checks against; `src/lib/python-sdk-schema.test.ts` holds the server
+to them. After changing either side, run `uv run python tests/sample_schema.py`
+and `pnpm prettier --write sdk-python/tests/fixtures`.
+
+## License
+
+MIT

statoss-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+statoss/__init__.py,sha256=MwBx1tQqGlJ3JUj0lGbAdA3c38vj0mCBoxkiyWUerjc,1025
+statoss/_client.py,sha256=wZ-AWqxv7rS6eITUyYecuH-n_sbfq5rL4HkLLcM24Sc,9740
+statoss/_schema.py,sha256=gfLliMF-veNFHehAQVyTBDw8nVIfz8LAFzx3y3DzivQ,17011
+statoss/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statoss-0.1.0.dist-info/licenses/LICENSE,sha256=BmZH0-DV0qH-I5lzCxExeH6ImjfBTiucfAA7HYJvqck,1064
+statoss-0.1.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+statoss-0.1.0.dist-info/METADATA,sha256=r2MHjfwX8tK_MZIr0l0ZRv8lO8u82Sud4MylAeVZTlY,7631
+statoss-0.1.0.dist-info/RECORD,,

statoss-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.23
+Root-Is-Purelib: true
+Tag: py3-none-any

statoss-0.1.0.dist-info/licenses/LICENSE

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