webfunction 0.1.0__py3-none-any.whl

webfunction/models.py

@@ -0,0 +1,325 @@
+"""Package/Endpoint/Argument/Attribute/ObjectSchema/DocumentedError, ported from the
+Ruby reference gem's package.rb/endpoint.rb/argument.rb/attribute.rb/object_schema.rb/
+documented_error.rb/flaggable.rb.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from . import wftype
+
+
+def _normalize_array(items: Any, fn=None) -> list:
+    if not isinstance(items, list):
+        return []
+    result = []
+    for item in items:
+        value = fn(item) if fn else item
+        if value is not None:
+            result.append(value)
+    return result
+
+
+def _normalize_strings(items: Any) -> List[str]:
+    return _normalize_array(items, lambda i: str(i))
+
+
+def _normalize_choices(raw: Any) -> list:
+    if isinstance(raw, list):
+        return list(raw)
+    return [raw] if raw is not None else []
+
+
+class Flaggable:
+    """Mixin providing ``has_flag()`` for objects with a ``flags`` list, mirroring the
+    Ruby gem's ``Flaggable`` module."""
+
+    flags: List[str]
+
+    def has_flag(self, flag: str) -> bool:
+        return flag in self.flags
+
+
+@dataclass
+class DocumentedError:
+    code: str
+    docs: str = ""
+
+    @classmethod
+    def from_dict(cls, d: Any) -> Optional["DocumentedError"]:
+        if not isinstance(d, dict) or not d.get("code"):
+            return None
+        return cls(code=d["code"], docs=str(d.get("docs") or ""))
+
+    @classmethod
+    def from_list(cls, items: Any) -> List["DocumentedError"]:
+        return _normalize_array(items, cls.from_dict)
+
+
+@dataclass
+class Argument(Flaggable):
+    name: str
+    type: wftype.Type
+    group: Optional[str] = None
+    choices: list = field(default_factory=list)
+    flags: List[str] = field(default_factory=list)
+    docs: str = ""
+
+    @property
+    def required(self) -> bool:
+        return self.has_flag("required")
+
+    @property
+    def optional(self) -> bool:
+        return not self.required
+
+    @classmethod
+    def from_dict(cls, d: Any) -> Optional["Argument"]:
+        if not isinstance(d, dict) or not d.get("name") or not d.get("type"):
+            return None
+        return cls(
+            name=d["name"],
+            type=wftype.parse(d["type"]),
+            group=d.get("group"),
+            choices=_normalize_choices(d.get("choices")),
+            flags=_normalize_strings(d.get("flags")),
+            docs=str(d.get("docs") or ""),
+        )
+
+    @classmethod
+    def from_list(cls, items: Any) -> List["Argument"]:
+        return _normalize_array(items, cls.from_dict)
+
+
+@dataclass
+class Attribute(Flaggable):
+    name: str
+    type: wftype.Type
+    values: list = field(default_factory=list)
+    flags: List[str] = field(default_factory=list)
+    docs: str = ""
+
+    @property
+    def nullable(self) -> bool:
+        return self.has_flag("nullable")
+
+    @classmethod
+    def from_dict(cls, d: Any) -> Optional["Attribute"]:
+        if not isinstance(d, dict) or not d.get("name") or not d.get("type"):
+            return None
+        return cls(
+            name=d["name"],
+            type=wftype.parse(d["type"]),
+            values=_normalize_choices(d.get("values")),
+            flags=_normalize_strings(d.get("flags")),
+            docs=str(d.get("docs") or ""),
+        )
+
+    @classmethod
+    def from_list(cls, items: Any) -> List["Attribute"]:
+        return _normalize_array(items, cls.from_dict)
+
+
+class ObjectSchema:
+    """Named object definition. An ``object.<name>`` reference resolves against either
+    its ``arguments`` (argument context) or ``attributes`` (attribute context)."""
+
+    CONTEXTS = ("arguments", "attributes")
+
+    def __init__(self, name: str, arguments: Optional[List[Argument]] = None,
+                 attributes: Optional[List[Attribute]] = None):
+        self.name = name
+        self._arguments: Dict[str, Argument] = {a.name: a for a in (arguments or [])}
+        self._attributes: Dict[str, Attribute] = {a.name: a for a in (attributes or [])}
+
+    @property
+    def arguments(self) -> List[Argument]:
+        return list(self._arguments.values())
+
+    def argument(self, name: str) -> Optional[Argument]:
+        return self._arguments.get(str(name))
+
+    @property
+    def attributes(self) -> List[Attribute]:
+        return list(self._attributes.values())
+
+    def attribute(self, name: str) -> Optional[Attribute]:
+        return self._attributes.get(str(name))
+
+    def properties(self, context: str) -> list:
+        if context == "arguments":
+            return self.arguments
+        if context == "attributes":
+            return self.attributes
+        raise ValueError(f"context must be one of {self.CONTEXTS!r}, got {context!r}")
+
+    def __repr__(self):
+        return f"ObjectSchema(name={self.name!r})"
+
+    @classmethod
+    def from_dict(cls, d: Any) -> Optional["ObjectSchema"]:
+        if not isinstance(d, dict) or not d.get("name"):
+            return None
+        return cls(
+            name=d["name"],
+            arguments=Argument.from_list(d.get("arguments")),
+            attributes=Attribute.from_list(d.get("attributes")),
+        )
+
+    @classmethod
+    def from_list(cls, items: Any) -> List["ObjectSchema"]:
+        return _normalize_array(items, cls.from_dict)
+
+
+class Endpoint(Flaggable):
+    def __init__(self, *, name: str, returns: Any, flags: Optional[List[str]] = None,
+                 group: Optional[str] = None, docs: Optional[str] = None,
+                 arguments: Optional[List[Argument]] = None,
+                 attributes: Optional[List[Attribute]] = None,
+                 errors: Optional[List[DocumentedError]] = None):
+        self.name = name
+        self.returns = wftype.parse(returns)
+        self.flags = flags or []
+        self.group = group
+        self.docs = docs or ""
+        self._arguments: Dict[str, Argument] = {a.name: a for a in (arguments or [])}
+        self._attributes: Dict[str, Attribute] = {a.name: a for a in (attributes or [])}
+        self._errors: Dict[str, DocumentedError] = {e.code: e for e in (errors or [])}
+        # Assigned when the endpoint is loaded from a package into a Client; required by .call().
+        self.client = None
+
+    @property
+    def arguments(self) -> List[Argument]:
+        return list(self._arguments.values())
+
+    def argument(self, name: str) -> Optional[Argument]:
+        return self._arguments.get(str(name))
+
+    @property
+    def attributes(self) -> List[Attribute]:
+        return list(self._attributes.values())
+
+    def attribute(self, name: str) -> Optional[Attribute]:
+        return self._attributes.get(str(name))
+
+    @property
+    def errors(self) -> List[DocumentedError]:
+        return list(self._errors.values())
+
+    def error(self, code: str) -> Optional[DocumentedError]:
+        return self._errors.get(str(code))
+
+    @property
+    def bearer_auth(self) -> bool:
+        return self.has_flag("bearer_auth")
+
+    @property
+    def capture_bearer(self) -> bool:
+        return self.has_flag("capture_bearer")
+
+    @property
+    def paginated(self) -> bool:
+        return self.has_flag("paginated")
+
+    @property
+    def private(self) -> bool:
+        return self.has_flag("private")
+
+    def call(self, **args) -> Any:
+        if self.client is None:
+            raise RuntimeError("client must be set to invoke an endpoint")
+        return self.client.call(self.name, args)
+
+    def __repr__(self):
+        return f"Endpoint(name={self.name!r})"
+
+    @classmethod
+    def from_dict(cls, d: Any) -> Optional["Endpoint"]:
+        if not isinstance(d, dict) or not d.get("name") or not d.get("returns"):
+            return None
+        return cls(
+            name=d["name"],
+            returns=d["returns"],
+            flags=_normalize_strings(d.get("flags")),
+            group=d.get("group"),
+            docs=str(d.get("docs") or ""),
+            arguments=Argument.from_list(d.get("arguments")),
+            attributes=Attribute.from_list(d.get("attributes")),
+            errors=DocumentedError.from_list(d.get("errors")),
+        )
+
+    @classmethod
+    def from_list(cls, items: Any) -> List["Endpoint"]:
+        return _normalize_array(items, cls.from_dict)
+
+
+class Package(Flaggable):
+    def __init__(self, *, base_url: str, pipeline_url: Optional[str] = None,
+                 name: Optional[str] = None, version: Optional[str] = None,
+                 docs: Optional[str] = None, flags: Optional[List[str]] = None,
+                 versions: Optional[List[str]] = None,
+                 endpoints: Optional[List[Endpoint]] = None,
+                 errors: Optional[List[DocumentedError]] = None,
+                 objects: Optional[List[ObjectSchema]] = None):
+        self.base_url = base_url
+        self.pipeline_url = pipeline_url
+        self.name = name
+        self.version = version
+        self.docs = docs or ""
+        self.flags = flags or []
+        self.versions = versions or []
+        self._endpoints: Dict[str, Endpoint] = {e.name: e for e in (endpoints or [])}
+        self._errors: Dict[str, DocumentedError] = {e.code: e for e in (errors or [])}
+        self._objects: Dict[str, ObjectSchema] = {o.name: o for o in (objects or [])}
+
+    @property
+    def endpoints(self) -> List[Endpoint]:
+        return list(self._endpoints.values())
+
+    def endpoint(self, name: str) -> Optional[Endpoint]:
+        # Underscores map to hyphens so python_style_names match hyphenated endpoint names.
+        return self._endpoints.get(str(name).replace("_", "-"))
+
+    @property
+    def errors(self) -> List[DocumentedError]:
+        return list(self._errors.values())
+
+    def error(self, code: str) -> Optional[DocumentedError]:
+        return self._errors.get(str(code))
+
+    @property
+    def objects(self) -> List[ObjectSchema]:
+        return list(self._objects.values())
+
+    def object(self, name: str, *, context: str) -> Optional[ObjectSchema]:
+        obj = self._objects.get(str(name))
+        if obj is None:
+            return None
+        if not obj.properties(context):
+            return None
+        return obj
+
+    @property
+    def versioned(self) -> bool:
+        return self.has_flag("versioned")
+
+    def __repr__(self):
+        return f"Package(name={self.name!r}, base_url={self.base_url!r})"
+
+    @classmethod
+    def from_dict(cls, d: Any) -> "Package":
+        d = d or {}
+        return cls(
+            base_url=d.get("base_url"),
+            pipeline_url=d.get("pipeline_url"),
+            name=d.get("name"),
+            version=d.get("version"),
+            docs=str(d.get("docs") or ""),
+            flags=_normalize_strings(d.get("flags")),
+            versions=_normalize_strings(d.get("versions")),
+            endpoints=Endpoint.from_list(d.get("endpoints")),
+            errors=DocumentedError.from_list(d.get("errors")),
+            objects=ObjectSchema.from_list(d.get("objects")),
+        )

webfunction/page.py

@@ -0,0 +1,134 @@
+"""Pagination wrapper, ported from the Ruby reference gem's page.rb.
+
+Deliberate, ecosystem-wide deviation from the Ruby gem: pagination is detected via
+the endpoint's ``paginated`` flag, not by sniffing the response shape (the shape-sniffing
+approach is also the root cause of a real zero-item-pagination bug hit later on the Ruby
+*codegen* side -- see ``/areas/wfn-ruby-codegen.md``). Go/Java/C# all made this same
+deviation deliberately; Python does too, for consistency across the suite.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterator, List, Optional
+
+
+class Page:
+    """A page of results from a paginated (sync) endpoint. Iterable over its items."""
+
+    def __init__(self, *, items: list, next_body: Optional[dict], previous_body: Optional[dict],
+                 fetch: Callable[[dict], Any]):
+        self.items = items
+        self._next_body = next_body
+        self._previous_body = previous_body
+        self._fetch = fetch
+
+    @property
+    def has_next(self) -> bool:
+        return self._next_body is not None
+
+    @property
+    def has_previous(self) -> bool:
+        return self._previous_body is not None
+
+    def next_page(self) -> Optional[Any]:
+        """Fetches the next page by posting the opaque ``next`` body to the same endpoint."""
+        if self._next_body is None:
+            return None
+        return self._fetch(self._next_body)
+
+    def previous_page(self) -> Optional[Any]:
+        """Fetches the previous page by posting the opaque ``previous`` body to the same endpoint."""
+        if self._previous_body is None:
+            return None
+        return self._fetch(self._previous_body)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __getitem__(self, index):
+        return self.items[index]
+
+    def __repr__(self) -> str:
+        return f"Page(items={self.items!r}, has_next={self.has_next}, has_previous={self.has_previous})"
+
+    @staticmethod
+    def is_paginated_shape(response: Any) -> bool:
+        """Whether ``response`` matches the pagination contract's shape. Not used for the
+        wrap decision itself (see module docstring) but exposed for callers who want to
+        double-check a server's response against the spec."""
+        return (
+            isinstance(response, dict)
+            and "page" in response and "next" in response and "previous" in response
+            and isinstance(response["page"], list)
+            and (response["next"] is None or isinstance(response["next"], dict))
+            and (response["previous"] is None or isinstance(response["previous"], dict))
+        )
+
+    @classmethod
+    def wrap(cls, response: Any, *, paginated: bool, fetch: Callable[[dict], Any]) -> Any:
+        """Wraps ``response`` in a Page when the endpoint declares the ``paginated`` flag,
+        else returns it unchanged. ``fetch`` is called with the opaque ``next``/``previous``
+        body and should return an already re-wrapped Page (or bare value) in turn."""
+        if not paginated or not isinstance(response, dict):
+            return response
+        return cls(
+            items=response.get("page") or [],
+            next_body=response.get("next"),
+            previous_body=response.get("previous"),
+            fetch=fetch,
+        )
+
+
+class AsyncPage:
+    """Async equivalent of :class:`Page`. ``next_page()``/``previous_page()`` must be awaited."""
+
+    def __init__(self, *, items: list, next_body: Optional[dict], previous_body: Optional[dict],
+                 fetch: Callable[[dict], Any]):
+        self.items = items
+        self._next_body = next_body
+        self._previous_body = previous_body
+        self._fetch = fetch
+
+    @property
+    def has_next(self) -> bool:
+        return self._next_body is not None
+
+    @property
+    def has_previous(self) -> bool:
+        return self._previous_body is not None
+
+    async def next_page(self) -> Optional[Any]:
+        if self._next_body is None:
+            return None
+        return await self._fetch(self._next_body)
+
+    async def previous_page(self) -> Optional[Any]:
+        if self._previous_body is None:
+            return None
+        return await self._fetch(self._previous_body)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __getitem__(self, index):
+        return self.items[index]
+
+    def __repr__(self) -> str:
+        return f"AsyncPage(items={self.items!r}, has_next={self.has_next}, has_previous={self.has_previous})"
+
+    @classmethod
+    def wrap(cls, response: Any, *, paginated: bool, fetch: Callable[[dict], Any]) -> Any:
+        if not paginated or not isinstance(response, dict):
+            return response
+        return cls(
+            items=response.get("page") or [],
+            next_body=response.get("next"),
+            previous_body=response.get("previous"),
+            fetch=fetch,
+        )

webfunction/pipeline.py

@@ -0,0 +1,163 @@
+"""Call pipelining: Path/Promise/Pipeline, ported from the Ruby reference gem's
+pipeline.rb/promise.rb.
+
+Unlike the Ruby gem -- where an unresolved ``Promise#[]`` returns a bare ``Path``
+rather than another ``Promise`` (arguably a quirk of the reference implementation) --
+Python's version always returns a new ``Promise`` wrapping the deeper path, so
+chained indexing (``promise["a"]["b"]``) keeps working and stays consistent with
+what the Go/Java/C# clients do with their equivalent ``.Field()``/``.get()`` methods.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Union
+
+from .errors import UnresolvedPromiseError
+
+_UNSET = object()
+
+
+class Path:
+    """A JSONPath expression (e.g. ``"$[0].id"``) built up via indexing."""
+
+    __slots__ = ("_path",)
+
+    def __init__(self, path: str):
+        self._path = path
+
+    def __getitem__(self, key: Union[str, int]) -> "Path":
+        if isinstance(key, int):
+            return Path(f"{self._path}[{key}]")
+        return Path(f"{self._path}.{key}")
+
+    def __str__(self) -> str:
+        return self._path
+
+    def __repr__(self) -> str:
+        return f"Path({self._path!r})"
+
+    def __eq__(self, other):
+        return isinstance(other, Path) and other._path == self._path
+
+
+class Promise:
+    """A placeholder for a value that will be resolved once its pipeline executes.
+
+    A literal argument string starting with ``"$"`` must be escaped as ``"\\$"``
+    per the pipelining spec -- that escaping is the caller's responsibility when
+    building step bodies, same as every other client in the suite.
+    """
+
+    def __init__(self, pipeline: "Pipeline", path: Union[str, Path]):
+        self._pipeline = pipeline
+        self._path = path if isinstance(path, Path) else Path(path)
+        self._value: Any = _UNSET
+
+    @property
+    def resolved(self) -> bool:
+        return self._value is not _UNSET
+
+    def __getitem__(self, key: Union[str, int]) -> Any:
+        if self.resolved:
+            return self._value[key]
+        return Promise(self._pipeline, self._path[key])
+
+    def field(self, key: Union[str, int]) -> "Promise":
+        """Explicit equivalent of ``promise[key]``, for readability or non-literal keys."""
+        return self[key]
+
+    def __str__(self) -> str:
+        return str(self._value) if self.resolved else str(self._path)
+
+    def __repr__(self) -> str:
+        return f"Promise({self._value!r})" if self.resolved else f"Promise({self._path!r})"
+
+    def to_json_value(self) -> Any:
+        """Used by the request layer's JSON encoder to serialize an embedded, unresolved
+        Promise as its JSONPath string, or a resolved Promise as its real value."""
+        return self._value if self.resolved else str(self._path)
+
+    @property
+    def value(self) -> Any:
+        if not self.resolved:
+            raise UnresolvedPromiseError()
+        return self._value
+
+    def _set_value(self, value: Any) -> None:
+        self._value = value
+
+    def resolve(self) -> Any:
+        """Resolves the promise, executing its pipeline first if necessary."""
+        if self.resolved:
+            return self._value
+        self._pipeline.execute()
+        return self.value
+
+
+class _BasePipeline:
+    def __init__(self, url: str):
+        self._url = url
+        self._steps: List[dict] = []
+        self._promises: List[Promise] = []
+
+    def add_step(self, step: dict) -> Promise:
+        n = len(self._promises)
+        promise = Promise(self, f"$[{n}]")
+        self._steps.append(step)
+        self._promises.append(promise)
+        return promise
+
+    def _reset(self) -> None:
+        self._steps = []
+        self._promises = []
+
+    def _args_for(self, returns: str) -> dict:
+        if returns == "all":
+            return {"steps": self._steps, "returns": "$"}
+        if returns == "last":
+            return {"steps": self._steps, "returns": "$[-1:]"}
+        return {"steps": self._steps, "returns": returns}
+
+
+class Pipeline(_BasePipeline):
+    """A sequence of steps executed together as a single request, via a synchronous
+    execute function injected by the owning (sync) Client."""
+
+    def __init__(self, url: str, execute_fn: Callable[[str, dict], Any]):
+        super().__init__(url)
+        self._execute_fn = execute_fn
+
+    def execute(self, returns: str = "all") -> Any:
+        args = self._args_for(returns)
+        response = self._execute_fn(self._url, args)
+
+        if returns == "all":
+            for promise, value in zip(self._promises, response):
+                promise._set_value(value)
+        elif returns == "last" and self._promises:
+            self._promises[-1]._set_value(response)
+
+        self._reset()
+        return response
+
+
+class AsyncPipeline(_BasePipeline):
+    """Async equivalent of :class:`Pipeline`, via an async execute function injected by
+    the owning (async) AsyncClient."""
+
+    def __init__(self, url: str, execute_fn: Callable[[str, dict], Any]):
+        super().__init__(url)
+        self._execute_fn = execute_fn
+
+    async def execute(self, returns: str = "all") -> Any:
+        args = self._args_for(returns)
+        response = await self._execute_fn(self._url, args)
+
+        if returns == "all":
+            for promise, value in zip(self._promises, response):
+                promise._set_value(value)
+        elif returns == "last" and self._promises:
+            self._promises[-1]._set_value(response)
+
+        self._reset()
+        return response