mirror of
https://github.com/graphql-python/graphene.git
synced 2025-10-31 16:07:27 +03:00
310 lines
7.9 KiB
ReStructuredText
310 lines
7.9 KiB
ReStructuredText
.. _Scalars:
|
||
|
||
Scalars
|
||
=======
|
||
|
||
Scalar types represent concrete values at the leaves of a query. There are
|
||
several built in types that Graphene provides out of the box which represent common
|
||
values in Python. You can also create your own Scalar types to better express
|
||
values that you might have in your data model.
|
||
|
||
All Scalar types accept the following arguments. All are optional:
|
||
|
||
``name``: *string*
|
||
|
||
Override the name of the Field.
|
||
|
||
``description``: *string*
|
||
|
||
A description of the type to show in the GraphiQL browser.
|
||
|
||
``required``: *boolean*
|
||
|
||
If ``True``, the server will enforce a value for this field. See `NonNull <../list-and-nonnull.html#nonnull>`_. Default is ``False``.
|
||
|
||
``deprecation_reason``: *string*
|
||
|
||
Provide a deprecation reason for the Field.
|
||
|
||
``default_value``: *any*
|
||
|
||
Provide a default value for the Field.
|
||
|
||
|
||
|
||
Built in scalars
|
||
----------------
|
||
|
||
Graphene defines the following base Scalar Types that match the default `GraphQL types <https://graphql.org/learn/schema/#scalar-types>`_:
|
||
|
||
``graphene.String``
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents textual data, represented as UTF-8
|
||
character sequences. The String type is most often used by GraphQL to
|
||
represent free-form human-readable text.
|
||
|
||
``graphene.Int``
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
Represents non-fractional signed whole numeric
|
||
values. Int is a signed 32‐bit integer per the
|
||
`GraphQL spec <https://facebook.github.io/graphql/June2018/#sec-Int>`_
|
||
|
||
``graphene.Float``
|
||
^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents signed double-precision fractional
|
||
values as specified by
|
||
`IEEE 754 <http://en.wikipedia.org/wiki/IEEE_floating_point>`_.
|
||
|
||
``graphene.Boolean``
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents `true` or `false`.
|
||
|
||
``graphene.ID``
|
||
^^^^^^^^^^^^^^^
|
||
|
||
Represents a unique identifier, often used to
|
||
refetch an object or as key for a cache. The ID type appears in a JSON
|
||
response as a String; however, it is not intended to be human-readable.
|
||
When expected as an input type, any string (such as `"4"`) or integer
|
||
(such as `4`) input value will be accepted as an ID.
|
||
|
||
----
|
||
|
||
Graphene also provides custom scalars for common values:
|
||
|
||
``graphene.Date``
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
Represents a Date value as specified by `iso8601 <https://en.wikipedia.org/wiki/ISO_8601>`_.
|
||
|
||
.. code:: python
|
||
|
||
import datetime
|
||
from graphene import Schema, ObjectType, Date
|
||
|
||
class Query(ObjectType):
|
||
one_week_from = Date(required=True, date_input=Date(required=True))
|
||
|
||
def resolve_one_week_from(root, info, date_input):
|
||
assert date_input == datetime.date(2006, 1, 2)
|
||
return date_input + datetime.timedelta(weeks=1)
|
||
|
||
schema = Schema(query=Query)
|
||
|
||
results = schema.execute("""
|
||
query {
|
||
oneWeekFrom(dateInput: "2006-01-02")
|
||
}
|
||
""")
|
||
|
||
assert results.data == {"oneWeekFrom": "2006-01-09"}
|
||
|
||
|
||
``graphene.DateTime``
|
||
^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents a DateTime value as specified by `iso8601 <https://en.wikipedia.org/wiki/ISO_8601>`_.
|
||
|
||
.. code:: python
|
||
|
||
import datetime
|
||
from graphene import Schema, ObjectType, DateTime
|
||
|
||
class Query(ObjectType):
|
||
one_hour_from = DateTime(required=True, datetime_input=DateTime(required=True))
|
||
|
||
def resolve_one_hour_from(root, info, datetime_input):
|
||
assert datetime_input == datetime.datetime(2006, 1, 2, 15, 4, 5)
|
||
return datetime_input + datetime.timedelta(hours=1)
|
||
|
||
schema = Schema(query=Query)
|
||
|
||
results = schema.execute("""
|
||
query {
|
||
oneHourFrom(datetimeInput: "2006-01-02T15:04:05")
|
||
}
|
||
""")
|
||
|
||
assert results.data == {"oneHourFrom": "2006-01-02T16:04:05"}
|
||
|
||
``graphene.Time``
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
Represents a Time value as specified by `iso8601 <https://en.wikipedia.org/wiki/ISO_8601>`_.
|
||
|
||
.. code:: python
|
||
|
||
import datetime
|
||
from graphene import Schema, ObjectType, Time
|
||
|
||
class Query(ObjectType):
|
||
one_hour_from = Time(required=True, time_input=Time(required=True))
|
||
|
||
def resolve_one_hour_from(root, info, time_input):
|
||
assert time_input == datetime.time(15, 4, 5)
|
||
tmp_time_input = datetime.datetime.combine(datetime.date(1, 1, 1), time_input)
|
||
return (tmp_time_input + datetime.timedelta(hours=1)).time()
|
||
|
||
schema = Schema(query=Query)
|
||
|
||
results = schema.execute("""
|
||
query {
|
||
oneHourFrom(timeInput: "15:04:05")
|
||
}
|
||
""")
|
||
|
||
assert results.data == {"oneHourFrom": "16:04:05"}
|
||
|
||
``graphene.Decimal``
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents a Python Decimal value.
|
||
|
||
.. code:: python
|
||
|
||
import decimal
|
||
from graphene import Schema, ObjectType, Decimal
|
||
|
||
class Query(ObjectType):
|
||
add_one_to = Decimal(required=True, decimal_input=Decimal(required=True))
|
||
|
||
def resolve_add_one_to(root, info, decimal_input):
|
||
assert decimal_input == decimal.Decimal("10.50")
|
||
return decimal_input + decimal.Decimal("1")
|
||
|
||
schema = Schema(query=Query)
|
||
|
||
results = schema.execute("""
|
||
query {
|
||
addOneTo(decimalInput: "10.50")
|
||
}
|
||
""")
|
||
|
||
assert results.data == {"addOneTo": "11.50"}
|
||
|
||
``graphene.JSONString``
|
||
^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents a JSON string.
|
||
|
||
.. code:: python
|
||
|
||
from graphene import Schema, ObjectType, JSONString, String
|
||
|
||
class Query(ObjectType):
|
||
update_json_key = JSONString(
|
||
required=True,
|
||
json_input=JSONString(required=True),
|
||
key=String(required=True),
|
||
value=String(required=True)
|
||
)
|
||
|
||
def resolve_update_json_key(root, info, json_input, key, value):
|
||
assert json_input == {"name": "Jane"}
|
||
json_input[key] = value
|
||
return json_input
|
||
|
||
schema = Schema(query=Query)
|
||
|
||
results = schema.execute("""
|
||
query {
|
||
updateJsonKey(jsonInput: "{\\"name\\": \\"Jane\\"}", key: "name", value: "Beth")
|
||
}
|
||
""")
|
||
|
||
assert results.data == {"updateJsonKey": "{\"name\": \"Beth\"}"}
|
||
|
||
|
||
``graphene.Base64``
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
Represents a Base64 encoded string.
|
||
|
||
.. code:: python
|
||
|
||
from graphene import Schema, ObjectType, Base64
|
||
|
||
class Query(ObjectType):
|
||
increment_encoded_id = Base64(
|
||
required=True,
|
||
base64_input=Base64(required=True),
|
||
)
|
||
|
||
def resolve_increment_encoded_id(root, info, base64_input):
|
||
assert base64_input == "4"
|
||
return int(base64_input) + 1
|
||
|
||
schema = Schema(query=Query)
|
||
|
||
results = schema.execute("""
|
||
query {
|
||
incrementEncodedId(base64Input: "NA==")
|
||
}
|
||
""")
|
||
|
||
assert results.data == {"incrementEncodedId": "NQ=="}
|
||
|
||
|
||
|
||
Custom scalars
|
||
--------------
|
||
|
||
You can create custom scalars for your schema.
|
||
The following is an example for creating a DateTime scalar:
|
||
|
||
.. code:: python
|
||
|
||
import datetime
|
||
from graphene.types import Scalar
|
||
from graphql.language import ast
|
||
|
||
class DateTime(Scalar):
|
||
'''DateTime Scalar Description'''
|
||
|
||
@staticmethod
|
||
def serialize(dt):
|
||
return dt.isoformat()
|
||
|
||
@staticmethod
|
||
def parse_literal(node, _variables=None):
|
||
if isinstance(node, ast.StringValueNode):
|
||
return datetime.datetime.strptime(
|
||
node.value, "%Y-%m-%dT%H:%M:%S.%f")
|
||
|
||
@staticmethod
|
||
def parse_value(value):
|
||
return datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%f")
|
||
|
||
Mounting Scalars
|
||
----------------
|
||
|
||
Scalars mounted in a ``ObjectType``, ``Interface`` or ``Mutation`` act as
|
||
``Field``\ s.
|
||
|
||
.. code:: python
|
||
|
||
class Person(graphene.ObjectType):
|
||
name = graphene.String()
|
||
|
||
# Is equivalent to:
|
||
class Person(graphene.ObjectType):
|
||
name = graphene.Field(graphene.String)
|
||
|
||
|
||
**Note:** when using the ``Field`` constructor directly, pass the type and
|
||
not an instance.
|
||
|
||
Types mounted in a ``Field`` act as ``Argument``\ s.
|
||
|
||
|
||
.. code:: python
|
||
|
||
graphene.Field(graphene.String, to=graphene.String())
|
||
|
||
# Is equivalent to:
|
||
graphene.Field(graphene.String, to=graphene.Argument(graphene.String))
|