tessl/pypi-ariadne

Ariadne is a Python library for implementing GraphQL servers using a schema-first approach.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Ariadne

Name: tessl/pypi-ariadne
Author: tessl

A comprehensive Python library for implementing GraphQL servers using a schema-first approach. Ariadne provides full GraphQL compatibility with support for queries, mutations, subscriptions, custom scalars, enums, schema directives, unions, interfaces, file uploads, and asynchronous resolvers. It's designed to be simple, consistent, and modular while following GraphQL community best practices.

Package Information

Package Name: ariadne
Language: Python
Installation: pip install ariadne
Python Requirements: Python 3.9 or higher

Core Imports

import ariadne

Common imports for basic functionality:

from ariadne import ObjectType, QueryType, gql, make_executable_schema
from ariadne.asgi import GraphQL

Basic Usage

from ariadne import ObjectType, QueryType, gql, make_executable_schema
from ariadne.asgi import GraphQL

# Define GraphQL schema using Schema Definition Language
type_defs = gql("""
    type Query {
        people: [Person!]!
    }

    type Person {
        firstName: String
        lastName: String
        age: Int
        fullName: String
    }
""")

# Create query resolver
query = QueryType()

@query.field("people")
def resolve_people(*_):
    return [
        {"firstName": "John", "lastName": "Doe", "age": 21},
        {"firstName": "Bob", "lastName": "Boberson", "age": 24},
    ]

# Create object type resolver
person = ObjectType("Person")

@person.field("fullName")
def resolve_person_fullname(person, *_):
    return f"{person['firstName']} {person['lastName']}"

# Create executable schema
schema = make_executable_schema(type_defs, query, person)

# Create ASGI application
app = GraphQL(schema, debug=True)

Architecture

Ariadne follows a schema-first approach with clear separation of concerns:

Schema Definition: GraphQL schemas defined using SDL strings
Bindables: Python classes that bind resolvers to schema elements
Execution: GraphQL query execution with async/sync support
Extensions: Middleware-like system for cross-cutting concerns
ASGI Integration: Web server support for production deployment

The bindable pattern allows associating Python logic with GraphQL schema elements while maintaining loose coupling and explicit type reuse across multiple schemas.

Capabilities

Core Schema Creation

Essential functionality for creating executable GraphQL schemas from type definitions and binding Python logic to schema elements.

def make_executable_schema(
    type_defs: Union[str, list[str]],
    *bindables: Union[SchemaBindable, type[Enum], list[Union[SchemaBindable, type[Enum]]]],
    directives: Optional[dict[str, type[SchemaDirectiveVisitor]]] = None,
    convert_names_case: Union[bool, SchemaNameConverter] = False,
) -> GraphQLSchema: ...

def load_schema_from_path(path: str) -> str: ...

def gql(string: str) -> str: ...

Core Schema

GraphQL Execution

Functions for executing GraphQL queries, mutations, and subscriptions with support for both synchronous and asynchronous execution.

async def graphql(
    schema: GraphQLSchema,
    data: dict,
    *,
    context_value: Optional[Any] = None,
    root_value: Optional[Any] = None,
    debug: bool = False,
    **kwargs
) -> dict: ...

def graphql_sync(
    schema: GraphQLSchema,
    data: dict,
    *,
    context_value: Optional[Any] = None,
    root_value: Optional[Any] = None,
    debug: bool = False,
    **kwargs
) -> dict: ...

async def subscribe(
    schema: GraphQLSchema,
    data: dict,
    *,
    context_value: Optional[Any] = None,
    root_value: Optional[Any] = None,
    debug: bool = False,
    **kwargs
): ...

GraphQL Execution

Type Bindables

Classes for binding Python logic to different GraphQL schema elements including objects, scalars, enums, interfaces, unions, and input types.

class ObjectType(SchemaBindable):
    def __init__(self, name: str): ...
    def field(self, name: str): ...

class QueryType(ObjectType): ...
class MutationType(ObjectType): ...

class ScalarType(SchemaBindable):
    def __init__(self, name: str): ...
    def serializer(self, serializer_func): ...
    def value_parser(self, parser_func): ...
    def literal_parser(self, parser_func): ...

class EnumType(SchemaBindable):
    def __init__(self, name: str, values: dict): ...

class InterfaceType(SchemaBindable):
    def __init__(self, name: str): ...
    def field(self, name: str): ...
    def type_resolver(self, type_resolver_func): ...

class UnionType(SchemaBindable):
    def __init__(self, name: str): ...
    def type_resolver(self, type_resolver_func): ...

class InputType(SchemaBindable):
    def __init__(self, name: str): ...
    def out_type(self, out_type_func): ...

class SubscriptionType(SchemaBindable):
    def __init__(self, name: str): ...
    def field(self, name: str): ...
    def source(self, name: str): ...

Type Bindables

ASGI Integration

ASGI application for serving GraphQL APIs with WebSocket support for subscriptions and integration with ASGI servers.

class GraphQL:
    def __init__(
        self,
        schema: GraphQLSchema,
        *,
        context_value: Optional[Any] = None,
        root_value: Optional[Any] = None,
        debug: bool = False,
        explorer: Optional[Explorer] = None,
        **kwargs
    ): ...

ASGI Integration

Error Handling

Functions for formatting GraphQL errors and extracting error information for client responses.

def format_error(error: Exception, debug: bool = False) -> dict: ...
def get_error_extension(error: Exception) -> Optional[dict]: ...
def get_formatted_error_context(error: dict) -> Optional[Any]: ...  
def get_formatted_error_traceback(error: dict) -> Optional[str]: ...
def unwrap_graphql_error(error: Exception) -> Exception: ...

Error Handling

Resolver Utilities

Helper functions and classes for creating field resolvers with support for fallback resolvers and case conversion.

def resolve_to(value: Any): ...
def is_default_resolver(resolver: Callable) -> bool: ...

fallback_resolvers: FallbackResolversSetter
snake_case_fallback_resolvers: SnakeCaseFallbackResolversSetter

class FallbackResolversSetter(SchemaBindable): ...
class SnakeCaseFallbackResolversSetter(SchemaBindable): ...

Resolver Utilities

GraphQL Explorer

Built-in GraphQL development tools including GraphQL Playground, GraphiQL, and Apollo Studio integration for API exploration and testing.

class Explorer:
    def __init__(self, title: str = "Ariadne GraphQL"): ...

class ExplorerPlayground(Explorer): ...
class ExplorerGraphiQL(Explorer): ...
class ExplorerApollo(Explorer): ...
class ExplorerHttp405(Explorer): ...

GraphQL Explorer

File Uploads

Support for GraphQL multipart file uploads following the GraphQL multipart request specification.

def combine_multipart_data(operations: dict, files_map: dict, files: dict) -> dict: ...

upload_scalar: ScalarType

File Uploads

Apollo Federation

Support for Apollo Federation allowing microservice architecture with federated GraphQL schemas.

class FederatedObjectType(ObjectType):
    def __init__(self, name: str): ...
    def reference_resolver(self, resolver_func): ...

class FederatedInterfaceType(InterfaceType):
    def __init__(self, name: str): ...
    def reference_resolver(self, resolver_func): ...

def make_federated_schema(
    type_defs: Union[str, list[str]],
    *bindables,
    **kwargs
) -> GraphQLSchema: ...

Apollo Federation

Relay Support

Implementation of Relay specifications including connections, global object identification, and pagination.

class RelayObjectType(ObjectType):
    def __init__(self, name: str): ...

class RelayQueryType(QueryType):
    def __init__(self): ...

class RelayNodeInterfaceType(InterfaceType):
    def __init__(self): ...

class RelayConnection:
    def __init__(
        self,
        edges: list,
        page_info: dict,
        total_count: Optional[int] = None
    ): ...

class ConnectionArguments:
    first: Optional[int]
    after: Optional[str]
    last: Optional[int]
    before: Optional[str]

def encode_global_id(type_name: str, node_id: str) -> str: ...
def decode_global_id(global_id: str) -> tuple[str, str]: ...

Relay Support

Validation

Query validation tools for implementing security measures like query cost analysis and introspection control.

cost_directive: SchemaDirectiveVisitor
cost_validator: Callable

Validation

Types

# Base types
SchemaBindable = Protocol
Extension = Protocol
Resolver = Callable
SchemaBindables = Union[SchemaBindable, type[Enum], list[Union[SchemaBindable, type[Enum]]]]

# ASGI types  
Extensions = dict[str, Any]
MiddlewareList = list[Callable]
Middlewares = Union[MiddlewareList, Callable]
OnConnect = Callable
OnDisconnect = Callable
OnOperation = Callable
OnComplete = Callable
Operation = dict[str, Any]

# Relay types
ConnectionResolver = Callable
GlobalIDTuple = tuple[str, str]

# Exception types
class WebSocketConnectionError(Exception): ...

Install with Tessl CLI