graphql-api 1.4.18__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.20/.github/workflows/python-package.yml

@@ -0,0 +1,78 @@
+name: Python Package CI/CD
+
+on:
+  push:
+    branches:
+      - main # Or your default branch
+    tags:
+      - '*.*.*' # For publishing to PyPI
+  pull_request:
+    branches:
+      - main # Or your default branch
+
+jobs:
+  build_and_test:
+    name: Build and Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"] # graphql-api requires Python 3.11+
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install UV
+      uses: astral-sh/setup-uv@v3
+
+    - name: Install dependencies
+      run: uv sync --dev
+
+    - name: Lint with Flake8
+      run: uv run flake8 graphql_api tests
+
+    - name: Test with Pytest
+      run: uv run pytest
+
+  publish:
+    name: Publish to PyPI
+    needs: build_and_test # Ensure tests pass before publishing
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    permissions:
+      id-token: write
+    
+    steps:
+    - name: Validate tag format (e.g., 1.0.0)
+      run: |
+        TAG_NAME="${{ github.ref_name }}"
+        if ! [[ "$TAG_NAME" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+          echo "Error: Tag '$TAG_NAME' is not in the required X.Y.Z numeric format (e.g., 1.0.0)."
+          exit 1
+        fi
+        echo "Tag '$TAG_NAME' is valid."
+      shell: bash
+
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12' # Use compatible Python version
+
+    - name: Install UV
+      uses: astral-sh/setup-uv@v3
+
+    - name: Update VERSION file
+      run: echo "${{ github.ref_name }}" > VERSION
+      shell: bash
+
+    - name: Build and publish package to PyPI
+      run: uv build && uv publish

graphql_api-1.4.20/.gitignore

@@ -0,0 +1,23 @@
+.idea
+.DS_Store
+.coverage
+.pytest_cache
+
+# Virtual environments
+.venv/
+env/
+venv/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Testing
+tests/logs/
+tests/htmlcov/
+htmlcov/
+
+# Python
+*.pyc
+__pycache__/

graphql_api-1.4.20/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

{graphql_api-1.4.18/graphql_api.egg-info → graphql_api-1.4.20}/PKG-INFO

@@ -1,44 +1,27 @@
 Metadata-Version: 2.4
 Name: graphql_api
-Version: 1.4.18
+Version: 1.4.20
 Summary: A framework for building Python GraphQL APIs.
-Home-page: https://gitlab.com/parob/graphql-api
-Download-URL: https://gitlab.com/parob/graphql/-/archive/v1.4.18/graphql_api-v1.4.18.tar.gz
-Author: Robert Parker
-Author-email: rob@parob.com
+Author-email: Robert Parker <rob@parob.com>
 License: MIT
+Project-URL: Homepage, https://gitlab.com/parob/graphql-api
+Project-URL: Repository, https://gitlab.com/parob/graphql-api
 Keywords: GraphQL,GraphQL-API,GraphQLAPI,Server
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: graphql-core~=3.1
-Requires-Dist: requests~=2.24
-Requires-Dist: typing-inspect~=0.6
-Requires-Dist: aiohttp~=3.8
-Requires-Dist: docstring-parser~=0.15
-Requires-Dist: pydantic~=2.0
-Provides-Extra: dev
-Requires-Dist: pytest~=5.4; extra == "dev"
-Requires-Dist: pytest-cov~=2.10; extra == "dev"
-Requires-Dist: coverage~=5.2; extra == "dev"
-Requires-Dist: faker~=4.1; extra == "dev"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: download-url
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
+Requires-Dist: graphql-core
+Requires-Dist: requests
+Requires-Dist: typing-inspect
+Requires-Dist: aiohttp
+Requires-Dist: docstring-parser
+Requires-Dist: pydantic
 Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: summary
 
 # GraphQL API for Python
 
@@ -54,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.
@@ -126,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]:
@@ -134,7 +119,7 @@ class BookAPI:
             Book(title="1984", author="George Orwell"),
         ]
 
-api = GraphQLAPI(root_type=BookAPI)
+api = GraphQLAPI()
 
 graphql_query = """
     query {
@@ -157,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.
@@ -184,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:
@@ -198,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.18 → 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