errpath 0.1.0__py3-none-any.whl

errpath/__init__.py

@@ -0,0 +1,19 @@
+"""errpath: Result types for Python. See every error path."""
+
+from errpath.result import Err, Ok, Result, err_type, ok, traceback_of
+from errpath.safe import safe, safe_async, safe_async_with, safe_with
+
+__all__ = [
+    "Err",
+    "Ok",
+    "Result",
+    "err_type",
+    "ok",
+    "safe",
+    "safe_async",
+    "safe_async_with",
+    "safe_with",
+    "traceback_of",
+]
+
+__version__ = "0.1.0"

errpath/__main__.py

@@ -0,0 +1,4 @@
+from errpath.cli import main
+
+if __name__ == "__main__":
+    main()

errpath/_pydantic.py

@@ -0,0 +1,102 @@
+"""Pydantic support for Ok / Err. Imported only when Pydantic asks for a schema.
+
+JSON shape (the same as awaitly's):
+
+    {"ok": true, "value": ...}
+    {"ok": false, "error": ...}
+
+An exception error is written as {"type": "KeyError", "message": "..."}. It can't be
+read back from JSON (an exception isn't data), so use a model, str or enum as the
+error type for Results that travel through APIs.
+"""
+
+from __future__ import annotations
+
+import types
+import typing
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+from pydantic_core import PydanticSerializationUnexpectedValue
+from pydantic_core import core_schema as cs
+
+
+def _exception_types(tp: Any) -> tuple[type[BaseException], ...] | None:
+    """The exception classes in ``tp`` (a class or a union of them), or None if it isn't one."""
+    members = (
+        typing.get_args(tp) if typing.get_origin(tp) in (typing.Union, types.UnionType) else (tp,)
+    )
+    if members and all(isinstance(m, type) and issubclass(m, BaseException) for m in members):
+        return members
+    return None
+
+
+def _describe_exception(error: BaseException) -> dict[str, str]:
+    return {"type": type(error).__name__, "message": str(error)}
+
+
+def result_schema(
+    cls: type, source: Any, handler: GetCoreSchemaHandler, *, ok: bool
+) -> cs.CoreSchema:
+    field = "value" if ok else "error"
+    args = typing.get_args(source)
+    payload_type = args[0] if args else Any
+
+    exceptions = _exception_types(payload_type)
+    to_payload: Callable[[Any], Any]
+    if exceptions:
+        payload = cs.union_schema([cs.is_instance_schema(e) for e in exceptions])
+        payload_out = cs.typed_dict_schema(
+            {
+                "type": cs.typed_dict_field(cs.str_schema()),
+                "message": cs.typed_dict_field(cs.str_schema()),
+            }
+        )
+        to_payload = _describe_exception
+    else:
+        payload = handler.generate_schema(payload_type)
+        payload_out = payload
+        to_payload = lambda value: value  # noqa: E731
+
+    def shape(inner: cs.CoreSchema) -> cs.CoreSchema:
+        return cs.typed_dict_schema(
+            {
+                "ok": cs.typed_dict_field(cs.literal_schema([ok])),
+                field: cs.typed_dict_field(inner),
+            }
+        )
+
+    # {"ok": ..., "value"/"error": ...} -> Ok/Err, validating the payload.
+    from_dict = cs.no_info_after_validator_function(lambda d: cls(d[field]), shape(payload))
+    # An existing Ok/Err is re-checked the same way, so Ok("not a User") is rejected.
+    from_instance = cs.chain_schema(
+        [
+            cs.is_instance_schema(cls),
+            cs.no_info_plain_validator_function(lambda r: {"ok": ok, field: getattr(r, field)}),
+            from_dict,
+        ]
+    )
+
+    def serialize(result: Any, handler: cs.SerializerFunctionWrapHandler) -> Any:
+        if not isinstance(result, cls):
+            # In Ok | Err, both serializers are tried; this tells Pydantic to use the other.
+            raise PydanticSerializationUnexpectedValue(f"not an {cls.__name__}")
+        # Hand the dict back to Pydantic, so include/exclude reach the payload's fields
+        # (e.g. exclude={"result": {"value": {"secret"}}}).
+        return handler({"ok": ok, field: to_payload(getattr(result, field))})
+
+    def document_written_shape(schema: cs.CoreSchema, handler: GetJsonSchemaHandler) -> Any:
+        # An exception is validated by instance check (no JSON Schema) but written as
+        # {type, message}; document what is written. (return_schema would do this too, but
+        # it serializes a second time, which breaks include/exclude.)
+        if handler.mode == "serialization":
+            return handler(shape(payload_out))
+        return handler(schema)
+
+    return cs.json_or_python_schema(
+        json_schema=from_dict,
+        python_schema=cs.union_schema([from_instance, from_dict]),
+        serialization=cs.wrap_serializer_function_ser_schema(serialize, schema=shape(payload_out)),
+        metadata={"pydantic_js_functions": [document_written_shape]} if exceptions else None,
+    )