graphql-api 1.6.7__tar.gz → 1.6.8__tar.gz

{graphql_api-1.6.7 → graphql_api-1.6.8}/.github/workflows/pages.yml

@@ -22,7 +22,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      HUGO_VERSION: 0.146.0
+      HUGO_VERSION: 0.160.1
     steps:
       - name: Checkout
         uses: actions/checkout@v4

{graphql_api-1.6.7 → graphql_api-1.6.8}/AGENTS.md

@@ -30,8 +30,9 @@ uv run flake8 graphql_api tests
 
 - **Automatic snake_case to camelCase**: All Python field names, arguments, and dataclass/Pydantic fields are auto-converted to camelCase in GraphQL. Input arguments are converted back to snake_case. Conversion lives in `graphql_api/utils.py` (`to_camel_case()`, `to_snake_case()`)
 - `@field` marks a method as a query; `@field(mutable=True)` makes it a mutation; `AsyncGenerator` return type or `subscription=True` makes it a subscription
+- Plain functions: `@api.query` / `@api.mutation` / `@api.subscription` register a free function as a root-level field — no class required. Composes with class-based roots (registered fns are folded onto the user-provided `query_type` / `mutation_type` / `subscription_type` / `root_type`)
 - Python types auto-map: `str`→String, `int`→Int, `bool`→Boolean, `float`→Float, `UUID`→UUID scalar, `datetime`→DateTime, `Optional[T]`→nullable, `List[T]`→list, dataclasses/Pydantic models→object types, enums→enum types
-- Schema setup: `GraphQLAPI(query_type=Q, mutation_type=M, subscription_type=S)` or legacy `root_type=Root`
+- Schema setup: `GraphQLAPI(query_type=Q, mutation_type=M, subscription_type=S)` or legacy `root_type=Root` (or neither — just `@api.query`/`@api.mutation`/`@api.subscription`)
 
 ## Releasing
 

{graphql_api-1.6.7 → graphql_api-1.6.8}/CLAUDE.md

@@ -30,8 +30,9 @@ uv run flake8 graphql_api tests
 
 - **Automatic snake_case to camelCase**: All Python field names, arguments, and dataclass/Pydantic fields are auto-converted to camelCase in GraphQL. Input arguments are converted back to snake_case. Conversion lives in `graphql_api/utils.py` (`to_camel_case()`, `to_snake_case()`)
 - `@field` marks a method as a query; `@field(mutable=True)` makes it a mutation; `AsyncGenerator` return type or `subscription=True` makes it a subscription
+- Plain functions: `@api.query` / `@api.mutation` / `@api.subscription` register a free function as a root-level field — no class required. Composes with class-based roots (registered fns are folded onto the user-provided `query_type` / `mutation_type` / `subscription_type` / `root_type`)
 - Python types auto-map: `str`→String, `int`→Int, `bool`→Boolean, `float`→Float, `UUID`→UUID scalar, `datetime`→DateTime, `Optional[T]`→nullable, `List[T]`→list, dataclasses/Pydantic models→object types, enums→enum types
-- Schema setup: `GraphQLAPI(query_type=Q, mutation_type=M, subscription_type=S)` or legacy `root_type=Root`
+- Schema setup: `GraphQLAPI(query_type=Q, mutation_type=M, subscription_type=S)` or legacy `root_type=Root` (or neither — just `@api.query`/`@api.mutation`/`@api.subscription`)
 
 ## Releasing
 

{graphql_api-1.6.7 → graphql_api-1.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphql-api
-Version: 1.6.7
+Version: 1.6.8
 Summary: A framework for building Python GraphQL APIs.
 Author-email: Robert Parker <rob@parob.com>
 License: MIT
@@ -57,46 +57,56 @@ pip install graphql-api
 
 ## Quick Start
 
-Create a simple GraphQL API in just a few lines of code.
+For simple APIs, register plain functions directly — no class required:
 
 ```python
 # example.py
 from graphql_api.api import GraphQLAPI
 
-# 1. Initialize the API
 api = GraphQLAPI()
 
-# 2. Define your root type with decorators
-@api.type(is_root_type=True)
-class Query:
-    """
-    The root query for our amazing API.
-    """
-    @api.field
-    def hello(self, name: str = "World") -> str:
-        """
-        A classic greeting.
-        """
-        return f"Hello, {name}!"
+@api.query
+def hello(name: str = "World") -> str:
+    """A classic greeting."""
+    return f"Hello, {name}!"
 
-# 3. Define a query
-graphql_query = """
-    query Greetings {
-        hello(name: "Developer")
-    }
-"""
+@api.mutation
+def set_name(name: str) -> str:
+    return f"Name set to {name}"
 
-# 4. Execute the query
 if __name__ == "__main__":
-    result = api.execute(graphql_query)
+    result = api.execute('query { hello(name: "Developer") }')
     print(result.data)
 ```
 
-Running this script will produce:
-
 ```bash
 $ python example.py
-{'hello': 'Hello, Developer'}
+{'hello': 'Hello, Developer!'}
+```
+
+Use `@api.query`, `@api.mutation`, and `@api.subscription` for root-level
+fields. For nested object types, reach for the class-based form below.
+
+### Class-based form
+
+When you need object types with their own fields (relationships, computed
+properties, nested resolvers), define a root class:
+
+```python
+from graphql_api.api import GraphQLAPI
+
+api = GraphQLAPI()
+
+@api.type(is_root_type=True)
+class Query:
+    """The root query for our amazing API."""
+    @api.field
+    def hello(self, name: str = "World") -> str:
+        return f"Hello, {name}!"
+
+result = api.execute('query { hello(name: "Developer") }')
+print(result.data)
+# {'hello': 'Hello, Developer!'}
 ```
 
 ## Examples

{graphql_api-1.6.7 → graphql_api-1.6.8}/README.md

@@ -32,46 +32,56 @@ pip install graphql-api
 
 ## Quick Start
 
-Create a simple GraphQL API in just a few lines of code.
+For simple APIs, register plain functions directly — no class required:
 
 ```python
 # example.py
 from graphql_api.api import GraphQLAPI
 
-# 1. Initialize the API
 api = GraphQLAPI()
 
-# 2. Define your root type with decorators
-@api.type(is_root_type=True)
-class Query:
-    """
-    The root query for our amazing API.
-    """
-    @api.field
-    def hello(self, name: str = "World") -> str:
-        """
-        A classic greeting.
-        """
-        return f"Hello, {name}!"
+@api.query
+def hello(name: str = "World") -> str:
+    """A classic greeting."""
+    return f"Hello, {name}!"
 
-# 3. Define a query
-graphql_query = """
-    query Greetings {
-        hello(name: "Developer")
-    }
-"""
+@api.mutation
+def set_name(name: str) -> str:
+    return f"Name set to {name}"
 
-# 4. Execute the query
 if __name__ == "__main__":
-    result = api.execute(graphql_query)
+    result = api.execute('query { hello(name: "Developer") }')
     print(result.data)
 ```
 
-Running this script will produce:
-
 ```bash
 $ python example.py
-{'hello': 'Hello, Developer'}
+{'hello': 'Hello, Developer!'}
+```
+
+Use `@api.query`, `@api.mutation`, and `@api.subscription` for root-level
+fields. For nested object types, reach for the class-based form below.
+
+### Class-based form
+
+When you need object types with their own fields (relationships, computed
+properties, nested resolvers), define a root class:
+
+```python
+from graphql_api.api import GraphQLAPI
+
+api = GraphQLAPI()
+
+@api.type(is_root_type=True)
+class Query:
+    """The root query for our amazing API."""
+    @api.field
+    def hello(self, name: str = "World") -> str:
+        return f"Hello, {name}!"
+
+result = api.execute('query { hello(name: "Developer") }')
+print(result.data)
+# {'hello': 'Hello, Developer!'}
 ```
 
 ## Examples

graphql_api-1.6.8/VERSION

@@ -0,0 +1 @@
+1.6.8

{graphql_api-1.6.7 → graphql_api-1.6.8}/docs/content/docs/fundamentals/async-and-subscriptions.md

@@ -101,6 +101,29 @@ Subscriptions can be defined using either of the two schema definition modes des
 
 ### Subscription Examples
 
+**Using Plain Functions (Simplest):**
+
+Register an async generator directly with `@api.subscription`:
+
+```python
+import asyncio
+from typing import AsyncGenerator
+from graphql_api.api import GraphQLAPI
+
+api = GraphQLAPI()
+
+@api.query
+def placeholder() -> str:
+    return "ok"
+
+@api.subscription
+async def count(to: int = 5) -> AsyncGenerator[int, None]:
+    """Counts up to a given number, yielding each number."""
+    for i in range(1, to + 1):
+        await asyncio.sleep(1)
+        yield i
+```
+
 **Using Mode 1 (Single Root Type):**
 
 ```python

{graphql_api-1.6.7 → graphql_api-1.6.8}/docs/content/docs/fundamentals/defining-schemas.md

@@ -82,7 +82,39 @@ Global decorators avoid this issue since they don't require importing an API ins
 
 ## Schema Definition Modes
 
-`graphql-api` offers two distinct approaches for organizing your GraphQL operations (queries, mutations, subscriptions):
+`graphql-api` offers three approaches for organizing your GraphQL operations (queries, mutations, subscriptions). They can be mixed in the same API.
+
+### Mode 0: Plain Functions (Simplest)
+
+Register free functions directly on the API — no class required. Good for small APIs, scripts, and cases where you don't need nested object types at the root.
+
+```python
+from graphql_api.api import GraphQLAPI
+
+api = GraphQLAPI()
+
+@api.query
+def hello(name: str = "World") -> str:
+    return f"Hello, {name}!"
+
+@api.mutation
+def set_counter(value: int) -> int:
+    return value
+
+@api.subscription
+async def ticks(to: int = 3):  # AsyncGenerator[int, None]
+    for i in range(1, to + 1):
+        yield i
+```
+
+Registered functions compose with any of the class-based modes below — they're folded onto whatever root/query/mutation/subscription type you supply, so you can gradually migrate from plain functions to classes (or vice versa) without breaking changes.
+
+**Use when:**
+- Building a small API or script where class boilerplate isn't earning its keep
+- You want the lowest-friction onboarding for teammates new to GraphQL
+- Mixing a handful of root fields onto an existing class-based schema
+
+**Limitations:** plain functions have no `self` — so they can't share instance state. For request-scoped state, declare `context: GraphQLContext` as a parameter (same mechanism used by class-based fields). For nested object types, define them as classes and return instances from your registered function.
 
 ### Mode 1: Single Root Type (Strongly Recommended)
 

{graphql_api-1.6.7 → graphql_api-1.6.8}/docs/content/docs/fundamentals/getting-started.md

@@ -19,9 +19,44 @@ pip install graphql-api
 
 Let's create a simple GraphQL API that returns a classic "Hello, World!" greeting.
 
-### 1. Initialize the API
+There are two ways to define root fields — pick whichever fits the shape of your API:
 
-First, create a new Python file (e.g., `main.py`) and initialize `GraphQLAPI`:
+- **Plain functions** — register a free function as a root query/mutation/subscription. Great for small APIs, scripts, and anything that doesn't need nested object types.
+- **Class-based** — define a root class and decorate its methods. Use this when you have nested object types, shared state, or interrelated resolvers.
+
+You can mix both in the same API. We'll show the plain-function version first, then the class-based version.
+
+### Option A: Plain functions (simplest)
+
+```python
+# main.py
+from graphql_api.api import GraphQLAPI
+
+api = GraphQLAPI()
+
+@api.query
+def hello(name: str = "World") -> str:
+    """A classic greeting. This docstring becomes the field description."""
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    result = api.execute('query { hello(name: "Developer") }')
+    print(result.data)  # {'hello': 'Hello, Developer!'}
+```
+
+Three decorators are available on the API instance:
+
+- `@api.query` — register a query field
+- `@api.mutation` — register a mutation field
+- `@api.subscription` — register a subscription field (function must return `AsyncGenerator[T, None]`)
+
+They accept the same `meta={...}` and `directives=[...]` parameters as `@api.field`. Type hints, defaults, `Optional[T]`, dataclass/Pydantic inputs, and `GraphQLContext` injection all work identically to class-based fields.
+
+### Option B: Class-based
+
+Use a class when you need nested object types, shared state, or multiple interrelated resolvers.
+
+#### 1. Initialize the API
 
 ```python
 # main.py
@@ -30,9 +65,9 @@ from graphql_api.api import GraphQLAPI
 api = GraphQLAPI()
 ```
 
-### 2. Define the Root Query
+#### 2. Define the Root Query
 
-Next, define a class that will serve as your root query object. Use the `@api.type` decorator to mark it as the root type for your schema and the `@api.field` decorator to expose a method as a GraphQL field.
+Define a class that will serve as your root query object. Use the `@api.type` decorator to mark it as the root type for your schema and the `@api.field` decorator to expose a method as a GraphQL field.
 
 ```python
 # main.py
@@ -74,7 +109,7 @@ This generates:
 example(requiredArg: String!, optionalArg: String): String!
 ```
 
-### 3. Execute a Query
+#### 3. Execute a Query
 
 Now you're ready to execute a query against your API.
 

{graphql_api-1.6.7 → graphql_api-1.6.8}/docs/content/docs/fundamentals/mutations.md

@@ -9,7 +9,34 @@ description: >
 
 GraphQL mutations allow clients to modify data on the server. This guide covers how to create mutations and define input types for complex data operations.
 
-## Basic Mutations
+## Plain Functions (Simplest)
+
+The lowest-friction way to define a mutation is a free function decorated with `@api.mutation` — no class required:
+
+```python
+from graphql_api.api import GraphQLAPI
+
+api = GraphQLAPI()
+
+@api.query
+def get_user(user_id: str):
+    return find_user_by_id(user_id)
+
+@api.mutation
+def create_user(name: str, email: str) -> User:
+    """Create a new user account."""
+    user = User(id=generate_id(), name=name, email=email)
+    save_user(user)
+    return user
+
+@api.mutation
+def delete_user(user_id: str) -> bool:
+    return delete_user_by_id(user_id)
+```
+
+Input types, `Optional[T]`, defaults, dataclass/Pydantic inputs, and `GraphQLContext` injection all work exactly as they do for class-based mutations (covered below).
+
+## Basic Mutations (Class-based)
 
 In Mode 1 (Single Root Type), mark mutation fields with `mutable=True`:
 

{graphql_api-1.6.7 → graphql_api-1.6.8}/docs/content/docs/reference/api-reference.md

@@ -191,6 +191,55 @@ async def user_updates(self) -> AsyncGenerator[User, None]:
 ```
 
 
+### `@api.query`, `@api.mutation`, `@api.subscription`
+
+Register a plain (free) function as a root-level GraphQL field. Useful when you don't want to wrap root fields in a class.
+
+```python
+@api.query(
+    meta: Optional[Dict] = None,
+    directives: Optional[List] = None,
+)
+
+@api.mutation(
+    meta: Optional[Dict] = None,
+    directives: Optional[List] = None,
+)
+
+@api.subscription(
+    meta: Optional[Dict] = None,
+    directives: Optional[List] = None,
+)
+```
+
+**Parameters:**
+- `meta`: Optional metadata dictionary, retrievable in middleware (same semantics as `@api.field(meta=...)`).
+- `directives`: Optional list of applied schema directives.
+
+**Behavior:**
+- `@api.query` adds the function to the root `Query` type.
+- `@api.mutation` adds the function to the root `Mutation` type.
+- `@api.subscription` adds the function to the root `Subscription` type. The function must return `AsyncGenerator[T, None]`.
+- Registered functions compose with `query_type=` / `mutation_type=` / `subscription_type=` / `root_type=` — they are folded onto the user-supplied class so you can mix class-based and function-based root fields freely.
+- Type hints, default values, `Optional[T]`, dataclass/Pydantic inputs, enum args, and `context: GraphQLContext` injection all work identically to `@api.field`.
+- Plain functions have no `self`; use a `GraphQLContext` parameter for request-scoped state, and module-level or captured state otherwise.
+
+**Bare and parameterized usage:**
+```python
+@api.query
+def hello(name: str = "World") -> str:
+    return f"Hello, {name}!"
+
+@api.mutation(meta={"audit": True})
+def set_counter(value: int) -> int:
+    return value
+
+@api.subscription
+async def ticks(to: int = 3) -> AsyncGenerator[int, None]:
+    for i in range(1, to + 1):
+        yield i
+```
+
 ### `@api.enum`
 
 Mark an enum class as a GraphQL enum.

{graphql_api-1.6.7 → graphql_api-1.6.8}/graphql_api/api.py

@@ -266,6 +266,9 @@ class GraphQLAPI(GraphQLBaseExecutor):
         self.enum_suffix = enum_suffix
         self.interface_suffix = interface_suffix
         self.input_suffix = input_suffix
+        self._registered_queries: List[Callable] = []
+        self._registered_mutations: List[Callable] = []
+        self._registered_subscriptions: List[Callable] = []
 
     # --------------------------------------------------------------------------
     # DECORATORS
@@ -330,9 +333,207 @@ class GraphQLAPI(GraphQLBaseExecutor):
         self.root_type = root_type
         return root_type
 
+    def _register_plain(
+        self,
+        arg,
+        graphql_type: str,
+        meta: Optional[Dict],
+        directives: Optional[List],
+        target_list: List[Callable],
+    ):
+        """
+        Shared implementation for api.query / api.mutation / api.subscription.
+
+        Supports both bare `@api.query` and parameterized `@api.query(meta={...})`
+        usage. In the bare form, `arg` is the function being decorated. In the
+        parameterized form, `arg` is None (only keyword args were given) and we
+        return a decorator.
+        """
+
+        def tag_and_register(func):
+            tagged = tag_value(
+                value=func,
+                graphql_type=graphql_type,
+                schema=self,
+                meta=meta,
+                directives=directives,
+            )
+            if tagged not in target_list:
+                target_list.append(tagged)
+            self._cached_schema = None
+            return tagged
+
+        if arg is not None and callable(arg):
+            return tag_and_register(arg)
+        return tag_and_register
+
+    def query(
+        self=None,
+        func: Optional[Callable] = None,
+        meta: Optional[Dict] = None,
+        directives: Optional[List] = None,
+    ):
+        """
+        Register a plain function as a root-level GraphQL query field.
+
+        Usage:
+            @api.query
+            def hello(name: str) -> str: ...
+
+            @api.query(meta={"note": "..."})
+            def goodbye(name: str) -> str: ...
+        """
+        return self._register_plain(
+            arg=func,
+            graphql_type="field",
+            meta=meta,
+            directives=directives,
+            target_list=self._registered_queries,
+        )
+
+    def mutation(
+        self=None,
+        func: Optional[Callable] = None,
+        meta: Optional[Dict] = None,
+        directives: Optional[List] = None,
+    ):
+        """
+        Register a plain function as a root-level GraphQL mutation field.
+        """
+        return self._register_plain(
+            arg=func,
+            graphql_type="mutable_field",
+            meta=meta,
+            directives=directives,
+            target_list=self._registered_mutations,
+        )
+
+    def subscription(
+        self=None,
+        func: Optional[Callable] = None,
+        meta: Optional[Dict] = None,
+        directives: Optional[List] = None,
+    ):
+        """
+        Register a plain function as a root-level GraphQL subscription field.
+        The function should return `AsyncGenerator[T, None]`.
+        """
+        return self._register_plain(
+            arg=func,
+            graphql_type="subscription_field",
+            meta=meta,
+            directives=directives,
+            target_list=self._registered_subscriptions,
+        )
+
     # --------------------------------------------------------------------------
     # SCHEMA BUILDING & EXECUTION
     # --------------------------------------------------------------------------
+    def _fold_registered_functions(self):
+        """
+        Synthesize root classes from functions registered via
+        @api.query / @api.mutation / @api.subscription, or subclass existing
+        user-supplied root types to include them.
+
+        Each registered function is attached to the synthesized class as a
+        method wrapper that accepts (and discards) the leading `self` arg,
+        forwarding keyword args to the real function. This matches the
+        resolver's call convention at graphql_api/mapper.py:485-517 — which
+        ends up calling `function_type(_self, **_args)` for root-level fields
+        where `_self` is typically None — so the wrapper absorbs `_self` and
+        the free function sees only its declared keyword args.
+
+        The wrapper preserves `__annotations__`, `__wrapped__`, and the
+        `_graphql` / `_schemas` tags so `typing.get_type_hints` and
+        `inspect.signature` (which follows `__wrapped__`) return the original
+        function's hints and defaults.
+        """
+        if not (
+            self._registered_queries
+            or self._registered_mutations
+            or self._registered_subscriptions
+        ):
+            return
+
+        def make_method(fn: Callable) -> Callable:
+            def _method(_self, **kwargs):
+                return fn(**kwargs)
+            _method.__name__ = fn.__name__
+            _method.__qualname__ = getattr(fn, "__qualname__", fn.__name__)
+            _method.__doc__ = fn.__doc__
+            _method.__module__ = getattr(fn, "__module__", None)
+            _method.__annotations__ = dict(getattr(fn, "__annotations__", {}))
+            _method.__wrapped__ = fn  # inspect.signature follows this
+            # Preserve the @field-style tags attached by tag_value()
+            for attr in ("_graphql", "_schemas", "_defined_on",
+                         "_applied_directives"):
+                if hasattr(fn, attr):
+                    setattr(_method, attr, getattr(fn, attr))
+            return _method
+
+        def unwrap(base: Optional[Type]) -> Optional[Type]:
+            # If we previously synthesized on top of this slot, peel that
+            # layer off so re-builds don't stack subclasses.
+            while base is not None and getattr(
+                base, "__graphql_api_synthesized__", False
+            ):
+                parents = [b for b in base.__bases__ if b is not object]
+                base = parents[0] if parents else None
+            return base
+
+        def synthesize(name: str, base: Optional[Type], fns: List[Callable]):
+            if not fns:
+                return base
+            attrs: Dict[str, Any] = {fn.__name__: make_method(fn) for fn in fns}
+            attrs["__graphql_api_synthesized__"] = True
+            bases: Tuple[type, ...] = (base,) if base else ()
+            return type(name, bases, attrs)
+
+        # root_type path: legacy single-class mode. Fold every registered
+        # function (queries + mutations) onto a subclass of root_type.
+        if self.root_type is not None:
+            if self._registered_subscriptions:
+                raise GraphQLError(
+                    "api.subscription is not supported together with "
+                    "root_type=. Use query_type/mutation_type/subscription_type "
+                    "instead."
+                )
+            combined = [
+                *self._registered_queries,
+                *self._registered_mutations,
+            ]
+            base_root = unwrap(self.root_type)
+            if base_root is None:
+                return
+            self.root_type = synthesize(
+                base_root.__name__, base_root, combined
+            )
+            return
+
+        # Explicit mode: fold each list onto its matching *_type, always
+        # starting from the unwrapped original so re-builds are idempotent.
+        base_query = unwrap(self.query_type)
+        base_mutation = unwrap(self.mutation_type)
+        base_subscription = unwrap(self.subscription_type)
+
+        self.query_type = synthesize(
+            "Query" if base_query is None else base_query.__name__,
+            base_query,
+            self._registered_queries,
+        )
+        self.mutation_type = synthesize(
+            "Mutation" if base_mutation is None else base_mutation.__name__,
+            base_mutation,
+            self._registered_mutations,
+        )
+        self.subscription_type = synthesize(
+            "Subscription"
+            if base_subscription is None
+            else base_subscription.__name__,
+            base_subscription,
+            self._registered_subscriptions,
+        )
+
     def schema(self, ignore_cache: bool = False) -> GraphQLSchema:
         return self.build(ignore_cache)[0]
 
@@ -345,6 +546,13 @@ class GraphQLAPI(GraphQLBaseExecutor):
         if not ignore_cache and self._cached_schema:
             return self._cached_schema
 
+        # Fold any plain functions registered via @api.query / @api.mutation /
+        # @api.subscription into query_type / mutation_type / subscription_type
+        # (or subclass them onto root_type). The synthesized classes attach each
+        # registered function as a staticmethod so the resolver in
+        # graphql_api/mapper.py treats them as free functions (no self injected).
+        self._fold_registered_functions()
+
         # Federation support
         if self.federation:
             from graphql_api.federation.federation import add_federation_types