Skip to main content

A Wagtail package that speeds up and simplifies implementing a GraphQL endpoint!

Project description

A red g with a grapple hook

Wagtail Grapple

Build status Ruff PyPi pre-commit.ci status

A library to build GraphQL endpoints easily so you can grapple your Wagtail data from anywhere!

Explore the docs » · Report Bug · Request Feature

About The Project

There is a range of GraphQL packages for Python and specifically Django. However, getting these packages to work out of the box with an existing infrastructure without errors isn't as easy to come by.

The purpose of Grapple is to be able to build GraphQL endpoints on a model by model basis as quickly as possible. The setup and configuration have been designed to be as simple but also provide the best features; No complex serializers need to be written - just add a graphql_fields list to your model and away you go (although if you want to go deeper you can!).

Features

  • Easily create GraphQL types by adding a small annotation in your models.
  • Supports traditional Wagtail models:
    • Pages (including StreamField & Orderables)
    • Snippets
    • Images
    • Documents
    • Media (via wagtailmedia)
    • Settings
    • Redirects
    • Search (on all models)
  • Custom Image & Document model support
  • Pagination support
  • Middleware support

Built With

This library is an abstraction upon and relies heavily on Graphene & Graphene Django.

Getting Started

Getting Grapple installed is designed to be as simple as possible!

Prerequisites

Python >= 3.9
Wagtail >= 6.3
Django >= 4.2

Installation

Install using pip

python -m pip install wagtail_grapple

Add the following to the INSTALLED_APPS list in your Wagtail settings file:

INSTALLED_APPS = [
    # ...
    "grapple",
    "graphene_django",
    # ...
]

Add the following to the bottom of the same settings file, where each key is the app you want to this library to scan and the value is the prefix you want to give to GraphQL types (you can usually leave this blank):

# Grapple config:
GRAPHENE = {"SCHEMA": "grapple.schema.schema"}
GRAPPLE = {
    "APPS": ["home"],
}

Add the GraphQL URLs to your urls.py:

from django.urls import include, path
from grapple import urls as grapple_urls

# ...
urlpatterns = [
    # ...
    path("api/", include(grapple_urls)),
    # ...
]

Done! Now you can proceed onto configuring your models to generate GraphQL types that adopt their structure :tada: Your GraphQL endpoint is available at http://localhost:8000/api/graphql/

Usage

Here is a GraphQL model configuration for the default page from the Wagtail docs:

# ...
from grapple.models import GraphQLString, GraphQLStreamfield


class BlogPage(Page):
    author = models.CharField(max_length=255)
    date = models.DateField("Post date")
    body = StreamField(
        [
            ("heading", blocks.CharBlock(classname="full title")),
            ("paragraph", blocks.RichTextBlock()),
            ("image", ImageChooserBlock()),
        ]
    )

    content_panels = Page.content_panels + [
        FieldPanel("author"),
        FieldPanel("date"),
        StreamFieldPanel("body"),
    ]

    # Note these fields below:
    graphql_fields = [
        GraphQLString("heading"),
        GraphQLString("date"),
        GraphQLString("author"),
        GraphQLStreamfield("body"),
    ]

For more examples, please refer to the Documentation

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the project
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Local development

  • In the Python environment of your choice, navigate to tests/
  • Run python -m pip install -r requirements.txt
  • Run python manage.py migrate
  • Run server python manage.py runserver
  • Run tests python manage.py test

With Postgres

  • Ensure you have docker and docker compose
  • Run docker compose up
  • Run export DATABASE_URL="postgres://postgres:postgres@localhost/postgres"
  • In the Python environment of your choice, navigate to tests/
  • Run python -m pip install -r requirements.txt
  • Run python manage.py migrate
  • Run server python manage.py runserver
  • Run tests python manage.py test

Compatibility

Wagtail Grapple supports:

  • Python 3.9, 3.10, 3.11, 3.12 and 3.13
  • Wagtail >= 6.3

License

Distributed under the MIT License. See LICENSE for more information.

Inspired by

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

wagtail_grapple-0.29.0.tar.gz (39.1 kB view details)

Uploaded Source

Built Distribution

wagtail_grapple-0.29.0-py3-none-any.whl (49.1 kB view details)

Uploaded Python 3

File details

Details for the file wagtail_grapple-0.29.0.tar.gz.

File metadata

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

File hashes

Hashes for wagtail_grapple-0.29.0.tar.gz
Algorithm Hash digest
SHA256 56b023dcfdce72532fba00610507b2705bf3a0be068946275c7658314de5431a
MD5 75dc47ba5b2b36d92625d7712f5ae4e2
BLAKE2b-256 c066abe1b5ad7c335ff3969190c38ac259285b9f107d8273a18cc8c0ba0d36c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for wagtail_grapple-0.29.0.tar.gz:

Publisher: publish.yml on torchbox/wagtail-grapple

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

File details

Details for the file wagtail_grapple-0.29.0-py3-none-any.whl.

File metadata

File hashes

Hashes for wagtail_grapple-0.29.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d9c8c76bd9ba8c52ba1796b86043360d5ab083b24db6caaf2b1e6e41a7a2503e
MD5 dae40759242b2092a503149a96c38b31
BLAKE2b-256 48aea7a26e331f9207ed864ebea292aac6af1e19a221391d2f833cd4fbe70f68

See more details on using hashes here.

Provenance

The following attestation bundles were made for wagtail_grapple-0.29.0-py3-none-any.whl:

Publisher: publish.yml on torchbox/wagtail-grapple

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