veil-api-kit 0.10.0__py3-none-any.whl

veil_kit/di.py

@@ -0,0 +1,362 @@
+"""A dependency injection container on top of ``veil.Depends``.
+
+.. code-block:: python
+
+    from veil_kit.di import Container, Inject
+
+    container = Container()
+    container.singleton(Settings, lambda: Settings.from_env())
+    container.scoped(Session, make_session)              # once per request; make_session may yield
+    container.transient(Clock, Clock)
+
+    @container.provider(Repo, scope="scoped")
+    def repo(session: Session, settings: Settings):      # parameters of registered types are injected
+        return Repo(session, settings)
+
+    @app.get("/items")
+    def items(repo: Repo = Inject(Repo)):
+        return repo.list()
+
+    with container.override(Repo, FakeRepo()):           # tests
+        ...
+
+A provider is resolved through ``veil.Depends``: its parameters may also be request parameters (``Query``,
+``Header``, ``request: veil.Request``, other ``Depends``) and generators clean up after the request. ``singleton``
+values are created once per process (thread-safe), ``scoped`` once per request, ``transient`` on every use.
+Registrations may come after the routes that use them, until the server starts.
+"""
+
+# F-268: 解決は veil の Depends の木（登録時に組み立て、要求ごとは決まった順に呼ぶ）。差し替えは提供者の入れ替え。
+
+import contextlib
+import inspect
+import threading
+
+import veil
+
+__all__ = ["Container", "Inject", "SINGLETON", "SCOPED", "TRANSIENT"]
+
+SINGLETON, SCOPED, TRANSIENT = "singleton", "scoped", "transient"
+
+_current = None
+
+
+class _Registration:
+    __slots__ = ("key", "factory", "scope", "value", "lock", "has_value", "resolver")
+
+    def __init__(self, key, factory, scope):
+        self.key = key
+        self.factory = factory
+        self.scope = scope
+        self.value = None
+        self.has_value = False
+        self.lock = threading.Lock()
+        self.resolver = None
+
+
+class Container:
+    """Providers by type (or any hashable key)."""
+
+    def __init__(self):
+        """Create an empty container."""
+        self._regs = {}
+        self._overrides = {}
+        self._stubs = {}
+        global _current
+        _current = self
+
+    # ---- 登録 ----
+
+    def register(self, key, factory=None, scope=SCOPED):
+        """Register ``factory`` (a callable, or a value for ``singleton``) for ``key``; ``factory`` defaults to ``key``."""
+        if scope not in (SINGLETON, SCOPED, TRANSIENT):
+            raise ValueError("scope must be singleton, scoped or transient")
+        if factory is None:
+            factory = key
+        if not callable(factory):
+            value = factory
+            reg = _Registration(key, None, SINGLETON)
+            reg.value, reg.has_value = value, True
+        else:
+            reg = _Registration(key, factory, scope)
+        self._regs[key] = reg
+        self._stubs.pop(key, None)
+        return self
+
+    def singleton(self, key, factory=None):
+        """Register a provider created once per process (or a ready value)."""
+        return self.register(key, factory, SINGLETON)
+
+    def scoped(self, key, factory=None):
+        """Register a provider created once per request."""
+        return self.register(key, factory, SCOPED)
+
+    def transient(self, key, factory=None):
+        """Register a provider created on every use."""
+        return self.register(key, factory, TRANSIENT)
+
+    def value(self, key, value):
+        """Register an existing value."""
+        reg = _Registration(key, None, SINGLETON)
+        reg.value, reg.has_value = value, True
+        self._regs[key] = reg
+        self._stubs.pop(key, None)
+        return self
+
+    def provider(self, key, scope=SCOPED):
+        """Decorator form of :meth:`register`."""
+
+        def deco(f):
+            self.register(key, f, scope)
+            return f
+
+        return deco
+
+    # ---- 解決 ----
+
+    def depends(self, key):
+        """The ``veil.Depends`` marker for ``key`` (``Inject(key)`` uses the current container)."""
+        reg = self._regs.get(key)
+        scope = reg.scope if reg is not None else SCOPED
+        return veil.Depends(self._resolver(key), use_cache=scope != TRANSIENT)
+
+    def _resolver(self, key):
+        stub = self._stubs.get(key)
+        if stub is not None:
+            return stub
+        reg = self._regs.get(key)
+        if reg is None:
+            # まだ登録されていない: 呼ばれたとき（起動後）に解決する（ジェネレータの提供者は要求の後に閉じる）
+            container = self
+
+            def late(request: veil.Request):
+                o = container._overrides.get(key, _MISSING)
+                if o is not _MISSING:
+                    yield o
+                    return
+                reg = container._regs.get(key)
+                if reg is None:
+                    raise LookupError("no provider registered for %r" % (key,))
+                if reg.has_value or reg.scope == SINGLETON:
+                    yield container.get(key)
+                    return
+                v = reg.factory(**container._registered_kwargs(reg.factory))
+                if inspect.isgenerator(v):
+                    yield from _once(v)
+                    return
+                if inspect.isawaitable(v):
+                    from veil import _run_coro
+
+                    v = _run_coro(v)
+                yield v
+
+            late._veil_inline = True
+            stub = late
+        else:
+            stub = self._make_resolver(reg)
+        self._stubs[key] = stub
+        return stub
+
+    def _make_resolver(self, reg):
+        container = self
+        key = reg.key
+        if reg.has_value:
+            def value_resolver():
+                o = container._overrides.get(key, _MISSING)
+                return reg.value if o is _MISSING else o
+
+            value_resolver._veil_inline = True
+            return value_resolver
+        factory = reg.factory
+        sig = _injected_signature(self, factory)
+        regs = self._regs
+        kind = "gen" if inspect.isgeneratorfunction(factory) else (
+            "agen" if inspect.isasyncgenfunction(factory) else (
+                "async" if inspect.iscoroutinefunction(factory) else "sync"))
+
+        if reg.scope == SINGLETON:
+            def resolver(**kw):
+                o = container._overrides.get(key, _MISSING)
+                if o is not _MISSING:
+                    return o
+                cur = regs[key]
+                if not cur.has_value:
+                    with cur.lock:
+                        if not cur.has_value:
+                            v = cur.factory(**kw)
+                            if inspect.isawaitable(v):
+                                from veil import _run_coro
+
+                                v = _run_coro(v)
+                            cur.value, cur.has_value = v, True
+                return cur.value
+        elif kind == "gen":
+            def resolver(**kw):
+                o = container._overrides.get(key, _MISSING)
+                if o is not _MISSING:
+                    yield o
+                    return
+                yield from regs[key].factory(**kw)
+        elif kind == "agen":
+            async def resolver(**kw):
+                o = container._overrides.get(key, _MISSING)
+                if o is not _MISSING:
+                    yield o
+                    return
+                async for v in regs[key].factory(**kw):
+                    yield v
+        elif kind == "async":
+            async def resolver(**kw):
+                o = container._overrides.get(key, _MISSING)
+                if o is not _MISSING:
+                    return o
+                return await regs[key].factory(**kw)
+        else:
+            def resolver(**kw):
+                o = container._overrides.get(key, _MISSING)
+                if o is not _MISSING:
+                    return o
+                return regs[key].factory(**kw)
+
+        resolver.__signature__ = sig
+        resolver.__annotations__ = {p.name: p.annotation for p in sig.parameters.values()
+                                    if p.annotation is not inspect.Parameter.empty}
+        resolver.__name__ = "provide_%s" % getattr(key, "__name__", "value")
+        resolver.__qualname__ = resolver.__name__
+        resolver.__module__ = getattr(factory, "__module__", __name__)
+        if getattr(factory, "_veil_inline", False):
+            resolver._veil_inline = True
+        return resolver
+
+    def get(self, key):
+        """Resolve ``key`` outside a request (singletons and providers without request parameters; a generator
+        provider gives its first value and its code after ``yield`` is not run)."""
+        o = self._overrides.get(key, _MISSING)
+        if o is not _MISSING:
+            return o
+        reg = self._regs.get(key)
+        if reg is None:
+            raise LookupError("no provider registered for %r" % (key,))
+        if reg.has_value:
+            return reg.value
+        kwargs = self._registered_kwargs(reg.factory)
+        if reg.scope == SINGLETON:
+            with reg.lock:
+                if not reg.has_value:
+                    reg.value, reg.has_value = reg.factory(**kwargs), True
+            return reg.value
+        v = reg.factory(**kwargs)
+        if inspect.isgenerator(v):
+            # 要求の外: 最初の値を返す（yield の後は実行しない）
+            return next(v)
+        if inspect.isawaitable(v):
+            from veil import _run_coro
+
+            v = _run_coro(v)
+        return v
+
+    def _registered_kwargs(self, factory):
+        # 登録された型の引数だけを解決する（要求の引数は無い前提）
+        kwargs = {}
+        for p in _injected_signature(self, factory).parameters.values():
+            d = p.default
+            if isinstance(d, veil.Depends) and d.dependency in self._stubs.values():
+                kwargs[p.name] = self.get(_key_of(self, d.dependency))
+        return kwargs
+
+    # ---- 差し替え ----
+
+    @contextlib.contextmanager
+    def override(self, key, value):
+        """Use ``value`` for ``key`` inside the ``with`` block (tests); requests in progress may see either."""
+        old = self._overrides.get(key, _MISSING)
+        self._overrides[key] = value
+        try:
+            yield value
+        finally:
+            if old is _MISSING:
+                self._overrides.pop(key, None)
+            else:
+                self._overrides[key] = old
+
+    def replace(self, key, factory, app=None):
+        """Replace the provider of ``key`` while the server runs (new requests use it).
+
+        A provider with the same parameters is swapped in place. One with other parameters needs ``app``: the routes
+        are rebuilt through ``app.dependency_overrides``.
+        """
+        reg = self._regs.get(key)
+        if reg is None:
+            self.register(key, factory)
+            return
+        old = self._stubs.get(key)
+        if app is not None and old is not None:
+            new = self._make_resolver(_Registration(key, factory, reg.scope))
+            app.dependency_overrides[old] = new
+            return
+        if old is not None and _injected_signature(self, factory) != _injected_signature(self, reg.factory):
+            raise ValueError("the new provider has other parameters; pass app= to rebuild the routes")
+        reg.factory = factory
+        reg.has_value = False
+        reg.value = None
+
+    def reset(self, key):
+        """Forget the cached singleton value of ``key``."""
+        reg = self._regs.get(key)
+        if reg is not None and reg.factory is not None:
+            reg.has_value = False
+            reg.value = None
+
+
+_MISSING = object()
+
+
+def _once(gen):
+    # ジェネレータの提供者の最初の値を渡し、要求の後に残りを実行する
+    v = next(gen)
+    try:
+        yield v
+    finally:
+        try:
+            next(gen)
+        except StopIteration:
+            pass
+
+
+def _key_of(container, resolver):
+    for k, v in container._stubs.items():
+        if v is resolver:
+            return k
+    raise LookupError(resolver)
+
+
+def _injected_signature(container, factory):
+    """The signature of ``factory`` with the parameters of registered types turned into ``Depends``."""
+    target = factory.__init__ if inspect.isclass(factory) else factory
+    try:
+        sig = inspect.signature(factory)
+    except (TypeError, ValueError):
+        return inspect.Signature()
+    try:
+        import typing
+
+        hints = typing.get_type_hints(target)
+    except Exception:  # noqa: BLE001
+        hints = {}
+    params = []
+    for p in sig.parameters.values():
+        ann = hints.get(p.name, p.annotation)
+        if p.default is inspect.Parameter.empty and ann in container._regs:
+            p = p.replace(default=container.depends(ann), annotation=ann)
+        elif ann is not inspect.Parameter.empty:
+            p = p.replace(annotation=ann)
+        params.append(p)
+    return sig.replace(parameters=params, return_annotation=inspect.Signature.empty)
+
+
+def Inject(key, container=None):  # noqa: N802
+    """``param: T = Inject(T)``: the ``veil.Depends`` marker for ``key`` in ``container`` (the last created by default)."""
+    c = container or _current
+    if c is None:
+        raise RuntimeError("create a Container before using Inject()")
+    return c.depends(key)

veil_kit/graphql.py

@@ -0,0 +1,215 @@
+"""GraphQL with strawberry (``pip install "veil-api-kit[graphql]"``).
+
+.. code-block:: python
+
+    import strawberry
+    from veil_kit.graphql import mount
+
+    schema = strawberry.Schema(query=Query, mutation=Mutation, subscription=Subscription)
+    mount(app, "/graphql", schema)
+
+One path serves ``POST`` (JSON, batches too) and ``GET`` (query string), GraphQL over SSE for subscriptions
+(``Accept: text/event-stream``), WebSocket subscriptions (``graphql-transport-ws`` and the older ``graphql-ws``) and
+GraphiQL for a browser ``GET`` (``graphiql=False`` turns it off; the page loads its scripts from a CDN).
+``context_getter(request)`` builds the context passed to resolvers (default: ``{"request": request}``).
+"""
+
+# F-268: examples/api/python-graphql（F-210）を取り込み、WebSocket（F-263）のサブスクリプションを足した
+
+import asyncio
+import json
+
+import veil
+
+__all__ = ["mount", "GraphQLRoutes"]
+
+_GRAPHQL_RESPONSE = "application/graphql-response+json"
+
+
+def _result(r):
+    out = {"data": r.data}
+    if r.errors:
+        out["errors"] = [e.formatted if hasattr(e, "formatted") else {"message": str(e)} for e in r.errors]
+    if getattr(r, "extensions", None):
+        out["extensions"] = r.extensions
+    return out
+
+
+def _graphiql_html(path):
+    try:
+        from strawberry.http.ide import get_graphql_ide_html  # noqa: PLC0415
+
+        return get_graphql_ide_html(graphql_ide="graphiql")
+    except ImportError:
+        pass
+    try:
+        from strawberry.utils.graphiql import get_graphiql_html  # noqa: PLC0415
+
+        return get_graphiql_html()
+    except ImportError:
+        pass
+    return (
+        "<!doctype html><html><head><title>GraphiQL</title>"
+        '<link rel="stylesheet" href="https://unpkg.com/graphiql@3/graphiql.min.css"></head>'
+        '<body style="margin:0"><div id="g" style="height:100vh"></div>'
+        '<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>'
+        '<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>'
+        '<script src="https://unpkg.com/graphiql@3/graphiql.min.js"></script>'
+        "<script>ReactDOM.createRoot(document.getElementById('g')).render(React.createElement(GraphiQL,"
+        "{fetcher:GraphiQL.createFetcher({url:%s})}))</script></body></html>" % json.dumps(path)
+    )
+
+
+class GraphQLRoutes:
+    """The routes of one schema (created by :func:`mount`)."""
+
+    def __init__(self, schema, path, graphiql=True, context_getter=None, keep_alive=None):
+        self.schema = schema
+        self.path = path
+        self.graphiql = graphiql
+        self.context_getter = context_getter or (lambda request: {"request": request})
+        self.keep_alive = keep_alive
+
+    async def _execute(self, body, request):
+        ctx = self.context_getter(request)
+        if isinstance(ctx, asyncio.Future) or asyncio.iscoroutine(ctx):
+            ctx = await ctx
+        r = await self.schema.execute(body.get("query") or "", variable_values=body.get("variables"),
+                                      operation_name=body.get("operationName"), context_value=ctx)
+        return _result(r)
+
+    async def _subscribe(self, body, request):
+        ctx = self.context_getter(request)
+        if asyncio.iscoroutine(ctx):
+            ctx = await ctx
+        r = await self.schema.subscribe(body.get("query") or "", variable_values=body.get("variables"),
+                                        operation_name=body.get("operationName"), context_value=ctx)
+        if hasattr(r, "__aiter__"):
+            async for x in r:
+                yield _result(x)
+        else:
+            yield _result(r)
+
+    async def http(self, request: veil.Request):
+        """``GET`` / ``POST`` on the GraphQL path."""
+        accept = request.headers.get("accept") or ""
+        if request.method in ("GET", "HEAD"):
+            q = request.query_params
+            if not q.get("query"):
+                if self.graphiql and "text/html" in accept:
+                    return veil.HTMLResponse(_graphiql_html(self.path))
+                raise veil.HTTPException(400, "missing query")
+            try:
+                variables = json.loads(q["variables"]) if q.get("variables") else None
+            except ValueError:
+                raise veil.HTTPException(400, "variables is not valid JSON")
+            body = {"query": q.get("query"), "variables": variables, "operationName": q.get("operationName")}
+        else:
+            try:
+                body = json.loads(request.body or b"null")
+            except ValueError:
+                raise veil.HTTPException(400, "the body is not valid JSON")
+        if "text/event-stream" in accept:
+            if not isinstance(body, dict):
+                raise veil.HTTPException(400, "subscriptions over SSE take one operation")
+
+            async def events():
+                async for r in self._subscribe(body, request):
+                    yield {"event": "next", "data": r}
+                yield {"event": "complete", "data": ""}
+
+            return veil.EventSourceResponse(events())
+        if isinstance(body, list):
+            out = [await self._execute(b, request) for b in body if isinstance(b, dict)]
+        elif isinstance(body, dict):
+            out = await self._execute(body, request)
+        else:
+            raise veil.HTTPException(400, "a GraphQL request is a JSON object")
+        media = _GRAPHQL_RESPONSE if _GRAPHQL_RESPONSE in accept else "application/json"
+        return veil.Response(json.dumps(out, separators=(",", ":")), 200, media_type=media)
+
+    async def websocket(self, websocket: veil.WebSocket):
+        """Subscriptions over WebSocket (``graphql-transport-ws`` and ``graphql-ws``)."""
+        offered = websocket.subprotocols
+        proto = next((p for p in ("graphql-transport-ws", "graphql-ws") if p in offered), None)
+        if proto is None:
+            await websocket.close(4406)
+            return
+        await websocket.accept(subprotocol=proto)
+        legacy = proto == "graphql-ws"
+        ops = {}
+        acked = False
+
+        async def run(op_id, payload):
+            try:
+                async for r in self._subscribe(payload, websocket):
+                    await websocket.send_json({"type": "data" if legacy else "next", "id": op_id, "payload": r})
+                await websocket.send_json({"type": "complete", "id": op_id})
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:  # noqa: BLE001
+                await websocket.send_json({"type": "error", "id": op_id, "payload": [{"message": str(e)}]})
+            finally:
+                ops.pop(op_id, None)
+
+        try:
+            while True:
+                try:
+                    msg = await websocket.receive_json()
+                except veil.WebSocketDisconnect:
+                    break
+                except (ValueError, TypeError):
+                    await websocket.close(4400, "invalid message")
+                    break
+                t = msg.get("type") if isinstance(msg, dict) else None
+                if t == "connection_init":
+                    if acked and not legacy:
+                        await websocket.close(4429, "Too many initialisation requests")
+                        break
+                    acked = True
+                    await websocket.send_json({"type": "connection_ack"})
+                elif t == "ping":
+                    await websocket.send_json({"type": "pong", "payload": msg.get("payload")})
+                elif t == "pong":
+                    pass
+                elif t in ("subscribe", "start"):
+                    if not acked:
+                        await websocket.close(4401, "Unauthorized")
+                        break
+                    op_id = msg.get("id")
+                    if op_id in ops:
+                        await websocket.close(4409, "Subscriber for %s already exists" % op_id)
+                        break
+                    ops[op_id] = asyncio.get_running_loop().create_task(run(op_id, msg.get("payload") or {}))
+                elif t in ("complete", "stop"):
+                    task = ops.pop(msg.get("id"), None)
+                    if task is not None:
+                        task.cancel()
+                elif t == "connection_terminate":
+                    await websocket.close(1000)
+                    break
+                else:
+                    await websocket.close(4400, "Unknown message type")
+                    break
+        finally:
+            for task in list(ops.values()):
+                task.cancel()
+
+
+def mount(app, path, schema, *, graphiql=True, context_getter=None, websocket=True):
+    """Serve ``schema`` (a ``strawberry.Schema``) at ``path`` on ``app``; returns the :class:`GraphQLRoutes`."""
+    routes = GraphQLRoutes(schema, path, graphiql, context_getter)
+
+    async def graphql_http(request: veil.Request):
+        return await routes.http(request)
+
+    graphql_http.__name__ = "graphql" + path.replace("/", "_").replace("{", "").replace("}", "")
+    app.route(path, methods=["GET", "POST"], tags=["graphql"], summary="GraphQL endpoint")(graphql_http)
+    if websocket:
+        async def graphql_ws(websocket: veil.WebSocket):
+            await routes.websocket(websocket)
+
+        graphql_ws.__name__ = graphql_http.__name__ + "_ws"
+        # 同じパスの GET と WebSocket は、サーバが Upgrade の有無で振り分ける
+        app.websocket(path, subprotocols=["graphql-transport-ws", "graphql-ws"], include_in_schema=False)(graphql_ws)
+    return routes