| Name | graphql-api JSON |
| Version |
1.5.3
JSON |
| download |
| home_page | None |
| Summary | A framework for building Python GraphQL APIs. |
| upload_time | 2025-11-05 10:37:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.11 |
| license | MIT |
| keywords |
graphql
graphql-api
graphqlapi
server
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# GraphQL-API for Python
[](https://badge.fury.io/py/graphql-api)
[](https://pypi.org/project/graphql-api/)
[](https://opensource.org/licenses/MIT)
[](https://gitlab.com/parob/graphql-api/commits/master)
[](https://gitlab.com/parob/graphql-api/commits/master)
**[📚 Documentation](https://graphql-api.parob.com/)** | **[📦 PyPI](https://pypi.org/project/graphql-api/)** | **[🔧 GitHub](https://github.com/parob/graphql-api)**
---
A powerful and intuitive Python library for building GraphQL APIs, designed with a code-first, decorator-based approach.
`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
- **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.
- **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.
## Installation
```bash
pip install graphql-api
```
## Quick Start
Create a simple GraphQL API in just a few lines of code.
```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}!"
# 3. Define a query
graphql_query = """
query Greetings {
hello(name: "Developer")
}
"""
# 4. Execute the query
if __name__ == "__main__":
result = api.execute(graphql_query)
print(result.data)
```
Running this script will produce:
```bash
$ python example.py
{'hello': 'Hello, Developer'}
```
## Examples
### Using Pydantic Models
Leverage Pydantic for data validation and structure. `graphql-api` will automatically convert your models into GraphQL types.
```python
from pydantic import BaseModel
from typing import List
from graphql_api.api import GraphQLAPI
class Book(BaseModel):
title: str
author: str
@api.type(is_root_type=True)
class BookAPI:
@api.field
def get_books(self) -> List[Book]:
return [
Book(title="The Hitchhiker's Guide to the Galaxy", author="Douglas Adams"),
Book(title="1984", author="George Orwell"),
]
api = GraphQLAPI()
graphql_query = """
query {
getBooks {
title
author
}
}
"""
result = api.execute(graphql_query)
# result.data will contain the list of books
```
### Asynchronous Resolvers
Define async resolvers for non-blocking I/O operations.
```python
import asyncio
from graphql_api.api import GraphQLAPI
api = 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!"
# To execute async queries, you'll need an async executor
# or to run it within an async context.
async def main():
result = await api.execute("""
query {
fetchData
}
""")
print(result.data)
if __name__ == "__main__":
asyncio.run(main())
```
### Mutations with Dataclasses
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
@dataclass
class User:
id: int
name: str
# A simple in-memory database
db = {1: User(id=1, name="Alice")}
api = GraphQLAPI()
@api.type(is_root_type=True)
class Root:
@api.field
def get_user(self, user_id: int) -> User:
return db.get(user_id)
@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.
## Related Projects
- **[graphql-http](https://graphql-http.parob.com/)** - Serve your API over HTTP with authentication and GraphiQL
- **[graphql-db](https://graphql-db.parob.com/)** - SQLAlchemy integration for database-backed APIs
- **[graphql-mcp](https://graphql-mcp.parob.com/)** - Expose your API as MCP tools for AI agents
See the [documentation](https://graphql-api.parob.com/) for advanced schema patterns, federation, remote GraphQL, and more.
## Documentation
**Visit the [official documentation](https://graphql-api.parob.com/)** for comprehensive guides, tutorials, and API reference.
### Key Topics
- **[Getting Started](https://graphql-api.parob.com/docs/fundamentals/getting-started/)** - Quick introduction and basic usage
- **[Defining Schemas](https://graphql-api.parob.com/docs/fundamentals/defining-schemas/)** - Learn schema definition patterns
- **[Field Types](https://graphql-api.parob.com/docs/fundamentals/field-types/)** - Understanding GraphQL type system
- **[Mutations](https://graphql-api.parob.com/docs/fundamentals/mutations/)** - Implementing data modifications
- **[Remote GraphQL](https://graphql-api.parob.com/docs/distributed-systems/remote-graphql/)** - Connect to remote APIs
- **[Federation](https://graphql-api.parob.com/docs/distributed-systems/federation/)** - Apollo Federation support
- **[API Reference](https://graphql-api.parob.com/docs/reference/api-reference/)** - Complete API documentation
## Running Tests
To contribute or run the test suite locally:
```bash
# Install dependencies
pip install pipenv
pipenv install --dev
# Run tests
pipenv run pytest
```
Raw data
{
"_id": null,
"home_page": null,
"name": "graphql-api",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "GraphQL, GraphQL-API, GraphQLAPI, Server",
"author": null,
"author_email": "Robert Parker <rob@parob.com>",
"download_url": "https://files.pythonhosted.org/packages/71/97/acce84debe22e0dbcd698b479c51dc3c73913e69b4b401b25846d63006ea/graphql_api-1.5.3.tar.gz",
"platform": null,
"description": "# GraphQL-API for Python\n\n[](https://badge.fury.io/py/graphql-api)\n[](https://pypi.org/project/graphql-api/)\n[](https://opensource.org/licenses/MIT)\n[](https://gitlab.com/parob/graphql-api/commits/master)\n[](https://gitlab.com/parob/graphql-api/commits/master)\n\n**[\ud83d\udcda Documentation](https://graphql-api.parob.com/)** | **[\ud83d\udce6 PyPI](https://pypi.org/project/graphql-api/)** | **[\ud83d\udd27 GitHub](https://github.com/parob/graphql-api)**\n\n---\n\nA powerful and intuitive Python library for building GraphQL APIs, designed with a code-first, decorator-based approach.\n\n`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.\n\n## Key Features\n\n- **Decorator-Based Schema:** Define your GraphQL schema declaratively using simple and intuitive decorators.\n- **Type Hinting:** Automatically converts Python type hints into GraphQL types.\n- **Implicit Type Inference:** Automatically maps Pydantic models, dataclasses, and classes with fields - no explicit decorators needed.\n- **Pydantic & Dataclass Support:** Seamlessly use Pydantic and Dataclass models as GraphQL types.\n- **Asynchronous Execution:** Full support for `async` and `await` for high-performance, non-blocking resolvers.\n- **Apollo Federation:** Built-in support for creating federated services.\n- **Subscriptions:** Implement real-time functionality with GraphQL subscriptions.\n- **Middleware:** Add custom logic to your resolvers with a flexible middleware system.\n- **Relay Support:** Includes helpers for building Relay-compliant schemas.\n\n## Installation\n\n```bash\npip install graphql-api\n```\n\n## Quick Start\n\nCreate a simple GraphQL API in just a few lines of code.\n\n```python\n# example.py\nfrom graphql_api.api import GraphQLAPI\n\n# 1. Initialize the API\napi = GraphQLAPI()\n\n# 2. Define your root type with decorators\n@api.type(is_root_type=True)\nclass Query:\n \"\"\"\n The root query for our amazing API.\n \"\"\"\n @api.field\n def hello(self, name: str = \"World\") -> str:\n \"\"\"\n A classic greeting.\n \"\"\"\n return f\"Hello, {name}!\"\n\n# 3. Define a query\ngraphql_query = \"\"\"\n query Greetings {\n hello(name: \"Developer\")\n }\n\"\"\"\n\n# 4. Execute the query\nif __name__ == \"__main__\":\n result = api.execute(graphql_query)\n print(result.data)\n```\n\nRunning this script will produce:\n\n```bash\n$ python example.py\n{'hello': 'Hello, Developer'}\n```\n\n## Examples\n\n### Using Pydantic Models\n\nLeverage Pydantic for data validation and structure. `graphql-api` will automatically convert your models into GraphQL types.\n\n```python\nfrom pydantic import BaseModel\nfrom typing import List\nfrom graphql_api.api import GraphQLAPI\n\nclass Book(BaseModel):\n title: str\n author: str\n\n@api.type(is_root_type=True)\nclass BookAPI:\n @api.field\n def get_books(self) -> List[Book]:\n return [\n Book(title=\"The Hitchhiker's Guide to the Galaxy\", author=\"Douglas Adams\"),\n Book(title=\"1984\", author=\"George Orwell\"),\n ]\n\napi = GraphQLAPI()\n\ngraphql_query = \"\"\"\n query {\n getBooks {\n title\n author\n }\n }\n\"\"\"\n\nresult = api.execute(graphql_query)\n# result.data will contain the list of books\n```\n\n### Asynchronous Resolvers\n\nDefine async resolvers for non-blocking I/O operations.\n\n```python\nimport asyncio\nfrom graphql_api.api import GraphQLAPI\n\napi = GraphQLAPI()\n\n@api.type(is_root_type=True)\nclass AsyncAPI:\n @api.field\n async def fetch_data(self) -> str:\n await asyncio.sleep(1)\n return \"Data fetched successfully!\"\n\n# To execute async queries, you'll need an async executor\n# or to run it within an async context.\nasync def main():\n result = await api.execute(\"\"\"\n query {\n fetchData\n }\n \"\"\")\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n\n```\n\n\n### Mutations with Dataclasses\n\nUse dataclasses to define the structure of your data, and mark fields as mutable to automatically separate them into the GraphQL Mutation type.\n\n```python\nfrom dataclasses import dataclass\nfrom graphql_api.api import GraphQLAPI\n\n@dataclass\nclass User:\n id: int\n name: str\n\n# A simple in-memory database\ndb = {1: User(id=1, name=\"Alice\")}\n\napi = GraphQLAPI()\n\n@api.type(is_root_type=True)\nclass Root:\n @api.field\n def get_user(self, user_id: int) -> User:\n return db.get(user_id)\n\n @api.field(mutable=True)\n def add_user(self, user_id: int, name: str) -> User:\n new_user = User(id=user_id, name=name)\n db[user_id] = new_user\n return new_user\n```\n\nGraphQL 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.\n\n## Related Projects\n\n- **[graphql-http](https://graphql-http.parob.com/)** - Serve your API over HTTP with authentication and GraphiQL\n- **[graphql-db](https://graphql-db.parob.com/)** - SQLAlchemy integration for database-backed APIs\n- **[graphql-mcp](https://graphql-mcp.parob.com/)** - Expose your API as MCP tools for AI agents\n\nSee the [documentation](https://graphql-api.parob.com/) for advanced schema patterns, federation, remote GraphQL, and more.\n\n## Documentation\n\n**Visit the [official documentation](https://graphql-api.parob.com/)** for comprehensive guides, tutorials, and API reference.\n\n### Key Topics\n\n- **[Getting Started](https://graphql-api.parob.com/docs/fundamentals/getting-started/)** - Quick introduction and basic usage\n- **[Defining Schemas](https://graphql-api.parob.com/docs/fundamentals/defining-schemas/)** - Learn schema definition patterns\n- **[Field Types](https://graphql-api.parob.com/docs/fundamentals/field-types/)** - Understanding GraphQL type system\n- **[Mutations](https://graphql-api.parob.com/docs/fundamentals/mutations/)** - Implementing data modifications\n- **[Remote GraphQL](https://graphql-api.parob.com/docs/distributed-systems/remote-graphql/)** - Connect to remote APIs\n- **[Federation](https://graphql-api.parob.com/docs/distributed-systems/federation/)** - Apollo Federation support\n- **[API Reference](https://graphql-api.parob.com/docs/reference/api-reference/)** - Complete API documentation\n\n## Running Tests\n\nTo contribute or run the test suite locally:\n\n```bash\n# Install dependencies\npip install pipenv\npipenv install --dev\n\n# Run tests\npipenv run pytest\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework for building Python GraphQL APIs.",
"version": "1.5.3",
"project_urls": {
"Homepage": "https://gitlab.com/parob/graphql-api",
"Repository": "https://gitlab.com/parob/graphql-api"
},
"split_keywords": [
"graphql",
" graphql-api",
" graphqlapi",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2da7a8eb5cc3be66d0c803f0b71c809164b158e5ab7cc68f0ff6cd8f1d15499f",
"md5": "b786c7c86b3fa231bcb8c524817b0c46",
"sha256": "80197a5b467d558df934a5cdbbbba456d9c09dba05575a8cc8e772c003d94c8f"
},
"downloads": -1,
"filename": "graphql_api-1.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b786c7c86b3fa231bcb8c524817b0c46",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 67981,
"upload_time": "2025-11-05T10:37:10",
"upload_time_iso_8601": "2025-11-05T10:37:10.631470Z",
"url": "https://files.pythonhosted.org/packages/2d/a7/a8eb5cc3be66d0c803f0b71c809164b158e5ab7cc68f0ff6cd8f1d15499f/graphql_api-1.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7197acce84debe22e0dbcd698b479c51dc3c73913e69b4b401b25846d63006ea",
"md5": "d5210f80fed43478cda42c2c79eccb0d",
"sha256": "535921d2565bd2bd776077cdd5403d2f92281b4b483424fc8e0917a5aabb432a"
},
"downloads": -1,
"filename": "graphql_api-1.5.3.tar.gz",
"has_sig": false,
"md5_digest": "d5210f80fed43478cda42c2c79eccb0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 243517,
"upload_time": "2025-11-05T10:37:11",
"upload_time_iso_8601": "2025-11-05T10:37:11.846657Z",
"url": "https://files.pythonhosted.org/packages/71/97/acce84debe22e0dbcd698b479c51dc3c73913e69b4b401b25846d63006ea/graphql_api-1.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 10:37:11",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "parob",
"gitlab_project": "graphql-api",
"lcname": "graphql-api"
}
