hexastack-graphql 0.0.0__tar.gz

hexastack_graphql-0.0.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.3
+Name: hexastack-graphql
+Version: 0.0.0
+Summary: Strawberry GraphQL presentation adapter and CQRS integration for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: strawberry-graphql>=0.260.0
+Requires-Dist: fastapi>=0.141.1 ; extra == 'fastapi'
+Requires-Dist: hexastack-fastapi ; extra == 'fastapi'
+Requires-Python: >=3.13
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# hexastack-graphql
+
+> Strawberry GraphQL presentation adapter and CQRS integration for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-graphql` brings the power and type-safety of [Strawberry GraphQL](https://strawberry.rocks/) into the Hexastack architecture:
+
+- **Type-Safe GraphQL Schemas**: Native Python dataclass-based GraphQL schema definition via Strawberry.
+- **CQRS Integration via Context**: Injects the `rodi.Container`, `CommandBusPort`, and `QueryBusPort` directly into Strawberry's `Info.context` (`GraphQLContext`).
+- **Declarative Query & Mutation Registries**:
+  - `@graphql_query_type` and `@graphql_mutation_type`: Register whole type classes to be merged into root Query and Mutation types.
+  - `@graphql_query` and `@graphql_mutation`: Register standalone resolver functions as top-level fields.
+- **Dynamic Field Resolver Feature Flagging**:
+  - `@feature_flag_field("flag_key", raise_error=True, fallback=...)`: Evaluates feature flags dynamically before executing field resolvers, raising a `GraphQLError` or returning a safe fallback value.
+- **FastAPI Mount & GraphiQL Playground**: Seamless mounting as a `GraphQLRouter` into FastAPI applications with interactive GraphiQL playground enabled.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_graphql/
+├── domain/          # GraphQLContext, GraphQLError, SchemaBuildingError
+├── ports/           # GraphQLContextFactoryPort
+├── adapters/        # create_graphql_router, mount_graphql_router (FastAPI integration)
+└── infra/
+    ├── bootstrap.py # GraphQLBootstrapper (order=35)
+    ├── config.py    # HexastackGraphQLConfig
+    ├── decorators.py# @graphql_query, @graphql_mutation, @graphql_query_type, @graphql_mutation_type, @feature_flag_field
+    └── registries/  # schema.py (GraphQLSchemaRegistry)
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Bootstrap** | `GraphQLBootstrapper` (order=35), `HexastackGraphQLConfig` |
+| **Context & Domain** | `GraphQLContext`, `GraphQLError`, `SchemaBuildingError` |
+| **Decorators** | `@graphql_query`, `@graphql_mutation`, `@graphql_query_type`, `@graphql_mutation_type`, `@feature_flag_field` |
+| **FastAPI Adapters** | `create_graphql_router`, `mount_graphql_router` |
+| **Registries** | `GraphQLSchemaRegistry`, `get_schema_registry` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph ClientRequests ["GraphQL Client Requests"]
+        CLIENT["Web / Mobile GraphQL Clients"]
+    end
+
+    subgraph GraphQLAdapter ["hexastack-graphql"]
+        SCHEMA["strawberry.Schema"]
+        CTX["GraphQLContext (Container + Buses)"]
+        ROUTER["GraphQLRouter (FastAPI integration)"]
+    end
+
+    subgraph ApplicationLayer ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph WebServer ["hexastack-fastapi"]
+        FASTAPI_APP["FastAPI Application"]
+    end
+
+    CLIENT --> ROUTER
+    FASTAPI_APP --> ROUTER
+    ROUTER --> SCHEMA
+    SCHEMA --> CTX
+    CTX -->|dispatches commands/queries to| CBUS
+    CTX -->|dispatches commands/queries to| QBUS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, configuration registry, base exceptions.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `strawberry-graphql>=0.260.0`: Core GraphQL engine and schema generator.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **FastAPI Auto-Mounting**: `GraphQLBootstrapper` (order=35) discovers the `FastAPI` instance created by `FastApiBootstrapper` (order=30) and attaches the `GraphQLRouter` automatically if `auto_mount_fastapi=true`.
+- **CQRS Dispatching**: Field resolvers receive `info.context.query_bus` and `info.context.command_bus` to delegate execution into the CQRS pipeline.
+
+### Optional Integrations (Extras)
+- `[fastapi]`: Installs `hexastack-fastapi` and `fastapi>=0.141.1` for HTTP routing and GraphiQL playground.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-graphql
+
+# With FastAPI integration
+pip install "hexastack-graphql[fastapi]"
+
+# Via umbrella package
+pip install "hexastack[graphql]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.graphql]
+path = "/graphql" # Route prefix for GraphQL endpoint
+graphiql = true # Enable interactive GraphiQL web UI
+allow_queries = true
+allow_mutations = true
+auto_mount_fastapi = true # Auto mount onto FastAPI application on bootstrap
+title = "Hexastack GraphQL API"
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+import strawberry
+from strawberry.types import Info
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_graphql.domain.context import GraphQLContext
+from hexastack_graphql.infra.decorators import graphql_query_type
+
+
+# 1. Define CQRS Query & Handler
+@dataclass(frozen=True)
+class GetItemQuery(Query):
+    item_id: str
+
+
+@query_handler(GetItemQuery)
+class GetItemHandler:
+    def __call__(self, qry: GetItemQuery) -> dict:
+        return {"id": qry.item_id, "name": f"Item {qry.item_id}"}
+
+
+# 2. Define Strawberry GraphQL Type
+@strawberry.type
+class ItemType:
+    id: str
+    name: str
+
+
+@graphql_query_type
+class Query:
+    @strawberry.field
+    def item(self, info: Info[GraphQLContext, None], item_id: str) -> ItemType:
+        res = info.context.query_bus.dispatch(GetItemQuery(item_id=item_id))
+        return ItemType(id=res["id"], name=res["name"])
+
+
+# 3. Bootstrap Runtime with GraphQL
+runtime = bootstrap(packages_to_scan=[__name__])
+schema = runtime.get("graphql_schema")
+
+result = schema.execute_sync(
+    '{ item(itemId: "123") { id name } }',
+    context_value=GraphQLContext(
+        container=runtime.container, query_bus=runtime.get("query_bus")
+    ),
+)
+print(result.data)  # {'item': {'id': '123', 'name': 'Item 123'}}
+```

hexastack_graphql-0.0.0/README.md

@@ -0,0 +1,175 @@
+# hexastack-graphql
+
+> Strawberry GraphQL presentation adapter and CQRS integration for Hexastack.
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## 1. Overview & Capabilities
+
+`hexastack-graphql` brings the power and type-safety of [Strawberry GraphQL](https://strawberry.rocks/) into the Hexastack architecture:
+
+- **Type-Safe GraphQL Schemas**: Native Python dataclass-based GraphQL schema definition via Strawberry.
+- **CQRS Integration via Context**: Injects the `rodi.Container`, `CommandBusPort`, and `QueryBusPort` directly into Strawberry's `Info.context` (`GraphQLContext`).
+- **Declarative Query & Mutation Registries**:
+  - `@graphql_query_type` and `@graphql_mutation_type`: Register whole type classes to be merged into root Query and Mutation types.
+  - `@graphql_query` and `@graphql_mutation`: Register standalone resolver functions as top-level fields.
+- **Dynamic Field Resolver Feature Flagging**:
+  - `@feature_flag_field("flag_key", raise_error=True, fallback=...)`: Evaluates feature flags dynamically before executing field resolvers, raising a `GraphQLError` or returning a safe fallback value.
+- **FastAPI Mount & GraphiQL Playground**: Seamless mounting as a `GraphQLRouter` into FastAPI applications with interactive GraphiQL playground enabled.
+
+---
+
+## 2. Package Anatomy & Key Components
+
+```
+hexastack_graphql/
+├── domain/          # GraphQLContext, GraphQLError, SchemaBuildingError
+├── ports/           # GraphQLContextFactoryPort
+├── adapters/        # create_graphql_router, mount_graphql_router (FastAPI integration)
+└── infra/
+    ├── bootstrap.py # GraphQLBootstrapper (order=35)
+    ├── config.py    # HexastackGraphQLConfig
+    ├── decorators.py# @graphql_query, @graphql_mutation, @graphql_query_type, @graphql_mutation_type, @feature_flag_field
+    └── registries/  # schema.py (GraphQLSchemaRegistry)
+```
+
+### Key Exports
+
+| Category | Exports |
+|---|---|
+| **Bootstrap** | `GraphQLBootstrapper` (order=35), `HexastackGraphQLConfig` |
+| **Context & Domain** | `GraphQLContext`, `GraphQLError`, `SchemaBuildingError` |
+| **Decorators** | `@graphql_query`, `@graphql_mutation`, `@graphql_query_type`, `@graphql_mutation_type`, `@feature_flag_field` |
+| **FastAPI Adapters** | `create_graphql_router`, `mount_graphql_router` |
+| **Registries** | `GraphQLSchemaRegistry`, `get_schema_registry` |
+
+---
+
+## 3. Monorepo & Sibling Relationships
+
+```mermaid
+graph TD
+    subgraph ClientRequests ["GraphQL Client Requests"]
+        CLIENT["Web / Mobile GraphQL Clients"]
+    end
+
+    subgraph GraphQLAdapter ["hexastack-graphql"]
+        SCHEMA["strawberry.Schema"]
+        CTX["GraphQLContext (Container + Buses)"]
+        ROUTER["GraphQLRouter (FastAPI integration)"]
+    end
+
+    subgraph ApplicationLayer ["hexastack-cqrs"]
+        CBUS["CommandBusPort"]
+        QBUS["QueryBusPort"]
+    end
+
+    subgraph WebServer ["hexastack-fastapi"]
+        FASTAPI_APP["FastAPI Application"]
+    end
+
+    CLIENT --> ROUTER
+    FASTAPI_APP --> ROUTER
+    ROUTER --> SCHEMA
+    SCHEMA --> CTX
+    CTX -->|dispatches commands/queries to| CBUS
+    CTX -->|dispatches commands/queries to| QBUS
+```
+
+### Explicit Dependencies (Direct)
+- `hexastack-core`: DI container, configuration registry, base exceptions.
+- `hexastack-cqrs`: `CommandBusPort` and `QueryBusPort` for message dispatching.
+- `strawberry-graphql>=0.260.0`: Core GraphQL engine and schema generator.
+
+### Implied / Behavioral Relationships (DI-Mediated)
+- **FastAPI Auto-Mounting**: `GraphQLBootstrapper` (order=35) discovers the `FastAPI` instance created by `FastApiBootstrapper` (order=30) and attaches the `GraphQLRouter` automatically if `auto_mount_fastapi=true`.
+- **CQRS Dispatching**: Field resolvers receive `info.context.query_bus` and `info.context.command_bus` to delegate execution into the CQRS pipeline.
+
+### Optional Integrations (Extras)
+- `[fastapi]`: Installs `hexastack-fastapi` and `fastapi>=0.141.1` for HTTP routing and GraphiQL playground.
+
+---
+
+## 4. Installation
+
+```bash
+# Standalone install
+pip install hexastack-graphql
+
+# With FastAPI integration
+pip install "hexastack-graphql[fastapi]"
+
+# Via umbrella package
+pip install "hexastack[graphql]"
+```
+
+---
+
+## 5. Configuration Reference
+
+```toml
+[hexastack.graphql]
+path = "/graphql" # Route prefix for GraphQL endpoint
+graphiql = true # Enable interactive GraphiQL web UI
+allow_queries = true
+allow_mutations = true
+auto_mount_fastapi = true # Auto mount onto FastAPI application on bootstrap
+title = "Hexastack GraphQL API"
+```
+
+---
+
+## 6. Quickstart Example
+
+```python
+from dataclasses import dataclass
+import strawberry
+from strawberry.types import Info
+from hexastack_core.infra.bootstrap import bootstrap
+from hexastack_cqrs.domain.query import Query
+from hexastack_cqrs.infra.decorators import query_handler
+from hexastack_graphql.domain.context import GraphQLContext
+from hexastack_graphql.infra.decorators import graphql_query_type
+
+
+# 1. Define CQRS Query & Handler
+@dataclass(frozen=True)
+class GetItemQuery(Query):
+    item_id: str
+
+
+@query_handler(GetItemQuery)
+class GetItemHandler:
+    def __call__(self, qry: GetItemQuery) -> dict:
+        return {"id": qry.item_id, "name": f"Item {qry.item_id}"}
+
+
+# 2. Define Strawberry GraphQL Type
+@strawberry.type
+class ItemType:
+    id: str
+    name: str
+
+
+@graphql_query_type
+class Query:
+    @strawberry.field
+    def item(self, info: Info[GraphQLContext, None], item_id: str) -> ItemType:
+        res = info.context.query_bus.dispatch(GetItemQuery(item_id=item_id))
+        return ItemType(id=res["id"], name=res["name"])
+
+
+# 3. Bootstrap Runtime with GraphQL
+runtime = bootstrap(packages_to_scan=[__name__])
+schema = runtime.get("graphql_schema")
+
+result = schema.execute_sync(
+    '{ item(itemId: "123") { id name } }',
+    context_value=GraphQLContext(
+        container=runtime.container, query_bus=runtime.get("query_bus")
+    ),
+)
+print(result.data)  # {'item': {'id': '123', 'name': 'Item 123'}}
+```

hexastack_graphql-0.0.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "hexastack-graphql"
+version = "0.0.0"
+description = "Strawberry GraphQL presentation adapter and CQRS integration for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "strawberry-graphql>=0.260.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.141.1",
+    "hexastack-fastapi",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+graphql = "hexastack_graphql.infra.bootstrap:GraphQLBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.uv.sources.hexastack-fastapi]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_graphql"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_graphql"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_graphql.domain"]
+forbidden_modules = [
+    "hexastack_graphql.adapters",
+    "hexastack_graphql.infra",
+]

hexastack_graphql-0.0.0/pyproject.toml.orig

@@ -0,0 +1,53 @@
+[project]
+name = "hexastack-graphql"
+version = "0.0.0"
+description = "Strawberry GraphQL presentation adapter and CQRS integration for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "strawberry-graphql>=0.260.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.141.1",
+    "hexastack-fastapi",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+graphql = "hexastack_graphql.infra.bootstrap:GraphQLBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+hexastack-fastapi = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_graphql"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_graphql"]
+layers = [
+    "adapters",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_graphql.domain"]
+forbidden_modules = [
+    "hexastack_graphql.adapters",
+    "hexastack_graphql.infra",
+]

hexastack_graphql-0.0.0/src/hexastack_graphql/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_graphql import adapters, domain, infra
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+]

hexastack_graphql-0.0.0/src/hexastack_graphql/adapters/fastapi.py

@@ -0,0 +1,122 @@
+import importlib.util
+from typing import Any
+
+import strawberry
+from rodi import Container
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_cqrs.ports.buses import CommandBusPort, QueryBusPort
+from hexastack_graphql.domain.context import GraphQLContext
+
+__all__ = [
+    "create_graphql_router",
+    "mount_graphql_router",
+]
+
+
+def _require_fastapi() -> None:
+    """Guard against missing FastAPI installation.
+
+    Raises:
+        MissingDependencyError: If fastapi is not installed.
+    """
+    if importlib.util.find_spec("fastapi") is None:
+        raise MissingDependencyError(
+            "fastapi is required for FastAPI GraphQL integration. "
+            "Install via 'pip install hexastack-graphql[fastapi]'."
+        )
+
+
+def create_graphql_router(
+    schema: strawberry.Schema,
+    container: Container,
+    *,
+    command_bus: CommandBusPort | None = None,
+    query_bus: QueryBusPort | None = None,
+    graphiql: bool = True,
+) -> Any:
+    """Construct a Strawberry GraphQLRouter for FastAPI.
+
+    Notes/Architectural Intent:
+        Creates a FastAPI APIRouter subclass (GraphQLRouter) that dynamically
+        injects the rodi Container and CQRS message buses into Info.context for
+        every HTTP execution.
+
+    Args:
+        schema: Compiled strawberry.Schema instance.
+        container: rodi DI Container.
+        command_bus: Optional CommandBusPort instance.
+        query_bus: Optional QueryBusPort instance.
+        graphiql: If True, enables the GraphiQL interactive playground.
+
+    Returns:
+        Configured strawberry.fastapi.GraphQLRouter instance.
+
+    Raises:
+        MissingDependencyError: If fastapi is not installed.
+    """
+    _require_fastapi()
+    from starlette.requests import Request
+    from strawberry.fastapi import GraphQLRouter
+
+    async def get_context(request: Request) -> GraphQLContext:
+        # Dynamically resolve buses from container if not passed explicitly
+        c_bus = command_bus
+        if c_bus is None and container is not None:
+            try:
+                c_bus = container.resolve(CommandBusPort)
+            except Exception:  # noqa: BLE001
+                c_bus = None
+
+        q_bus = query_bus
+        if q_bus is None and container is not None:
+            try:
+                q_bus = container.resolve(QueryBusPort)
+            except Exception:  # noqa: BLE001
+                q_bus = None
+
+        ctx = GraphQLContext(
+            container=container,
+            command_bus=c_bus,
+            query_bus=q_bus,
+        )
+        ctx.request = request
+        return ctx
+
+    return GraphQLRouter(
+        schema=schema,
+        context_getter=get_context,
+        graphql_ide="graphiql" if graphiql else None,
+    )
+
+
+def mount_graphql_router(
+    app: Any,
+    schema: strawberry.Schema,
+    container: Container,
+    *,
+    path: str = "/graphql",
+    graphiql: bool = True,
+) -> None:
+    """Mount Strawberry GraphQL router directly onto a FastAPI application instance.
+
+    Args:
+        app: Target FastAPI application instance.
+        schema: Compiled strawberry.Schema.
+        container: rodi DI Container.
+        path: Route prefix for GraphQL endpoints. Defaults to "/graphql".
+        graphiql: If True, enables GraphiQL playground.
+
+    Returns:
+        None.
+
+    Raises:
+        MissingDependencyError: If fastapi is not installed.
+    """
+    _require_fastapi()
+    router = create_graphql_router(
+        schema=schema,
+        container=container,
+        graphiql=graphiql,
+    )
+    app.include_router(router, prefix=path)

hexastack_graphql-0.0.0/src/hexastack_graphql/domain/context.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from strawberry.fastapi.context import BaseContext
+
+
+@dataclass
+class GraphQLContext(BaseContext):
+    """Execution context injected into Strawberry GraphQL resolvers.
+
+    Notes/Architectural Intent:
+        Carries the rodi DI container and CQRS command/query buses into
+        field resolvers, enabling clean dispatching from GraphQL queries
+        and mutations. Inherits from Strawberry's BaseContext for full
+        FastAPI router integration.
+    """
+
+    container: Any | None = None
+    command_bus: Any | None = None
+    query_bus: Any | None = None
+    request: Any | None = None
+    properties: dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = [
+    "GraphQLContext",
+]

hexastack_graphql-0.0.0/src/hexastack_graphql/domain/exceptions.py

@@ -0,0 +1,25 @@
+from hexastack_core.domain.exceptions import HexastackError
+
+
+class GraphQLError(HexastackError):
+    """Base exception for all GraphQL adapter errors.
+
+    Notes/Architectural Intent:
+        Inherits from HexastackError to maintain unified exception hierarchy
+        across core and adapter layers.
+    """
+
+
+class SchemaBuildingError(GraphQLError):
+    """Exception raised when GraphQL schema construction or validation fails.
+
+    Notes/Architectural Intent:
+        Raised when no queries or mutations are registered, or when invalid
+        field definitions conflict during schema compilation.
+    """
+
+
+__all__ = [
+    "GraphQLError",
+    "SchemaBuildingError",
+]