# GraphQL API for Python
A powerful and intuitive Python library for building GraphQL APIs, designed with a code-first, decorator-based approach.
[](https://gitlab.com/parob/graphql-api/commits/master)
[](https://gitlab.com/parob/graphql-api/commits/master)
`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.
- **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
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(root_type=BookAPI)
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
class AsyncAPI:
@api.field
async def fetch_data(self) -> str:
await asyncio.sleep(1)
return "Data fetched successfully!"
api = GraphQLAPI(root_type=AsyncAPI)
# 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_async("""
query {
fetchData
}
""")
print(result.data)
if __name__ == "__main__":
asyncio.run(main())
```
*Note: `execute_async` is a conceptual example. Refer to `test_async.py` for concrete implementation details.*
### Mutations with Dataclasses
Use dataclasses to define the structure of your mutation inputs.
```python
from dataclasses import dataclass
from graphql_api.api import GraphQLAPI, field
@dataclass
class User:
id: int
name: str
# A simple in-memory database
db = {1: User(id=1, name="Alice")}
class Root:
@field
def get_user(self, user_id: int) -> User:
return db.get(user_id)
class Mutations:
@field
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
# The GraphQLAPI constructor will need to be updated to support mutations separately
# api = GraphQLAPI(root_type=Root, mutation_type=Mutations)
```
*Note: The mutation API is illustrative. The library's `GraphQLAPI` constructor may need to be extended to support mutations as shown.*
## Running Tests
To contribute or run the test suite locally:
```bash
# Install dependencies
pip install pipenv
pipenv install --dev
# Run tests
pipenv run pytest
```
## Documentation
For more in-depth information, you can build the documentation locally.
```bash
pipenv run sphinx-build docs ./public -b html
```
Then open `public/index.html` in your browser. Note that some documentation may be outdated. For the latest features, please refer to the tests.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/parob/graphql-api",
"name": "graphql-api",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "GraphQL, GraphQL-API, GraphQLAPI, Server",
"author": "Robert Parker",
"author_email": "rob@parob.com",
"download_url": "https://files.pythonhosted.org/packages/3a/2e/0877c72d55d0bcd8507c49349941fac68dba90d4988ee08fef08d91801f9/graphql_api-1.4.11.tar.gz",
"platform": null,
"description": "# GraphQL API for Python\n\nA powerful and intuitive Python library for building GraphQL APIs, designed with a code-first, decorator-based approach.\n\n[](https://gitlab.com/parob/graphql-api/commits/master)\n\n[](https://gitlab.com/parob/graphql-api/commits/master)\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- **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\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(root_type=BookAPI)\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\nclass AsyncAPI:\n @api.field\n async def fetch_data(self) -> str:\n await asyncio.sleep(1)\n return \"Data fetched successfully!\"\n\napi = GraphQLAPI(root_type=AsyncAPI)\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_async(\"\"\"\n query {\n fetchData\n }\n \"\"\")\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n\n```\n*Note: `execute_async` is a conceptual example. Refer to `test_async.py` for concrete implementation details.*\n\n\n### Mutations with Dataclasses\n\nUse dataclasses to define the structure of your mutation inputs.\n\n```python\nfrom dataclasses import dataclass\nfrom graphql_api.api import GraphQLAPI, field\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\nclass Root:\n @field\n def get_user(self, user_id: int) -> User:\n return db.get(user_id)\n\nclass Mutations:\n @field\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# The GraphQLAPI constructor will need to be updated to support mutations separately\n# api = GraphQLAPI(root_type=Root, mutation_type=Mutations)\n```\n*Note: The mutation API is illustrative. The library's `GraphQLAPI` constructor may need to be extended to support mutations as shown.*\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\n## Documentation\n\nFor more in-depth information, you can build the documentation locally.\n\n```bash\npipenv run sphinx-build docs ./public -b html\n```\nThen open `public/index.html` in your browser. Note that some documentation may be outdated. For the latest features, please refer to the tests.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework for building Python GraphQL APIs.",
"version": "1.4.11",
"project_urls": {
"Download": "https://gitlab.com/parob/graphql/-/archive/v1.4.11/graphql_api-v1.4.11.tar.gz",
"Homepage": "https://gitlab.com/parob/graphql-api"
},
"split_keywords": [
"graphql",
" graphql-api",
" graphqlapi",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d68a00a79e34c2f3487f50407a77e7cbc3c0236279f388908fef15cd8c36d427",
"md5": "cbfb5216313df7f477aa319ab9a481d7",
"sha256": "9442ce59cc73141ea4c342f6d598c8892233387b4620902d47f58b384b14ba05"
},
"downloads": -1,
"filename": "graphql_api-1.4.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cbfb5216313df7f477aa319ab9a481d7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 100194,
"upload_time": "2025-07-31T23:36:30",
"upload_time_iso_8601": "2025-07-31T23:36:30.363911Z",
"url": "https://files.pythonhosted.org/packages/d6/8a/00a79e34c2f3487f50407a77e7cbc3c0236279f388908fef15cd8c36d427/graphql_api-1.4.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3a2e0877c72d55d0bcd8507c49349941fac68dba90d4988ee08fef08d91801f9",
"md5": "4c684cb291bf198e99b87c7a05dde8bf",
"sha256": "4b33b8bf1495c3b8bcc13c64796d16400cfd515b43987d6c0d8a92ae3e55ca08"
},
"downloads": -1,
"filename": "graphql_api-1.4.11.tar.gz",
"has_sig": false,
"md5_digest": "4c684cb291bf198e99b87c7a05dde8bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 89625,
"upload_time": "2025-07-31T23:36:32",
"upload_time_iso_8601": "2025-07-31T23:36:32.516440Z",
"url": "https://files.pythonhosted.org/packages/3a/2e/0877c72d55d0bcd8507c49349941fac68dba90d4988ee08fef08d91801f9/graphql_api-1.4.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 23:36:32",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "parob",
"gitlab_project": "graphql-api",
"lcname": "graphql-api"
}
JSON