0.24

Ariadne 0.18

February 21, 2023

Ariadne shipped!

Ariadne 0.18 is now available! 🚀

0.18 is a feature release bringing multiple new features and improvements to Ariadne.

New GraphQL explorers

In previous Ariadne versions GraphQL explorer was hardcoded into the GraphQL server. To customize or replace the GraphQL Playground, one had to create custom class inheriting from GraphQL and implement their own render_playground method.

In Ariadne 0.18 GraphQL explorers have been made into separate Python classes. To customize the explorer in your server, pass instance of Explorer class implementing the GraphQL explorer UI you wish to use to the explorer option of GraphQL class.

Ariadne 0.18 ships with following GraphQL explorers out of the box:

  • GraphiQL 2
  • Apollo Sandbox
  • GraphQL Playground

In addition to implementing GraphQL explorers, those classes also provide different configuration options specific to their explorer.

Implementing custom explorers is also supported!

See the explorers guide for more details.

GraphiQL 2 as default GraphQL explorer

Because GraphQL Playground is officially no longer maintainer, GraphiQL 2 is now a default GraphQL explorer in Ariadne.

GraphQL Playground is still available as an option.

Disabling the GraphQL explorer

Ariadne now provides the ExplorerHttp405 GraphQL explorer which actually doesn't implement any UI at all, but instead triggers the 405 not allowed response from the GraphQL server when explorer is accessed.

This is now the official way for disabling the GraphQL explorer UI in Ariadne.

New approach for managing different name cases between Python and GraphQL

Leading naming convention in Python is PascalCase for types and snake_case for attributes (and frequently dict keys). This causes conflict with GraphQL where fields are usually named using the camelCase.

Ariadne ships with snake_case_fallback_resolvers and convert_kwargs_to_snake_case utilities to create this convention automatically in places where no explicit convention was already specified by developer, namely in custom resolvers.

Ariadne 0.18 adds convert_schema_names option to make_executable_schema that sets this conversion automatically for entire schema:

  • Fields without custom resolvers set on them
  • Fields arguments
  • Inputs fields

See the name case conversion guide to learn more about this feature.

See the reference for details on algorithm used by Ariadne to convert camelCase names to snake_cases.

snake_case_fallback_resolvers, convert_kwargs_to_snake_case as well as FallbackResolversSetter and fallback_resolvers are now deprecated and will be removed from Ariadne in future version. We understand that migrating away from them may take a while for Ariadne's users, so we plan to keep those for few more months at least before announcing the final version those will be part of.

Better integration story for FastAPI and Starlette

Instances of the asgi.GraphQL class now expose the handle_request and handle_websocket methods which can be called from Starlette's and FastAPI's routes. This alternative approach to mounting the GraphQL as subapplication is intended to offer better integration in projects that rely heavily on other services or FastAPI's dependency injection.

Ariadne's documentation has been updated to show both of those use cases:

Dataloaders support for synchronous servers

Ariadne's public API was updated to support custom GraphQL execution contexts. This enables use of synchronous dataloaders in Ariadne.

See the dataloaders guide to learn more about dataloaders and see the code examples.

Updated reference documents

We have replaced all documents in existing "API Reference" section with new ones that are wholly generated from Ariadne's source code.

This makes them 100% accurate and much more useful to the developers already familiar with GraphQL development with Ariadne, but looking to learn about APIs and features not covered by other documents, or just to refresh their memory of the APIs.

Backwards incompatible changes

context_value function is now called with two arguments

context_value is now called with two arguments instead of one:

  • request: an representation of HTTP request specific to the framework used.
  • data: an unvalidated JSON which may be a valid GraphQL request payload.

Currently Ariadne supports both old and new functions, but it will show a warning when old function is used. To future-proof your function you can change it's signature from request to request, *_.

See the ContextValue reference.

root_value function is now called with four arguments

root_value is now called with four arguments instead of one:

  • context_value: a context value specific to this GraphQL server.
  • operation_name: a str with name of operation to execute (or None).
  • variables: a dict with variables to pass to query's resolvers (or None).
  • document: a DocumentNode with parsed GraphQL query.

Currently Ariadne supports both old and new functions, but it will show a warning when old function is used. To future-proof your function you can change it's signature from context to context, *_.

See the RootValue reference.

middleware option now expects a list of middlewares or callable returning list of middlewares

middleware option now expects a list of middlewares or callable returning list of middlewares.

This is in line with documentation that always described this use.

If you relied on custom MiddlewareManager, you can still pass it to Ariadne through the middleware_manager_class option that was added as part of this change.

Other improvements

There are few other improvements that we've found noteworthy for Ariadne 0.18:

logger option now supports Logger and LoggerAdapter instances in addition to str with logger name.

load_schema_from_path now supports Path-like objects in addition to str with path to schema.

query_parser option now enables replacement of default query parser used with custom one.

Security guide

Excellent folk from the Escape have contributed the security guide for GraphQl to Ariadne's docs.

You can find it here.

Changelog

  • GraphiQL2 is now default API explorer.
  • Added explorer option to ASGI and WSGI GraphQL applications that enables API explorer customization.
  • Added ExplorerHttp405 API explorer that returns 405 Method Not Allowed for GET HTTP requests.
  • Added implementations for GraphiQL2, GraphQL-Playground and Apollo Sandbox explorers.
  • Added convert_names_case option to make_executable_schema to convert all names in schema to Python case using default or custom strategy.
  • Added support for Path-like objects to load_schema_from_path.
  • Changed logger option to also support Logger and LoggerAdapter instance in addition to str with logger name.
  • Added support for @tag directive used by Apollo Federation.
  • Moved project configuration from setup.py to pyproject.toml.
  • Changed context_value option in ASGI and WSGI applications for callables to take query data as second argument.
  • Changed root_value option in ASGI and WSGI applications for callables to take operation and and variables in addition to context and parsed query.
  • Added execution_context_class option to ASGI and WSGI applications.
  • Added query_parser option to ASGI and WSGI GraphQL applications that enables query parsing customization.
  • Changed middleware option to work with callable or list of middlewares instead of MiddlewareManager instance.
  • Added middleware_manager_class option to ASGI and WSGI applications.
  • Added handle_request and handle_websocket methods to ASGI application that takes Starlette/FastAPI Request and Websocket objects.
  • Fixed type annotations for middlewares.
  • Added docstrings to members of public API.
Recent Posts