Skip to main content

Introspection utilities to extract data from strawberry graphql

Project description

strawberry-resources

build status coverage downloads PyPI version python version

Introspection utilities to extract data from the schema to use as helpers in the client, like building an automatic form for input types.

Installation

Just install the package with pip or your preferred package manager:

pip install strawberry-resources

How to use

Usage in a query

This lib provides a Query type that has two queries:

  • resources: Returns a list of all available resources in the schema
  • resource: Returns an specific resource given its name

You can use merge_type to merge it with your own Query type.

Then, given this example:

@strawberry.enum
class Color(enum.Enum):
    YELLOW = strawberry.enum_value("yellow", description="Color Yellow")
    RED = "red"
    ORANGE = "orange"

@strawberry.type
class Fruit:
    name: str
    color: Annotated[Color, config(label="Color")]
    weight: Annotate[float, strawberry_resource.config(label="Weight")]

@strawberry.type
class Market:
    name: Annotate[str, strawberry_resource.config(label="Market Name")]
    fruits: Annotate[List[Fruit], strawberry_resource.config(label="Fruits")]

@strawberry.type
class Query:
    market: Market

You can query resource(name: "Market") which would return:

{
  "resource": {
    "name": "Market"
    "fields": [
      {
        "__typename": "Field",
        "choices": null,
        "defaultValue": null,
        "filterable": false,
        "helpText": null,
        "kind": "STRING",
        "label": "Market Name",
        "multiple": false,
        "name": "name",
        "orderable": false,
        "resource": null,
        "validation": {
          "__typename": "BaseFieldValidation",
          "required": true
        }
      },
      {
        "__typename": "FieldObject",
        "label": "Fruits",
        "name": "fruits",
        "objKind": "OBJECT_LIST"
        "fields": [
          {
            "__typename": "Field",
            "choices": null,
            "defaultValue": null,
            "filterable": false,
            "helpText": null,
            "kind": "STRING",
            "label": "name",
            "multiple": false,
            "name": "name",
            "orderable": false,
            "resource": null,
            "validation": {
              "__typename": "BaseFieldValidation",
              "required": true
            }
          },
          {
            "__typename": "Field",
            "choices": [
              {
                "group": null,
                "label": "Color Yellow",
                "value": "YELLOW"
              },
              {
                "group": null,
                "label": "RED",
                "value": "RED"
              },
              {
                "group": null,
                "label": "ORANGE",
                "value": "ORANGE"
              }
            ],
            "defaultValue": null,
            "filterable": false,
            "helpText": null,
            "kind": "STRING",
            "label": "Color",
            "multiple": false,
            "name": "color",
            "orderable": false,
            "resource": null,
            "validation": {
              "__typename": "BaseFieldValidation",
              "required": true
            }
          },
          {
            "__typename": "Field",
            "choices": null,
            "defaultValue": null,
            "filterable": false,
            "helpText": null,
            "kind": "FLOAT",
            "label": "Weight",
            "multiple": false,
            "name": "weight",
            "orderable": false,
            "resource": null,
            "validation": {
              "__typename": "BaseFieldValidation",
              "required": true
            }
          }
        ],
      }
    ],
  }
}

Exporting the resources

You can also use the resources statically by exporting them by using the command:

strawberry_resources export --app-dir <schema>

The export functions are also exposed in strawberry_resources.exporter. There are 2 functions there:

  • to_dict: Will export the resources to a dictionary
  • to_json: Will export the resources to a json string (used by the command above)

Customizing the resource

Strawberry resource will introspect the schema to automatically fill some information regarding the field. However, you can customize them by annotating your fields with your own config.

In the example above we customized the label for most attributes, except for Fruit.name. All possible config options are:

  • kind (FieldKind): The kind of the field
  • multiple (bool): If the field is multivalued (i.e. a List)
  • orderable (bool): If the field is orderable`
  • filterable (bool): If the field is filterable`
  • label (str | None): An optional human friendly label for the field
  • help_text (str | FieldChoice): An optional list with available choices for the field
  • default_value (JSON | None): The default value for the field
  • validation (BaseFieldValidation): Validation options for the field

Check the types.py module for more details.

Integrations

Django

If you are using Django, and by extend strawberry-graphql-django or strawberry-django-plus, the integration will be automatically used to configure some options by introspecting your model.

The following will be retrieved from the fields in it, specially when typing it with strawberry.auto:

  • kind: The field kind will be automatically set based on the model field type. e.g. a CharField will generate a kind of STRING, a DateTimeField will generate a kind of DATETIME and so on.
  • orderable: Will be automatically filled if the django type has an ordering set on it, and the field itself is there
  • filterable: Will be automatically filled if the django type has filters set on it, and the field itself is there
  • label: Will be automatically filled using the field's verbose_name value
  • help_text: Will be automatically filled using the field's help_text value
  • choices: Will be automatically filled using the field's choices value
  • default_value: Will be automatically filled using the field's default value

Creating your own integration

You can create your own extension by creating an instance of strawberry_resources.integrations.StrawberryResourceIntegration. It expects 4 attributes:

  • name: The name of the integration
  • get_extra_mappings: A callable that should return a dict mapping a type to a FieldKind
  • get_field_options: A mapping that receives the type that contains the field, the field itself, the resolved type of the field and if it is a list of not. It is expect to return a dict with the options mentioned in the section above.
  • order: An optional order to be used when running the integrations.

The integrations will run in the order they are defined. The official integrations in this repo all have an order of 0, so you can define yours to run before them by passing a negative value, or after them by passing something greater than 0.

NOTE: strawberry-resources is eager to have more integrations, so feel free to open a PR for us sending yours! :)

How options are resolved

All options will be merged recursively to generate the final resource options. That means that options defined later will override the ones defined earlier. The order is the following:

  • The options will be created with its kind retrieved from the kind mapping (considering the ones returned by the integrations as well), and its label will be set the same as its name by default.
  • The integrations will run in the order they were defined, and each option returned will me merged recursively with the current options.
  • At last, options will be retrieved by the field's annotations and will have the highest priority when merging with the rest.

Licensing

The code in this project is licensed under MIT license. See LICENSE for more information.

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

strawberry_resources-0.11.0.tar.gz (17.7 kB view details)

Uploaded Source

Built Distribution

strawberry_resources-0.11.0-py3-none-any.whl (18.7 kB view details)

Uploaded Python 3

File details

Details for the file strawberry_resources-0.11.0.tar.gz.

File metadata

  • Download URL: strawberry_resources-0.11.0.tar.gz
  • Upload date:
  • Size: 17.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.7 Darwin/24.0.0

File hashes

Hashes for strawberry_resources-0.11.0.tar.gz
Algorithm Hash digest
SHA256 84eeec055e27f7ae10b85bbb83c6c0111fb09024da783ea79ebd77074ae5b628
MD5 381602d9fefe0ffc1dcb9264edffff8c
BLAKE2b-256 4c69a3552803e29d41c7b3fc9421eb0a5241e8bede3ade4ea5da11577bbb3f41

See more details on using hashes here.

File details

Details for the file strawberry_resources-0.11.0-py3-none-any.whl.

File metadata

File hashes

Hashes for strawberry_resources-0.11.0-py3-none-any.whl
Algorithm Hash digest
SHA256 00da19e5d33f19443507726f3f57ad96d7eea90fc8a8b849e12502cdbb0053f7
MD5 96500eed5a6730243cad978658666085
BLAKE2b-256 e9aa355a02e364d4d1fa02e749bd324c42eb6996a43bc795966fda02b9e1cc50

See more details on using hashes here.

Supported by

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