server-decorator-entity 2.0.19__py3-none-any.whl

server_decorator_entity/__init__.py

@@ -0,0 +1,43 @@
+from server_decorator_entity.action import action
+from server_decorator_entity.canonical import canonical_json
+from server_decorator_entity.markers import (
+    Bool,
+    Datetime,
+    Email,
+    EnumOf,
+    FieldMarker,
+    Float,
+    Id,
+    Int,
+    ListOf,
+    Obj,
+    Ref,
+    Str,
+    Uri,
+    Uuid,
+)
+from server_decorator_entity.restful import entity_spec, entity_spec_canonical, restful
+from server_decorator_entity.validate import RESERVED_WIRE_NAMES
+
+__all__ = [
+    "RESERVED_WIRE_NAMES",
+    "Bool",
+    "Datetime",
+    "Email",
+    "EnumOf",
+    "FieldMarker",
+    "Float",
+    "Id",
+    "Int",
+    "ListOf",
+    "Obj",
+    "Ref",
+    "Str",
+    "Uri",
+    "Uuid",
+    "action",
+    "canonical_json",
+    "entity_spec",
+    "entity_spec_canonical",
+    "restful",
+]

server_decorator_entity/action.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from server_decorator_entity.markers import FieldMarker
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_ATTR = "__entity_action__"
+
+
+def action(
+    name: str,
+    *,
+    description: str | None = None,
+    state_field: str | None = None,
+    from_state: str | None = None,
+    to_state: str | None = None,
+    input: list[tuple[str, FieldMarker]] | None = None,
+    transactional: bool = True,
+) -> Callable[[F], F]:
+    def mark(fn: F) -> F:
+        if isinstance(fn, (staticmethod, classmethod)):
+            kind = "static" if isinstance(fn, staticmethod) else "class"
+            underlying = fn.__func__
+            raise TypeError(
+                f"@action must decorate an instance method (got {kind} method "
+                f"'{underlying.__name__}')"
+            )
+        spec: dict[str, Any] = {"name": name}
+        if description is not None:
+            spec["description"] = description
+        if from_state is not None or to_state is not None:
+            spec["stateField"] = state_field or "status"
+            if from_state is not None:
+                spec["from"] = from_state
+            if to_state is not None:
+                spec["to"] = to_state
+        if input:
+            spec["input"] = [m.to_ir(n) for n, m in input]
+        if not transactional:
+            spec["transactional"] = False
+        setattr(fn, _ATTR, spec)
+        return fn
+
+    return mark

server_decorator_entity/canonical.py

@@ -0,0 +1,8 @@
+"""Canonical EntitySpec JSON — contracts/rules/entity-spec-canonical.md."""
+
+import json
+from typing import Any
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)

server_decorator_entity/markers.py

@@ -0,0 +1,119 @@
+"""Field markers used inside Annotated[...] on @restful classes."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from server_decorator_entity.validate import (
+    assert_enum_nonempty,
+    assert_format_pattern_exclusive,
+    assert_integer_or_none,
+    assert_portable_pattern,
+    assert_wire_name_not_reserved,
+)
+
+
+@dataclass(frozen=True)
+class FieldMarker:
+    type: str
+    description: str | None = None
+    role: str | None = None
+    format: str | None = None
+    enum: tuple[str, ...] | None = None
+    min: int | None = None
+    max: int | None = None
+    pattern: str | None = None
+    optional: bool = False
+    nullable: bool = False
+    readonly: bool = False
+    writeonly: bool = False
+    filterable: bool = False
+    item: "FieldMarker | None" = None
+    ref: str | None = None
+    fields: tuple[tuple[str, "FieldMarker"], ...] | None = None  # (name, marker) pairs for obj
+
+    def to_ir(self, name: str) -> dict[str, Any]:
+        label = f'field "{name}"'
+        assert_wire_name_not_reserved(name, label)
+        assert_format_pattern_exclusive(self.format, self.pattern, label)
+        assert_portable_pattern(self.pattern, label)
+        assert_enum_nonempty(self.enum, label)
+        assert_integer_or_none(self.min, f"{label}.min")
+        assert_integer_or_none(self.max, f"{label}.max")
+
+        ir: dict[str, Any] = {"name": name, "type": self.type}
+        if self.role:
+            ir["role"] = self.role
+        if self.format:
+            ir["format"] = self.format
+        if self.enum:
+            ir["enum"] = list(self.enum)
+        if self.min is not None:
+            ir["min"] = self.min
+        if self.max is not None:
+            ir["max"] = self.max
+        if self.pattern is not None:
+            ir["pattern"] = self.pattern
+        if self.description is not None:
+            ir["description"] = self.description
+        for flag in ("optional", "nullable", "readonly", "writeonly", "filterable"):
+            if getattr(self, flag):
+                ir[flag] = True
+        if self.item:
+            ir["item"] = self.item.to_ir(name)
+        if self.ref is not None:
+            ir["ref"] = self.ref
+        if self.fields is not None:
+            ir["fields"] = [m.to_ir(n) for n, m in self.fields]
+        return ir
+
+
+def Id() -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", role="id", readonly=True)
+
+
+def Str(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", **kw)
+
+
+def Email(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", format="email", **kw)
+
+
+def Uuid(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", format="uuid", **kw)
+
+
+def Uri(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="str", format="uri", **kw)
+
+
+def Int(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="int", **kw)
+
+
+def Float(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="float", **kw)
+
+
+def Bool(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="bool", **kw)
+
+
+def Datetime(**kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="datetime", **kw)
+
+
+def EnumOf(*values: str, **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="enum", enum=values, **kw)
+
+
+def Ref(entity: str, **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="ref", ref=entity, **kw)
+
+
+def ListOf(item: FieldMarker, **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="list", item=item, **kw)
+
+
+def Obj(fields: list[tuple[str, FieldMarker]], **kw: Any) -> FieldMarker:  # noqa: N802
+    return FieldMarker(type="obj", fields=tuple(fields), **kw)

server_decorator_entity/restful.py

@@ -0,0 +1,128 @@
+import copy
+import inspect
+import re
+import typing
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from server_decorator_entity.action import _ATTR
+from server_decorator_entity.canonical import canonical_json
+from server_decorator_entity.markers import FieldMarker
+from server_decorator_entity.validate import assert_valid_security
+
+C = TypeVar("C", bound=type)
+
+_SPEC_ATTR = "__entity_spec__"
+_DEFAULT_OPS = ["list", "get", "create", "update", "delete"]
+_WIRE_NAME_RE = re.compile(r"^[a-z][A-Za-z0-9]*$")
+
+
+def _camel(name: str) -> str:
+    head, *rest = name.split("_")
+    return head + "".join(s.capitalize() for s in rest)
+
+
+def restful(
+    *,
+    path: str,
+    transports: list[str] | None = None,
+    ops: list[str] | None = None,
+    pagination: str = "offset",
+    description: str | None = None,
+    tags: list[str] | None = None,
+    security: dict[str, Any] | None = None,
+) -> Callable[[C], C]:
+    def wrap(cls: C) -> C:
+        # Own-class declarations only (N2: no MRO walk) — a @restful subclass must not
+        # re-collect its base's fields. get_type_hints() still resolves the (possibly
+        # string/forward-ref) annotation values; own_annotations only supplies which
+        # names — and their declaration order — belong to this class.
+        own_annotations: dict[str, Any] = inspect.get_annotations(cls)
+        hints = typing.get_type_hints(cls, include_extras=True)
+        fields: list[dict[str, Any]] = []
+        seen_wire_names: set[str] = set()
+        for attr_name in own_annotations:
+            hint = hints.get(attr_name)
+            marker = next(
+                (m for m in getattr(hint, "__metadata__", ()) if isinstance(m, FieldMarker)), None
+            )
+            if marker is None:
+                continue
+            wire_name = _camel(attr_name)
+            if not _WIRE_NAME_RE.match(wire_name):
+                raise ValueError(
+                    f"{cls.__name__}.{attr_name}: computed wire name {wire_name!r} does not "
+                    f"match ^[a-z][A-Za-z0-9]*$"
+                )
+            if wire_name in seen_wire_names:
+                raise ValueError(
+                    f"{cls.__name__}.{attr_name}: wire name {wire_name!r} collides with "
+                    f"another field"
+                )
+            seen_wire_names.add(wire_name)
+            fields.append(marker.to_ir(wire_name))
+
+        # `or` is truthiness-coalescing, not None-coalescing — an explicit `transports=[]`/
+        # `ops=[]` must fail fast here (not be silently replaced by the default), matching TS's
+        # `??`-then-validate approach (C4). Only an omitted (`None`) argument gets the default.
+        resolved_transports = ["rest"] if transports is None else transports
+        if not resolved_transports:
+            raise ValueError(f"{cls.__name__}: transports must not be empty")
+        resolved_ops = list(_DEFAULT_OPS) if ops is None else ops
+        if not resolved_ops:
+            raise ValueError(f"{cls.__name__}: ops must not be empty")
+
+        actions: list[dict[str, Any]] = []
+        for member in vars(cls).values():
+            if isinstance(member, (staticmethod, classmethod)):
+                underlying = member.__func__
+                if hasattr(underlying, _ATTR):
+                    kind = "static" if isinstance(member, staticmethod) else "class"
+                    raise TypeError(
+                        f"@action must decorate an instance method (got {kind} method "
+                        f"'{underlying.__name__}')"
+                    )
+                continue
+            if callable(member) and hasattr(member, _ATTR):
+                actions.append(getattr(member, _ATTR))
+        spec: dict[str, Any] = {
+            "specVersion": "1.2.0",
+            "entity": cls.__name__,
+            "path": path,
+            "transports": resolved_transports,
+            "ops": resolved_ops,
+            "pagination": pagination,
+            "fields": fields,
+        }
+        if actions:
+            spec["actions"] = actions
+        assert_valid_security(security, resolved_ops, [a["name"] for a in actions], cls.__name__)
+        # Keep absent keys absent so canonical JSON is byte-unchanged for 1.1-era declarations.
+        if description is not None:
+            spec["description"] = description
+        if tags is not None:
+            spec["tags"] = tags
+        if security is not None:
+            spec["security"] = security
+        setattr(cls, _SPEC_ATTR, spec)
+        return cls
+
+    return wrap
+
+
+def _stored_spec(cls: type) -> dict[str, Any]:
+    # Own-attribute only (cls.__dict__, never getattr's MRO walk) — an undecorated
+    # subclass of a @restful base must not silently inherit the base's spec.
+    spec = cls.__dict__.get(_SPEC_ATTR)
+    if spec is None:
+        raise TypeError(f"{cls.__name__} is not decorated with @restful")
+    return spec  # type: ignore[no-any-return]
+
+
+def entity_spec(cls: type) -> dict[str, Any]:
+    # Deep copy so callers can't poison the memoized spec (parity with Node's deep-freeze).
+    return copy.deepcopy(_stored_spec(cls))
+
+
+def entity_spec_canonical(cls: type) -> str:
+    return canonical_json(_stored_spec(cls))

server_decorator_entity/testing/user_fixture.py

@@ -0,0 +1,63 @@
+from typing import Annotated, Any
+
+from server_decorator_entity import (
+    Bool,
+    Datetime,
+    Email,
+    EnumOf,
+    Float,
+    Id,
+    Int,
+    ListOf,
+    Obj,
+    Str,
+    action,
+    restful,
+)
+
+
+@restful(
+    path="users",
+    transports=["rest", "rpc", "sse", "ws"],
+    description="A registered user account",
+    tags=["identity"],
+    security={
+        "schemes": [
+            {"name": "bearerAuth", "type": "http", "scheme": "bearer", "bearerFormat": "JWT"}
+        ],
+        "ops": {"create": ["user:write"], "update": ["user:write"], "delete": ["user:admin"]},
+        "actions": {"activate": ["user:admin"]},
+    },
+)
+class User:
+    id: Annotated[str, Id()]
+    email: Annotated[str, Email(filterable=True, description="Primary contact address")]
+    name: Annotated[str, Str(min=2, max=80)]
+    status: Annotated[str, EnumOf("inactive", "active", "banned", filterable=True)]
+    login_count: Annotated[int, Int(min=0, readonly=True)]
+    tags: Annotated[list[str], ListOf(Str())]
+    profile: Annotated[
+        dict[str, Any] | None, Obj([("bio", Str(max=500, optional=True))], optional=True)
+    ]
+    birthday: Annotated[str | None, Datetime(optional=True, nullable=True)]
+    # I-d (P1 gate-review): writable, non-readonly fields to exercise DTO derivation rules the
+    # original 16-case contract never touched (JSON-type strictness on float/bool, writeonly
+    # exclusion from read).
+    score: Annotated[float | None, Float(min=0, optional=True)]
+    active: Annotated[bool | None, Bool(optional=True)]
+    secret_note: Annotated[str | None, Str(writeonly=True, max=100, optional=True)]
+
+    @action(
+        "activate",
+        description="Move a dormant account back to active",
+        from_state="inactive",
+        to_state="active",
+        input=[("reason", Str(max=200, optional=True))],
+    )
+    def activate(self) -> None: ...
+
+    @action("ping")
+    def ping(self) -> None: ...
+
+
+UserFixture = User

server_decorator_entity/validate.py

@@ -0,0 +1,155 @@
+"""Decoration-time IR validation shared across field markers and @restful.
+
+Mirrors node/packages/entity/src/validate.ts — see contracts/rules/entity-spec-validation.md
+for the shared invariants (reserved wire names, format+pattern exclusivity, integer min/max,
+non-empty enum/ops/transports) both language packages enforce identically.
+"""
+
+from typing import Any
+
+# Public pydantic.BaseModel attribute names (pydantic v2). A wire name colliding with one of
+# these makes gen-pydantic's create_model() raise "shadows an attribute in parent BaseModel" —
+# reject at decoration time in BOTH languages instead of letting it crash gen-pydantic's model
+# build. See contracts/rules/entity-spec-validation.md "Reserved wire names".
+RESERVED_WIRE_NAMES: frozenset[str] = frozenset(
+    {
+        "construct",
+        "copy",
+        "dict",
+        "from_orm",
+        "json",
+        "model_computed_fields",
+        "model_config",
+        "model_construct",
+        "model_copy",
+        "model_dump",
+        "model_dump_json",
+        "model_extra",
+        "model_fields",
+        "model_fields_set",
+        "model_json_schema",
+        "model_parametrized_name",
+        "model_post_init",
+        "model_rebuild",
+        "model_validate",
+        "model_validate_json",
+        "model_validate_strings",
+        "parse_file",
+        "parse_obj",
+        "parse_raw",
+        "schema",
+        "schema_json",
+        "update_forward_refs",
+        "validate",
+    }
+)
+
+
+def assert_integer_or_none(value: Any, label: str) -> None:
+    if value is None:
+        return
+    # bool is a subclass of int in Python — isinstance(True, int) is True — so it must be
+    # excluded explicitly, not just checked for isinstance(value, int).
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"{label}: min/max must be integers (got {value!r})")
+
+
+def assert_wire_name_not_reserved(name: str, label: str) -> None:
+    if name in RESERVED_WIRE_NAMES:
+        raise ValueError(
+            f"{label}: wire name {name!r} is reserved (shadows a pydantic BaseModel attribute)"
+        )
+
+
+def assert_format_pattern_exclusive(fmt: Any, pattern: Any, label: str) -> None:
+    if fmt is not None and pattern is not None:
+        raise ValueError(f"{label}: format and pattern are mutually exclusive")
+
+
+def assert_enum_nonempty(enum: Any, label: str) -> None:
+    if enum is not None and len(enum) == 0:
+        raise ValueError(f"{label}: enum must have at least one value")
+
+
+_LOOKAROUND_MARKERS = ("(?=", "(?!", "(?<=", "(?<!")
+
+
+def _has_backreference(pattern: str) -> bool:
+    """A `\\` run of odd length immediately before a digit 1-9 means that digit is escaped — a
+    backreference (`\\1`). An even-length run means the backslashes are themselves escaped
+    (`\\\\1` is a literal backslash followed by the literal digit `1`), so it's NOT a
+    backreference. `\\0` is never a backreference (it's either a literal `0` or, in some engines,
+    a null escape — not a capture-group reference), so only digits 1-9 are scanned. This is a
+    conservative lexical scan, not a regex parser — see
+    contracts/rules/entity-spec-validation.md for what it does and does not catch.
+    """
+    for i, c in enumerate(pattern):
+        if c in "123456789":
+            backslashes = 0
+            j = i - 1
+            while j >= 0 and pattern[j] == "\\":
+                backslashes += 1
+                j -= 1
+            if backslashes % 2 == 1:
+                return True
+    return False
+
+
+def assert_portable_pattern(pattern: Any, label: str) -> None:
+    """pydantic v2's Rust-backed regex engine (used by gen-pydantic) does not support lookaround
+    or backreferences — both are valid Python `re` / JS RegExp syntax, so a pattern using either
+    builds fine in gen-zod but crashes gen-pydantic's entire model build. Reject non-portable
+    patterns at DECORATION time (before either generator ever sees the IR), in both languages —
+    see contracts/rules/entity-spec-validation.md.
+    """
+    if pattern is None:
+        return
+    for marker in _LOOKAROUND_MARKERS:
+        if marker in pattern:
+            raise ValueError(
+                f"{label}: pattern {pattern!r} is not RE2/rust-regex compatible (contains "
+                f"lookaround {marker!r}) — see contracts/rules/entity-spec-validation.md"
+            )
+    if _has_backreference(pattern):
+        raise ValueError(
+            f"{label}: pattern {pattern!r} is not RE2/rust-regex compatible (contains a "
+            f"backreference) — see contracts/rules/entity-spec-validation.md"
+        )
+
+
+__all__ = [
+    "RESERVED_WIRE_NAMES",
+    "assert_enum_nonempty",
+    "assert_format_pattern_exclusive",
+    "assert_integer_or_none",
+    "assert_portable_pattern",
+    "assert_wire_name_not_reserved",
+]
+
+
+def assert_valid_security(
+    security: dict[str, Any] | None,
+    ops: list[str],
+    action_names: list[str],
+    entity: str,
+) -> None:
+    """Mirror of Node's validateSecurity() in packages/entity/src/validate.ts."""
+    if security is None:
+        return
+    schemes = security.get("schemes", [])
+    if not schemes:
+        raise ValueError(f"{entity}: security.schemes must not be empty")
+    for s in schemes:
+        name = s.get("name")
+        if s.get("type") not in ("http", "apiKey"):
+            raise ValueError(f'{entity}: scheme "{name}": type must be "http" or "apiKey"')
+        if s["type"] == "http" and "scheme" not in s:
+            raise ValueError(f'{entity}: scheme "{name}": http requires "scheme"')
+        if s["type"] == "apiKey" and ("in" not in s or "paramName" not in s):
+            raise ValueError(f'{entity}: scheme "{name}": apiKey requires "in" and "paramName"')
+    for op in security.get("ops", {}):
+        if op not in ops:
+            raise ValueError(f"{entity}: security.ops.{op} is not declared in ops")
+    for action_name in security.get("actions", {}):
+        if action_name not in action_names:
+            raise ValueError(f"{entity}: security.actions.{action_name} is not a declared action")

server_decorator_entity-2.0.19.dist-info/METADATA

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: server-decorator-entity
+Version: 2.0.19
+Summary: Declarative entity decorators emitting the language-neutral EntitySpec IR. Polyglot sibling of @montionugera/entity-spec.
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.21; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# server-decorator-entity (Python)
+
+Declarative entity decorators (`@restful`, `@action`, field markers) emitting the language-neutral EntitySpec IR — polyglot sibling of `@montionugera/entity-spec`, sharing the wire-format contracts in [`../../../contracts`](../../../contracts).
+
+## Install
+
+```bash
+pip install server-decorator-entity
+```
+
+## Usage
+
+```python
+from typing import Annotated
+from server_decorator_entity import restful, Id, Email, entity_spec
+
+@restful(path="users")
+class User:
+    id: Annotated[str, Id()]
+    email: Annotated[str, Email()]
+
+spec = entity_spec(User)  # -> EntitySpec IR, byte-identical to the Node emitter
+```
+
+`entity_spec_canonical(User)` returns the IR as a canonical JSON string (codepoint-sorted keys,
+`None`-dropping) — the exact bytes both languages' generators and the cross-language parity
+check compare against.

server_decorator_entity-2.0.19.dist-info/RECORD

@@ -0,0 +1,12 @@
+server_decorator_entity/__init__.py,sha256=tqlDxK1waungYVvAcXEHl54Idra4dNcIR1NLIlxlzmE,781
+server_decorator_entity/action.py,sha256=_ixpHHM4J8KGPx8rIpyRtUcIN5yKqd2dNCu7YFfqMCw,1462
+server_decorator_entity/canonical.py,sha256=lFX82wVG8-1qpeuYA57dwOif4kxQyK1MT2omiY6CjB4,243
+server_decorator_entity/markers.py,sha256=acEC9Z7oomjP_D384_j4wr5XhGiOvlc6X-66qWOrSHM,3705
+server_decorator_entity/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server_decorator_entity/restful.py,sha256=WQvmEevGQKOj4e1N9aPcsLGaoNebzUiNRrbj3nLYC0s,5207
+server_decorator_entity/validate.py,sha256=FUB7bdRrXsetE7ZOp3eSa8FadoDJR_XGblNsMqZ128M,6076
+server_decorator_entity/testing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server_decorator_entity/testing/user_fixture.py,sha256=XW1P4XxMguShaUumOnXFLGUCxZeNvUyc1lq1Vv3iEao,1948
+server_decorator_entity-2.0.19.dist-info/METADATA,sha256=Elvck7S19qcJhLaok4hBYBKGCfW6Ji-NqHK6hAFO1uk,1376
+server_decorator_entity-2.0.19.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+server_decorator_entity-2.0.19.dist-info/RECORD,,

server_decorator_entity-2.0.19.dist-info/WHEEL

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