Skip to main content

Ariadne is a Python library for implementing GraphQL servers.

Project description

Ariadne

Documentation Codecov


Ariadne

Ariadne is a Python library for implementing GraphQL servers.

  • Schema-first: Ariadne enables Python developers to use schema-first approach to the API implementation. This is the leading approach used by the GraphQL community and supported by dozens of frontend and backend developer tools, examples, and learning resources. Ariadne makes all of this immediately available to you and other members of your team.
  • Simple: Ariadne offers small, consistent and easy to memorize API that lets developers focus on business problems, not the boilerplate.
  • Open: Ariadne was designed to be modular and open for customization. If you are missing or unhappy with something, extend or easily swap with your own.

Documentation is available here.

Features

  • Simple, quick to learn and easy to memorize API.
  • Compatibility with GraphQL.js version 15.5.1.
  • Queries, mutations and input types.
  • Asynchronous resolvers and query execution.
  • Subscriptions.
  • Custom scalars, enums and schema directives.
  • Unions and interfaces.
  • File uploads.
  • Defining schema using SDL strings.
  • Loading schema from .graphql, .gql, and .graphqls files.
  • WSGI middleware for implementing GraphQL in existing sites.
  • Apollo Tracing and OpenTracing extensions for API monitoring.
  • Opt-in automatic resolvers mapping between camelCase and snake_case, and a @convert_kwargs_to_snake_case function decorator for converting camelCase kwargs to snake_case.
  • Built-in simple synchronous dev server for quick GraphQL experimentation and GraphQL Playground.
  • Support for Apollo GraphQL extension for Visual Studio Code.
  • GraphQL syntax validation via gql() helper function. Also provides colorization if Apollo GraphQL extension is installed.
  • No global state or object registry, support for multiple GraphQL APIs in same codebase with explicit type reuse.
  • Support for Apollo Federation.

Installation

Ariadne can be installed with pip:

pip install ariadne

Ariadne requires Python 3.9 or higher.

Quickstart

The following example creates an API defining Person type and single query field people returning a list of two persons. It also starts a local dev server with GraphQL Playground available on the http://127.0.0.1:8000 address.

Start by installing uvicorn, an ASGI server we will use to serve the API:

pip install uvicorn

Then create an example.py file for your example application:

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

# Define types using Schema Definition Language (https://graphql.org/learn/schema/)
# Wrapping string in gql function provides validation and better error traceback
type_defs = gql("""
    type Query {
        people: [Person!]!
    }

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

# Map resolver functions to Query fields using QueryType
query = QueryType()

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


# Map resolver functions to custom type fields using ObjectType
person = ObjectType("Person")

@person.field("fullName")
def resolve_person_fullname(person, *_):
    return "%s %s" % (person["firstName"], person["lastName"])

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

# Create an ASGI app using the schema, running in debug mode
app = GraphQL(schema, debug=True)

Finally run the server:

uvicorn example:app

For more guides and examples, please see the documentation.

Versioning policy

ariadne follows a custom versioning scheme where the minor version increases for breaking changes, while the patch version increments for bug fixes, enhancements, and other non-breaking updates.

Since ariadne has not yet reached a stable API, this approach is in place until version 1.0.0. Once the API stabilizes, the project will adopt Semantic Versioning.

Contributing

We are welcoming contributions to Ariadne! If you've found a bug or issue, feel free to use GitHub issues. If you have any questions or feedback, don't hesitate to catch us on GitHub discussions.

For guidance and instructions, please see CONTRIBUTING.md.

Website and the docs have their own GitHub repository: mirumee/ariadne-website

Also make sure you follow @AriadneGraphQL on Twitter for latest updates, news and random musings!

Crafted with ❤️ by Mirumee Software hello@mirumee.com

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ariadne-0.26.2.tar.gz (81.9 kB view details)

Uploaded Source

Built Distribution

ariadne-0.26.2-py3-none-any.whl (116.8 kB view details)

Uploaded Python 3

File details

Details for the file ariadne-0.26.2.tar.gz.

File metadata

  • Download URL: ariadne-0.26.2.tar.gz
  • Upload date:
  • Size: 81.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for ariadne-0.26.2.tar.gz
Algorithm Hash digest
SHA256 607617f82760c039b2137b7c1200b475ea90ccf4ca42c0994926c0d8fdede908
MD5 c9e604d49aa23eea634a2178f3a82e8e
BLAKE2b-256 bbe586f530bb26105520ada238f734abfea2257b754ff08055eb7d542c657e74

See more details on using hashes here.

Provenance

The following attestation bundles were made for ariadne-0.26.2.tar.gz:

Publisher: publish.yml on mirumee/ariadne

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ariadne-0.26.2-py3-none-any.whl.

File metadata

  • Download URL: ariadne-0.26.2-py3-none-any.whl
  • Upload date:
  • Size: 116.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for ariadne-0.26.2-py3-none-any.whl
Algorithm Hash digest
SHA256 8d272c73a751d30a1c9c367318a317483588a51c335351d7342f23f109816a92
MD5 125bb59bf73c1887e44517155c169911
BLAKE2b-256 ddd2fc23a8678c5d528d3f7202a749a7b7f1c0b7315b853143f3b3cf438d78a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for ariadne-0.26.2-py3-none-any.whl:

Publisher: publish.yml on mirumee/ariadne

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page