graphql-api 1.4.19__tar.gz → 1.4.20__tar.gz

graphql_api-1.4.20/.github/workflows/pages.yml

@@ -0,0 +1,77 @@
+name: Deploy Hugo site to GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+    paths: [ 'docs/**' ]
+  pull_request:
+    branches: [ main ]
+    paths: [ 'docs/**' ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      HUGO_VERSION: 0.146.0
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0
+      - name: Install Hugo CLI
+        run: |
+          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
+          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
+      - name: Install Dart Sass
+        run: sudo snap install dart-sass
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+        with:
+          enablement: true
+      - name: Install Node.js dependencies
+        working-directory: ./docs
+        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
+      - name: Setup Hugo Book theme
+        working-directory: ./docs
+        run: |
+          if [ ! -d "themes/hugo-book" ]; then
+            git clone --depth 1 https://github.com/alex-shpak/hugo-book.git themes/hugo-book
+          fi
+      - name: Build with Hugo
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        working-directory: ./docs
+        run: |
+          hugo \
+            --gc \
+            --minify \
+            --baseURL "${{ steps.pages.outputs.base_url }}/"          
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/public
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{graphql_api-1.4.19 → graphql_api-1.4.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphql_api
-Version: 1.4.19
+Version: 1.4.20
 Summary: A framework for building Python GraphQL APIs.
 Author-email: Robert Parker <rob@parob.com>
 License: MIT
@@ -37,6 +37,7 @@ A powerful and intuitive Python library for building GraphQL APIs, designed with
 
 - **Decorator-Based Schema:** Define your GraphQL schema declaratively using simple and intuitive decorators.
 - **Type Hinting:** Automatically converts Python type hints into GraphQL types.
+- **Implicit Type Inference:** Automatically maps Pydantic models, dataclasses, and classes with fields - no explicit decorators needed.
 - **Pydantic & Dataclass Support:** Seamlessly use Pydantic and Dataclass models as GraphQL types.
 - **Asynchronous Execution:** Full support for `async` and `await` for high-performance, non-blocking resolvers.
 - **Apollo Federation:** Built-in support for creating federated services.
@@ -109,6 +110,7 @@ class Book(BaseModel):
     title: str
     author: str
 
+@api.type(is_root_type=True)
 class BookAPI:
     @api.field
     def get_books(self) -> List[Book]:
@@ -117,7 +119,7 @@ class BookAPI:
             Book(title="1984", author="George Orwell"),
         ]
 
-api = GraphQLAPI(root_type=BookAPI)
+api = GraphQLAPI()
 
 graphql_query = """
     query {
@@ -140,13 +142,14 @@ Define async resolvers for non-blocking I/O operations.
 import asyncio
 from graphql_api.api import GraphQLAPI
 
+@api.type(is_root_type=True)
 class AsyncAPI:
     @api.field
     async def fetch_data(self) -> str:
         await asyncio.sleep(1)
         return "Data fetched successfully!"
 
-api = GraphQLAPI(root_type=AsyncAPI)
+api = GraphQLAPI()
 
 # To execute async queries, you'll need an async executor
 # or to run it within an async context.
@@ -167,11 +170,11 @@ if __name__ == "__main__":
 
 ### Mutations with Dataclasses
 
-Use dataclasses to define the structure of your mutation inputs.
+Use dataclasses to define the structure of your data, and mark fields as mutable to automatically separate them into the GraphQL Mutation type.
 
 ```python
 from dataclasses import dataclass
-from graphql_api.api import GraphQLAPI, field
+from graphql_api.api import GraphQLAPI
 
 @dataclass
 class User:
@@ -181,22 +184,66 @@ class User:
 # A simple in-memory database
 db = {1: User(id=1, name="Alice")}
 
+api = GraphQLAPI()
+
+@api.type(is_root_type=True)
 class Root:
-    @field
+    @api.field
     def get_user(self, user_id: int) -> User:
         return db.get(user_id)
 
-class Mutations:
-    @field
+    @api.field(mutable=True)
     def add_user(self, user_id: int, name: str) -> User:
         new_user = User(id=user_id, name=name)
         db[user_id] = new_user
         return new_user
+```
+
+GraphQL automatically separates queries and mutations - you don't need separate classes. Fields marked with `mutable=True` are placed in the Mutation type, while regular fields go in the Query type. Fields with `AsyncGenerator` return types are automatically detected as subscriptions. This automatic mapping means you can define all your operations in a single class and let `graphql-api` handle the schema organization for you.
+
+## Two Approaches for Complex Schemas
+
+`graphql-api` supports two approaches for organizing your GraphQL schema:
+
+### Single Root Type (Recommended)
+```python
+@api.type(is_root_type=True)
+class Root:
+    @api.field
+    def query_field(self) -> str: ...
+    
+    @api.field(mutable=True) 
+    def mutation_field(self) -> str: ...
+    
+    @api.field
+    async def subscription_field(self) -> AsyncGenerator[str, None]: ...
+
+api = GraphQLAPI(root_type=Root)
+```
+
+### Explicit Types
+```python
+@api.type
+class Query:
+    @api.field
+    def query_field(self) -> str: ...
+
+@api.type  
+class Mutation:
+    @api.field
+    def mutation_field(self) -> str: ...
+
+@api.type
+class Subscription:
+    @api.field
+    async def subscription_field(self) -> AsyncGenerator[str, None]: ...
 
-# The GraphQLAPI constructor will need to be updated to support mutations separately
-# api = GraphQLAPI(root_type=Root, mutation_type=Mutations)
+api = GraphQLAPI(
+    query_type=Query,
+    mutation_type=Mutation, 
+    subscription_type=Subscription
+)
 ```
-*Note: The mutation API is illustrative. The library's `GraphQLAPI` constructor may need to be extended to support mutations as shown.*
 
 ## Running Tests
 

{graphql_api-1.4.19 → graphql_api-1.4.20}/README.md

@@ -12,6 +12,7 @@ A powerful and intuitive Python library for building GraphQL APIs, designed with
 
 - **Decorator-Based Schema:** Define your GraphQL schema declaratively using simple and intuitive decorators.
 - **Type Hinting:** Automatically converts Python type hints into GraphQL types.
+- **Implicit Type Inference:** Automatically maps Pydantic models, dataclasses, and classes with fields - no explicit decorators needed.
 - **Pydantic & Dataclass Support:** Seamlessly use Pydantic and Dataclass models as GraphQL types.
 - **Asynchronous Execution:** Full support for `async` and `await` for high-performance, non-blocking resolvers.
 - **Apollo Federation:** Built-in support for creating federated services.
@@ -84,6 +85,7 @@ class Book(BaseModel):
     title: str
     author: str
 
+@api.type(is_root_type=True)
 class BookAPI:
     @api.field
     def get_books(self) -> List[Book]:
@@ -92,7 +94,7 @@ class BookAPI:
             Book(title="1984", author="George Orwell"),
         ]
 
-api = GraphQLAPI(root_type=BookAPI)
+api = GraphQLAPI()
 
 graphql_query = """
     query {
@@ -115,13 +117,14 @@ Define async resolvers for non-blocking I/O operations.
 import asyncio
 from graphql_api.api import GraphQLAPI
 
+@api.type(is_root_type=True)
 class AsyncAPI:
     @api.field
     async def fetch_data(self) -> str:
         await asyncio.sleep(1)
         return "Data fetched successfully!"
 
-api = GraphQLAPI(root_type=AsyncAPI)
+api = GraphQLAPI()
 
 # To execute async queries, you'll need an async executor
 # or to run it within an async context.
@@ -142,11 +145,11 @@ if __name__ == "__main__":
 
 ### Mutations with Dataclasses
 
-Use dataclasses to define the structure of your mutation inputs.
+Use dataclasses to define the structure of your data, and mark fields as mutable to automatically separate them into the GraphQL Mutation type.
 
 ```python
 from dataclasses import dataclass
-from graphql_api.api import GraphQLAPI, field
+from graphql_api.api import GraphQLAPI
 
 @dataclass
 class User:
@@ -156,22 +159,66 @@ class User:
 # A simple in-memory database
 db = {1: User(id=1, name="Alice")}
 
+api = GraphQLAPI()
+
+@api.type(is_root_type=True)
 class Root:
-    @field
+    @api.field
     def get_user(self, user_id: int) -> User:
         return db.get(user_id)
 
-class Mutations:
-    @field
+    @api.field(mutable=True)
     def add_user(self, user_id: int, name: str) -> User:
         new_user = User(id=user_id, name=name)
         db[user_id] = new_user
         return new_user
+```
+
+GraphQL automatically separates queries and mutations - you don't need separate classes. Fields marked with `mutable=True` are placed in the Mutation type, while regular fields go in the Query type. Fields with `AsyncGenerator` return types are automatically detected as subscriptions. This automatic mapping means you can define all your operations in a single class and let `graphql-api` handle the schema organization for you.
+
+## Two Approaches for Complex Schemas
+
+`graphql-api` supports two approaches for organizing your GraphQL schema:
+
+### Single Root Type (Recommended)
+```python
+@api.type(is_root_type=True)
+class Root:
+    @api.field
+    def query_field(self) -> str: ...
+    
+    @api.field(mutable=True) 
+    def mutation_field(self) -> str: ...
+    
+    @api.field
+    async def subscription_field(self) -> AsyncGenerator[str, None]: ...
+
+api = GraphQLAPI(root_type=Root)
+```
+
+### Explicit Types
+```python
+@api.type
+class Query:
+    @api.field
+    def query_field(self) -> str: ...
+
+@api.type  
+class Mutation:
+    @api.field
+    def mutation_field(self) -> str: ...
+
+@api.type
+class Subscription:
+    @api.field
+    async def subscription_field(self) -> AsyncGenerator[str, None]: ...
 
-# The GraphQLAPI constructor will need to be updated to support mutations separately
-# api = GraphQLAPI(root_type=Root, mutation_type=Mutations)
+api = GraphQLAPI(
+    query_type=Query,
+    mutation_type=Mutation, 
+    subscription_type=Subscription
+)
 ```
-*Note: The mutation API is illustrative. The library's `GraphQLAPI` constructor may need to be extended to support mutations as shown.*
 
 ## Running Tests
 

graphql_api-1.4.20/VERSION

@@ -0,0 +1 @@
+1.4.20

graphql_api-1.4.20/docs/README.md

@@ -0,0 +1,81 @@
+# GraphQL API Documentation
+
+This directory contains the documentation for the GraphQL API library, built with Jekyll and deployed to GitHub Pages.
+
+## Local Development
+
+### Prerequisites
+
+- Ruby 2.7 or newer
+- Bundler gem
+
+### Setup
+
+1. Install dependencies:
+   ```bash
+   cd docs
+   bundle install
+   ```
+
+2. Serve the site locally:
+   ```bash
+   bundle exec jekyll serve
+   ```
+
+3. Open http://localhost:4000 in your browser
+
+### Project Structure
+
+```
+docs/
+├── _config.yml          # Jekyll configuration
+├── _layouts/            # Page layouts
+│   └── default.html     # Main layout template
+├── assets/              # CSS, JS, and other assets
+│   └── css/
+│       └── style.scss   # Main stylesheet
+├── index.md             # Homepage
+├── getting-started.md   # Getting started guide
+├── examples.md          # Examples and tutorials
+├── api-reference.md     # Complete API reference
+├── contributing.md      # Contributing guidelines
+├── Gemfile              # Ruby dependencies
+└── README.md           # This file
+```
+
+## Adding Content
+
+### New Pages
+
+1. Create a new Markdown file in the docs directory
+2. Add front matter at the top:
+   ```yaml
+   ---
+   layout: default
+   title: "Page Title"
+   description: "Page description"
+   ---
+   ```
+3. Add the page to navigation in `_config.yml` if needed
+
+### Updating Existing Content
+
+Simply edit the corresponding Markdown files. The site will rebuild automatically when changes are pushed to the main branch.
+
+## Deployment
+
+The documentation is automatically deployed to GitHub Pages via GitHub Actions when changes are pushed to the main branch. The workflow is defined in `.github/workflows/pages.yml`.
+
+## Customization
+
+### Styling
+
+The main stylesheet is in `assets/css/style.scss`. It imports the base theme and adds custom styling for the documentation.
+
+### Layout
+
+The main layout template is in `_layouts/default.html`. It includes the header, navigation, content area, and footer.
+
+### Configuration
+
+Site configuration is in `_config.yml`. This includes site metadata, navigation, and Jekyll settings.

graphql_api-1.4.20/docs/content/_index.md

@@ -0,0 +1,71 @@
+---
+title: "GraphQL API for Python"
+type: docs
+---
+
+> **A powerful and intuitive Python library for building GraphQL APIs with a code-first, decorator-based approach.**
+
+# GraphQL API for Python
+
+[![PyPI version](https://badge.fury.io/py/graphql-api.svg)](https://badge.fury.io/py/graphql-api)
+[![Python versions](https://img.shields.io/pypi/pyversions/graphql-api.svg)](https://pypi.org/project/graphql-api/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why GraphQL API?
+
+`graphql-api` simplifies schema definition by leveraging Python's type hints, dataclasses, and Pydantic models, allowing you to build robust and maintainable GraphQL services with minimal boilerplate.
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| 🎯 **Code-First Approach** | Define your GraphQL schema using Python decorators and type hints. No SDL required. |
+| ⚡ **Type Safety** | Automatic type conversion from Python types to GraphQL types with full type checking support. |
+| 🔄 **Async Support** | Built-in support for async/await patterns and real-time subscriptions. |
+| 🧩 **Pydantic Integration** | Seamlessly use Pydantic models and dataclasses as GraphQL types. |
+| 🌐 **Federation Ready** | Built-in Apollo Federation support for microservice architectures. |
+| 🎛️ **Flexible Schema** | Choose between unified root types or explicit query/mutation/subscription separation. |
+
+## Quick Start
+
+Get up and running in minutes:
+
+```bash
+pip install graphql-api
+```
+
+```python
+from graphql_api.api import GraphQLAPI
+
+# Initialize the API
+api = GraphQLAPI()
+
+# Define your schema with decorators
+@api.type(is_root_type=True)
+class Query:
+    @api.field
+    def hello(self, name: str = "World") -> str:
+        return f"Hello, {name}!"
+
+# Execute queries
+result = api.execute('{ hello(name: "Developer") }')
+print(result.data)  # {'hello': 'Hello, Developer!'}
+```
+
+## Key Features
+
+- **Decorator-Based Schema:** Define your GraphQL schema declaratively using simple and intuitive decorators
+- **Type Hinting:** Automatically converts Python type hints into GraphQL types
+- **Implicit Type Inference:** Automatically maps Pydantic models, dataclasses, and classes with fields
+- **Pydantic & Dataclass Support:** Seamlessly use Pydantic and Dataclass models as GraphQL types
+- **Asynchronous Execution:** Full support for `async` and `await` for high-performance, non-blocking resolvers
+- **Apollo Federation:** Built-in support for creating federated services
+- **Subscriptions:** Implement real-time functionality with GraphQL subscriptions
+- **Middleware:** Add custom logic to your resolvers with a flexible middleware system
+- **Relay Support:** Includes helpers for building Relay-compliant schemas
+
+## What's Next?
+
+- 📚 **[Getting Started](docs/getting-started/)** - Learn the basics with our comprehensive guide
+- 💡 **[Examples](docs/examples/)** - Explore practical examples and tutorials for real-world scenarios  
+- 📖 **[API Reference](docs/api-reference/)** - Check out the complete API documentation

graphql_api-1.4.20/docs/content/docs/_index.md

@@ -0,0 +1,38 @@
+---
+title: "Documentation"
+weight: 1
+bookCollapseSection: false
+bookFlatSection: true
+---
+
+> **Complete documentation for GraphQL API, from basic concepts to advanced features.**
+
+Welcome to the GraphQL API documentation! This section contains everything you need to know to build powerful GraphQL APIs with Python.
+
+## Getting Started
+
+New to GraphQL API? Start here:
+
+- **[Getting Started](getting-started/)** - Installation and your first API
+
+## Guides
+
+Step-by-step guides for common tasks:
+
+- **[Examples & Tutorials](examples/)** - Practical examples and tutorials
+- **[Schema Definition](defining-schemas/)** - How to define types and fields
+- **[Pydantic & Dataclasses](pydantic-and-dataclasses/)** - Working with data models
+- **[Async & Subscriptions](async-and-subscriptions/)** - Real-time functionality
+
+## Advanced Topics
+
+For experienced users:
+
+- **[Apollo Federation](federation/)** - Building distributed graphs
+- **[Advanced Features](advanced/)** - Middleware, directives, and more
+
+## Reference
+
+Complete API documentation:
+
+- **[API Reference](api-reference/)** - Classes, methods, and functions

{graphql_api-1.4.19/docs_md → graphql_api-1.4.20/docs/content/docs}/advanced.md

@@ -1,3 +1,11 @@
+---
+title: "Advanced Topics"
+linkTitle: "Advanced"
+weight: 7
+description: >
+  Explore advanced features like middleware, directives, and Relay support
+---
+
 # Advanced Topics
 
 This section covers some of the more advanced features of `graphql-api`, including middleware, error handling, resolver context, directives, and Relay support.
@@ -55,12 +63,14 @@ class UserNotFoundError(GraphQLError):
         )
 
 # In a resolver, you can raise this exception
-@api.field
-def get_user_by_id(self, user_id: int) -> User:
-    user = find_user_in_db(user_id)
-    if not user:
-        raise UserNotFoundError(user_id)
-    return user
+@api.type(is_root_type=True)
+class Query:
+    @api.field
+    def get_user_by_id(self, user_id: int) -> User:
+        user = find_user_in_db(user_id)
+        if not user:
+            raise UserNotFoundError(user_id)
+        return user
 ```
 
 When this resolver is executed with an invalid ID, the client will receive a structured error in the response:
@@ -109,15 +119,17 @@ result = api.execute(
 The context is available via the `info` argument (which is of type `GraphQLResolveInfo`) that is passed to every resolver.
 
 ```python
-@api.field
-def get_my_profile(self, info) -> User:
-    # Access the context from the `info` object.
-    current_user = info.context.get("current_user")
+@api.type(is_root_type=True)
+class Query:
+    @api.field
+    def get_my_profile(self, info) -> User:
+        # Access the context from the `info` object.
+        current_user = info.context.get("current_user")
 
-    if not current_user:
-        raise PermissionError("You must be logged in to view your profile.")
+        if not current_user:
+            raise PermissionError("You must be logged in to view your profile.")
 
-    return current_user
+        return current_user
 ```
 
 Using the context is the recommended way to provide resolvers with request-scoped data, keeping them decoupled from the transport layer (e.g., HTTP).