Scalars🔗

In this section, we'll cover how GraphQL scalars work in Undine. Scalars are GraphQL types that represent concrete data types like strings, numbers, and booleans.

Built-in Scalars🔗

In addition to GraphQL's built-in scalars of Int, Float, String, Boolean, and ID, Undine provides its own scalars that are useful for representing common data types in Python.

Any🔗

Represent any value accepted by GraphQL. Used for e.g. for UnionTypes.

Base16🔗

Represents a base16-encoded string as defined in RFC 4648.

Base32🔗

Represents a base32-encoded string as defined in RFC 4648.

Base64🔗

Represents a base64-encoded string as defined in RFC 4648.

Date🔗

Represents a date value as specified by ISO 8601. Maps to the Python datetime.date type. See RFC 3339.

DateTime🔗

Represents a date and time value as specified by ISO 8601. Maps to the Python datetime.datetime type. See RFC 3339.

Decimal🔗

Represents a number as a string for correctly rounded floating point arithmetic. Maps to the Python decimal.Decimal type.

Duration🔗

Represents a duration of time in seconds. Maps to the Python datetime.timedelta type.

Email🔗

Represents a valid email address. See RFC 5322.

File🔗

Represents any kind of file. See the file upload section.

IP🔗

Represents a valid IPv4 or IPv6 address. See RFC 8200. and RFC 791.

IPv4🔗

Represents a valid IPv4 address. See RFC 791.

IPv6🔗

Represents a valid IPv6 address. See RFC 8200.

Image🔗

Represents an image file. See the file upload section.

JSON🔗

Represents a JSON serializable object. Maps to the Python dict type. See RFC 8259.

Null🔗

Represents represents an always null value. Maps to the Python None value.

Time🔗

Represents a time value as specified by ISO 8601. Maps to the Python datetime.time type. See RFC 3339.

URL🔗

Represents a valid URL. See RFC 3986.

UUID🔗

Represents a universally unique identifier string. Maps to Python's uuid.UUID type. See RFC 9562.

Modifying existing scalars🔗

All scalars have two functions that define its operation:

1. parse, which is used to parse incoming data to python types
2. serialize, which is used to serialize python data to GraphQL accepted types

For Undine's additional built-in scalars, these functions are single dispatch generic functions. This means that you can register different implementations for the functions which are used depending on the type of the input value. Think of them like a dynamic switch statement. This allows you to replace or extend the behavior of a scalar depending on your use case.

For example, you might want to use the whenever library instead or in addition to python's built-in datetime. To do this, you can register a new implementation for the parse function of the DateTime scalar.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from whenever import Instant, PlainDateTime, ZonedDateTime

from undine.scalars.datetime import datetime_scalar


@datetime_scalar.parse.register
def _(value: str) -> ZonedDateTime:
    # Default "str" parse overridden to use 'whenever'
    return ZonedDateTime.parse_common_iso(value)


@datetime_scalar.serialize.register
def _(value: Instant | ZonedDateTime | PlainDateTime) -> str:
    # Extend serialization with types from 'whenever'.
    # Same implementation for all types in the union
    return value.format_common_iso()

Custom scalars🔗

You can also define your own scalars to represent types that cannot be represented by any of Undine's built-in scalars. Let's create a new scalar named Vector3 that represents a 3D vector using a tuple of three integers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

from django.core.exceptions import ValidationError

from undine.scalars import ScalarType

Vector3 = tuple[int, int, int]

# Create a new ScalarType for our custom scalar.
# In `ScalarType[Vector3, str]`, the first type parameter is the type that
# the scalar will parse to, and the second the type that it will serialize to.
vector3_scalar: ScalarType[Vector3, str] = ScalarType(
    name="Vector3",
    description="Represents a 3D vector as a string in format 'X,Y,Z'.",
)

# Create the GraphQLScalarType from graphql-core.
# This is the actual scalar we can add to our schema.
GraphQLVector3 = vector3_scalar.as_graphql_scalar()


# Register the parse and serialize functions for our scalar.
@vector3_scalar.parse.register
def _(value: str) -> Vector3:
    try:
        x, y, z = value.split(",")
        return int(x.strip()), int(y.strip()), int(z.strip())

    except ValueError as error:
        msg = f"Invalid vector format: {value}"
        raise ValidationError(msg) from error


@vector3_scalar.serialize.register
def _(value: tuple) -> str:
    if len(value) != 3:
        msg = f"Vector must have 3 components, got {len(value)}"
        raise ValidationError(msg)

    if not isinstance(value[0], int):
        msg = f"Vector component X is not an integer, got {value[0]}"
        raise ValidationError(msg)

    if not isinstance(value[1], int):
        msg = f"Vector component Y is not an integer, got {value[1]}"
        raise ValidationError(msg)

    if not isinstance(value[2], int):
        msg = f"Vector component Z is not an integer, got {value[2]}"
        raise ValidationError(msg)

    return f"{value[0]},{value[1]},{value[2]}"

If Vector3 corresponds to a Django Model field, you could also let Undine know about it by registering it for its many built-in converters. This way a Model field can be converted automatically to your scalar for Fields, Inputs, Filters, and Orders. More on this in the "Hacking Undine" section.