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

{graphql_api-1.6.7 → graphql_api-1.6.9}/.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.9}/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.9}/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.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphql-api
-Version: 1.6.7
+Version: 1.6.9
 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.9}/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.9/VERSION

@@ -0,0 +1 @@
+1.6.9

{graphql_api-1.6.7 → graphql_api-1.6.9}/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.9}/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.9}/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.9}/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.9}/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.