trustfall 0.3.1__cp315-cp315-win_amd64.whl

trustfall/__init__.py

@@ -0,0 +1,41 @@
+# Error types:
+# - ParseError, when the provided input doesn't even parse as valid syntax
+# - ValidationError, when the input is syntactically valid but doesn't match the schema
+# - FrontendError, when the input's use of the schema is valid but the operations it attempts
+#   are not supported or not valid
+# - InvalidIRQueryError should in principle never be seen in Python. It indicates that
+#   the internal representation could not be converted to its "indexed" (i.e. execution-ready) form.
+# - InvalidSchemaError, when the provided schema cannot be used due to violating some necessary
+#   precondition as explained in the error message.
+# - QueryArgumentsError, if the query by itself is fine but cannot be executed together with
+#   the provided arguments.
+from ._internals import (
+    FrontendError,
+    InvalidIRQueryError,
+    InvalidSchemaError,
+    ParseError,
+    QueryArgumentsError,
+    Schema,
+    ValidationError,
+)
+from .adapter import Adapter, Context, FieldValue
+from .execution import execute_query
+
+__all__ = [
+    # from .adapter
+    "Adapter",
+    "Context",
+    "FieldValue",
+    #
+    # from .execution
+    "execute_query",
+    #
+    # from ._internals (defined in Rust)
+    "FrontendError",
+    "InvalidIRQueryError",
+    "InvalidSchemaError",
+    "ParseError",
+    "QueryArgumentsError",
+    "Schema",
+    "ValidationError",
+]

trustfall/_internals.py

@@ -0,0 +1,27 @@
+from . import trustfall
+
+# Workaround around issue preventing direct `from ._trustfall_internal import X` imports:
+# https://github.com/PyO3/pyo3/issues/759
+# https://github.com/PyO3/pyo3/issues/1517
+_trustfall_internal = trustfall._trustfall_internal
+AdapterShim = _trustfall_internal.AdapterShim
+Schema = _trustfall_internal.Schema
+FrontendError = _trustfall_internal.FrontendError
+InvalidIRQueryError = _trustfall_internal.InvalidIRQueryError
+InvalidSchemaError = _trustfall_internal.InvalidSchemaError
+ParseError = _trustfall_internal.ParseError
+QueryArgumentsError = _trustfall_internal.QueryArgumentsError
+ValidationError = _trustfall_internal.ValidationError
+interpret_query = _trustfall_internal.interpret_query
+
+__all__ = [
+    "AdapterShim",
+    "FrontendError",
+    "InvalidIRQueryError",
+    "InvalidSchemaError",
+    "ParseError",
+    "QueryArgumentsError",
+    "Schema",
+    "ValidationError",
+    "interpret_query",
+]

trustfall/_internals.pyi

@@ -0,0 +1,20 @@
+from typing import Any, Dict, Iterator, Mapping
+
+from .adapter import Adapter
+
+class AdapterShim:
+    def __init__(self, adapter: Adapter[Any]) -> None: ...
+
+class FrontendError(Exception): ...
+class InvalidIRQueryError(Exception): ...
+class InvalidSchemaError(Exception): ...
+class ParseError(Exception): ...
+class QueryArgumentsError(Exception): ...
+class ValidationError(Exception): ...
+
+class Schema:
+    def __init__(self, schema_txt: str) -> None: ...
+
+def interpret_query(
+    adapter: AdapterShim, schema: Schema, query: str, arguments: Mapping[str, Any]
+) -> Iterator[Dict[str, Any]]: ...

trustfall/adapter.py

@@ -0,0 +1,178 @@
+from abc import ABCMeta, abstractmethod
+from typing import (
+    Any,
+    Generic,
+    Iterable,
+    Iterator,
+    Mapping,
+    Optional,
+    Tuple,
+    TypeVar,
+    Union,
+)
+
+FieldValue = Union[None, str, int, float, bool, list["FieldValue"]]
+"""
+The type of property values, query arguments, and columns in the result.
+"""
+
+
+Vertex = TypeVar("Vertex")
+"""
+The type of vertices in the dataset implemented by an adapter.
+"""
+
+
+class Context(Generic[Vertex]):
+    """Adapter helper type. Its active_vertex property indicates vertices whose data is needed."""
+
+    __slots__ = ("_active_vertex",)
+
+    _active_vertex: Optional[Vertex]
+
+    @property
+    def active_vertex(self) -> Optional[Vertex]:
+        """The vertex whose information (properties, edges, etc.) needs to be resolved."""
+        return self._active_vertex
+
+
+class Adapter(Generic[Vertex], metaclass=ABCMeta):
+    @abstractmethod
+    def resolve_starting_vertices(
+        self,
+        edge_name: str,
+        parameters: Mapping[str, FieldValue],
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Vertex]:
+        """Produce an iterable of vertices for the specified starting edge.
+
+        Starting edges are ones where queries are allowed to begin.
+        They are defined directly on the root query type of the schema.
+        For example, `Foo` is the starting edge of the following query:
+        ```graphql
+        query {
+            Foo {
+                bar @output
+            }
+        }
+        ```
+
+        The caller guarantees that:
+        - The specified edge is a starting edge in the schema being queried.
+        - Any parameters the edge requires per the schema have values provided.
+        """
+
+    @abstractmethod
+    def resolve_property(
+        self,
+        contexts: Iterator[Context[Vertex]],
+        type_name: str,
+        property_name: str,
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Tuple[Context[Vertex], FieldValue]]:
+        """Resolve the value of a vertex property, over an iterator of query contexts.
+
+        Each context in the `contexts` argument has an active vertex of type Optional[Vertex],
+        which is either None or represents a vertex of type `type_name` defined in the schema.
+
+        This function resolves the property value on that active vertex.
+
+        The caller guarantees that:
+        - `type_name` is a type or interface defined in the schema.
+        - `property_name` is either a property field on `type_name` defined in the schema,
+          or the special value `"__typename"` requesting the name of the vertex's type.
+        - When the active vertex is not None, then it's a vertex of type `type_name`:
+          either its type is exactly `type_name`, or `type_name` is an interface that
+          the vertex's type implements.
+
+        The returned iterable must satisfy these properties:
+        - Produce `(context, property_value)` tuples with the property's value for that context.
+        - Produce contexts in the same order as the input `contexts` iterator produced them.
+        - Produce property values whose type matches the property's type defined in the schema.
+        - When a context's active vertex is `None`, its property value is `None`.
+        """
+
+    @abstractmethod
+    def resolve_neighbors(
+        self,
+        contexts: Iterator[Context[Vertex]],
+        type_name: str,
+        edge_name: str,
+        parameters: Mapping[str, FieldValue],
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Tuple[Context[Vertex], Iterable[Vertex]]]:
+        """Resolve the neighboring vertices across an edge, over an iterator of query contexts.
+
+        Each context in the `contexts` argument has an active vertex of type Optional[Vertex],
+        which is either None or represents a vertex of type `type_name` defined in the schema.
+
+        This function resolves the neighboring vertices for that active vertex.
+
+        If the schema this adapter covers has no edges aside from starting edges, then
+        this method will never be called and may be implemented as `raise NotImplementedError()`.
+
+        The caller guarantees that:
+        - `type_name` is a type or interface defined in the schema.
+        - `edge_name` is an edge field on `type_name` defined in the schema.
+        - Any parameters the edge requires per the schema have values provided.
+        - When the active vertex is not None, then it's a vertex of type `type_name`:
+          either its type is exactly `type_name`, or `type_name` is an interface that
+          the vertex's type implements.
+
+        The returned iterator must satisfy these properties:
+        - Produce `(context, neighbors)` tuples with an iterator of neighbor vertices for that edge.
+        - Produce contexts in the same order as the input `contexts` iterator produced them.
+        - Each neighboring vertex is of the type specified for that edge in the schema.
+        - When a context's active vertex is None, it has an empty neighbors iterator.
+        """
+
+    @abstractmethod
+    def resolve_coercion(
+        self,
+        contexts: Iterator[Context[Vertex]],
+        type_name: str,
+        coerce_to_type: str,
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Tuple[Context[Vertex], bool]]:
+        """Attempt to coerce vertices to a subtype, over an iterator of query contexts.
+
+        In this example query, the starting vertices of type `Foo` are coerced to `Bar`:
+        ```graphql
+        query {
+            Foo {
+                ... on Bar {
+                    abc @output
+                }
+            }
+        }
+        ```
+
+        Each context in the `contexts` argument has an active vertex of type `Optional[Vertex]`,
+        which is either None or represents a vertex of type `type_name` defined in the schema.
+
+        This function checks whether the active vertex is of the specified subtype.
+
+        If this adapter's schema contains no subtyping, then no type coercions are possible:
+        this method will never be called and may be implemented as `raise NotImplementedError()`.
+
+        The caller guarantees that:
+        - `type_name` is an interface defined in the schema.
+        - `coerce_to_type` is a type or interface that implements `type_name` in the schema.
+        - When the active vertex is not None, then it's a vertex of type `type_name`:
+          either its type is exactly `type_name`, or `type_name` is an interface that
+          the vertex's type implements.
+
+        The returned iterator must satisfy these properties:
+        - Produce `(context, can_coerce)` tuples showing if the coercion succeded for that context.
+        - Produce contexts in the same order as the input `contexts` iterator produced them.
+        - Each neighboring vertex is of the type specified for that edge in the schema.
+        - When a context's active vertex is `None`, its coercion outcome is `False`.
+        """

trustfall/execution.py

@@ -0,0 +1,20 @@
+from typing import Any, Dict, Iterator, Mapping
+
+from ._internals import AdapterShim, Schema, interpret_query
+from .adapter import Adapter, Vertex
+
+
+def execute_query(
+    adapter: Adapter[Vertex],
+    schema: Schema,
+    query: str,
+    arguments: Mapping[str, Any],
+    /,
+) -> Iterator[Dict[str, Any]]:
+    """Execute the given query using the adapter, returning an iterator of result dicts."""
+    if not isinstance(adapter, Adapter):
+        raise TypeError(
+            f"Expected 'adapter' input to be a subclass of Adapter, but instead got: {adapter}"
+        )
+
+    return interpret_query(AdapterShim(adapter), schema, query, arguments)

trustfall/tests/numbers_adapter.py

@@ -0,0 +1,105 @@
+from typing import Any, Iterable, Iterator, Mapping, Tuple, Union, cast
+
+from .. import Adapter, Context, FieldValue
+
+_NUMBER_NAMES = [
+    "zero",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+]
+
+Vertex = int
+
+
+class NumbersAdapter(Adapter[Vertex]):
+    def resolve_starting_vertices(
+        self,
+        edge_name: str,
+        parameters: Mapping[str, FieldValue],
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Vertex]:
+        max_value = cast(int, parameters["max"])  # type known from schema and enforced by Trustfall
+
+        # We could just `yield from range(0, max_value)` here.
+        # But that returns an `Iterator` which is an easier type to deal with than `Iterable`,
+        # and we've had a bug with correct `Iterable` handling already.
+        # So let's return an `Iterable` instead by wrapping it in `list()`.
+        return list(range(0, max_value))
+
+    def resolve_property(
+        self,
+        contexts: Iterator[Context[Vertex]],
+        type_name: str,
+        property_name: str,
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Tuple[Context[Vertex], Any]]:
+        for context in contexts:
+            active_vertex = context.active_vertex
+            value: Union[int, str, None] = None
+            if active_vertex is not None:
+                if property_name == "value":
+                    value = active_vertex
+                elif property_name == "name":
+                    if 0 <= active_vertex < len(_NUMBER_NAMES):
+                        value = _NUMBER_NAMES[active_vertex]
+                else:
+                    raise NotImplementedError()
+
+            yield (context, value)
+
+    def resolve_neighbors(
+        self,
+        contexts: Iterator[Context[Vertex]],
+        type_name: str,
+        edge_name: str,
+        parameters: Mapping[str, FieldValue],
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Tuple[Context[Vertex], Iterable[Vertex]]]:
+        for context in contexts:
+            active_vertex = context.active_vertex
+            neighbors: Iterable[Vertex] = []
+            if active_vertex is not None:
+                if edge_name == "multiple":
+                    if active_vertex > 0:
+                        max_value = cast(
+                            int, parameters["max"]
+                        )  # type known from schema and enforced by Trustfall
+                        neighbors = range(
+                            2 * active_vertex,
+                            max_value * active_vertex + 1,
+                            active_vertex,
+                        )
+                elif edge_name == "predecessor":
+                    if active_vertex > 0:
+                        neighbors = [active_vertex - 1]
+                elif edge_name == "successor":
+                    neighbors = [active_vertex + 1]
+                else:
+                    raise NotImplementedError()
+
+            yield (context, neighbors)
+
+    def resolve_coercion(
+        self,
+        contexts: Iterator[Context[Vertex]],
+        type_name: str,
+        coerce_to_type: str,
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterable[Tuple[Context[Vertex], bool]]:
+        raise NotImplementedError()