graphql-python/graphene
1
1
Fork 0
mirror of https://github.com/graphql-python/graphene.git synced 2025-09-21 11:22:33 +03:00
Code Issues Packages Projects Releases Wiki Activity

document graphene core API

Browse Source
This commit is contained in:
Dave A 2019-05-25 15:45:54 -04:00
parent 79f84706ec
commit 882d18e245
15 changed files with 408 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
docs/api/index.rst
View File

@ -10,80 +10,85 @@ Schema
.. Uncomment sections / types as API documentation is fleshed out
.. in each class
.. Object types
.. ------------
Object types
------------
.. .. autoclass:: graphene.ObjectType
.. autoclass:: graphene.ObjectType
.. .. autoclass:: graphene.InputObjectType
.. autoclass:: graphene.InputObjectType
.. Fields (Mounted Types)
.. ----------------------
.. autoclass:: graphene.Mutation
:members:
.. .. autoclass:: graphene.Field
Fields (Mounted Types)
----------------------
.. .. autoclass:: graphene.Argument
.. autoclass:: graphene.Field
.. .. autoclass:: graphene.InputField
.. autoclass:: graphene.Argument
.. GraphQL Scalars
.. ---------------
.. autoclass:: graphene.InputField
.. .. autoclass:: graphene.Int
Fields (Unmounted Types)
------------------------
.. .. autoclass:: graphene.Float
.. autoclass:: graphene.types.unmountedtype.UnmountedType
.. .. autoclass:: graphene.String
GraphQL Scalars
---------------
.. .. autoclass:: graphene.Boolean
.. autoclass:: graphene.Int()
.. .. autoclass:: graphene.ID
.. autoclass:: graphene.Float()
.. Graphene Scalars
.. ----------------
.. autoclass:: graphene.String()
.. .. autoclass:: graphene.Date
.. autoclass:: graphene.Boolean()
.. .. autoclass:: graphene.DateTime
.. autoclass:: graphene.ID()
.. .. autoclass:: graphene.Time
Graphene Scalars
----------------
.. .. autoclass:: graphene.Decimal
.. autoclass:: graphene.Date()
.. .. autoclass:: graphene.UUID
.. autoclass:: graphene.DateTime()
.. .. autoclass:: graphene.JSONString
.. autoclass:: graphene.Time()
.. Structures
.. ----------
.. autoclass:: graphene.Decimal()
.. .. autoclass:: graphene.List
.. autoclass:: graphene.UUID()
.. .. autoclass:: graphene.NonNull
.. autoclass:: graphene.JSONString()
.. Enum
.. ----
Enum
----
.. .. autoclass:: graphene.Enum
.. autoclass:: graphene.Enum()
.. Type Extension
.. --------------
Structures
----------
.. .. autoclass:: graphene.Interface
.. autoclass:: graphene.List
.. .. autoclass:: graphene.Union
.. autoclass:: graphene.NonNull
.. Execution Metadata
.. ------------------
Type Extension
--------------
.. .. autoclass:: graphene.ResolveInfo
.. autoclass:: graphene.Interface()
.. .. autoclass:: graphene.Context
.. autoclass:: graphene.Union()
.. Mutation
.. --------
Execution Metadata
------------------
.. .. autoclass:: graphene.Mutation
.. autoclass:: graphene.ResolveInfo
.. autoclass:: graphene.Context
.. autoclass:: graphql.execution.base.ExecutionResult
.. Relay
.. -----

29
graphene/types/argument.py
View File

@ -8,6 +8,35 @@ from .utils import get_type
class Argument(MountedType):
"""
Makes an Argument available on a Field in the GraphQL schema.
Arguments will be parsed and provided to resolver methods for fields as keyword arguments.
All ``arg`` and ``**extra_args`` for a ``graphene.Field`` are implicitly mounted as Argument
using the below parameters.
.. code:: python
age = graphene.String(
# Boolean implicitly mounted as Argument
dog_years=graphene.Boolean(description='convert to dog years'),
# Boolean explicitly mounted as Argument
decades=graphene.Argument(graphene.Boolean, default_value=False)
)
args:
type (class for a graphene.UnmountedType): must be a class (not an instance) of an
unmounted graphene type (ex. scalar or object) which is used for the type of this
argument in the GraphQL schema.
required (bool). Indicates this argument as not null in the graphql scehma. Same behavior
as graphene.NonNull. Default False.
name (str): the name of the GraphQL argument. Defaults to parameter name.
description (str): the description of the GraphQL argument in the schema.
default_value (Any): The value to be provided if the user does not set this argument in
the operation.
"""
def __init__(
self,
type,

19
graphene/types/context.py
View File

@ -1,4 +1,23 @@
class Context(object):
"""
Context can be used to make a convenient container for attributes to provide
for execution for resolvers of a GraphQL operation like a query.
.. code:: python
context = Context(loaders=build_dataloaders(), request=my_web_request)
schema.execute('{ hello(name: "world") }', context=context)
def resolve_hello(parent, info, name):
info.context.request # value set in Context
info.context.loaders # value set in Context
# ...
args:
**params (Dict[str, Any]): values to make available on Context instance as attributes.
"""
def __init__(self, **params):
for key, value in params.items():
setattr(self, key, value)

22
graphene/types/enum.py
View File

@ -67,6 +67,28 @@ class EnumMeta(SubclassWithMeta_Meta):
class Enum(six.with_metaclass(EnumMeta, UnmountedType, BaseType)):
"""
Enum type defintion
Defines a static set of values that can be provided as a Field, Argument or InputField.
.. code:: python
class NameFormat(graphene.Enum):
FIRST_LAST = 'first_last'
LAST_FIRST = 'last_first'
Meta:
enum (optional, Enum): Python enum to use as a base for GraphQL Enum.
name (optional, str): the name of the GraphQL type (must be unique in schema). Defaults to class
name.
description (optional, str): the description of the GraphQL type in the schema. Defaults to class
docstring.
deprecation_reason (optional, str): Setting this value indicates that the enum is
depreciated and may provide instruction or reason on how for clients to proceed.
"""
@classmethod
def __init_subclass_with_meta__(cls, enum=None, _meta=None, **options):
if not _meta:

41
graphene/types/field.py
View File

@ -19,6 +19,47 @@ def source_resolver(source, root, info, **args):
class Field(MountedType):
"""
Makes a field available on an ObjectType in the GraphQL schema. Any type can be mounted as a
Field:
- Object Type
- Scalar Type
- Enum
- Interface
- Union
All class attributes of ``graphene.ObjectType`` are implicitly mounted as Field using the below
arguments.
.. code:: python
class Person(ObjectType):
first_name = graphene.String(required=True) # implicitly mounted as Field
last_name = graphene.Field(String, description='Surname') # explicitly mounted as Field
args:
type (class for a graphene.UnmountedType): must be a class (not an instance) of an
unmounted graphene type (ex. scalar or object) which is used for the type of this
field in the GraphQL schema.
args (optional, Dict[str, graphene.Argument]): arguments that can be input to the field.
Prefer to use **extra_args.
resolver (optional, Callable): A function to get the value for a Field from the parent
value object. If not set, the default resolver method for the schema is used.
source (optional, str): attribute name to resolve for this field from the parent value
object. Alternative to resolver (cannot set both source and resolver).
deprecation_reason (optional, str): Setting this value indicates that the field is
depreciated and may provide instruction or reason on how for clients to proceed.
required (optional, bool). Indicates this field as not null in the graphql scehma. Same behavior as
graphene.NonNull. Default False.
name (optional, str): the name of the GraphQL field (must be unique in a type). Defaults to attribute
name.
description (optional, str): the description of the GraphQL field in the schema.
default_value (optional, Any): Default value to resolve if none set from schema.
**extra_args (optional, Dict[str, Union[graphene.Argument, graphene.UnmountedType]): any
additional arguments to mount on the field.
"""
def __init__(
self,
type,

36
graphene/types/inputfield.py
View File

@ -4,6 +4,42 @@ from .utils import get_type
class InputField(MountedType):
"""
Makes a field available on an ObjectType in the GraphQL schema. Any type can be mounted as a
Input Field except Interface and Union:
- Object Type
- Scalar Type
- Enum
Input object types also can't have arguments on their input fields, unlike regular ``graphene.Field``.
All class attributes of ``graphene.InputObjectType`` are implicitly mounted as InputField
using the below arguments.
.. code:: python
class Person(graphene.InputObjectType):
first_name = graphene.String(required=True) # implicitly mounted as Input Field
last_name = graphene.InputField(String, description='Surname') # explicitly mounted as Input Field
args:
type (class for a graphene.UnmountedType): must be a class (not an instance) of an
unmounted graphene type (ex. scalar or object) which is used for the type of this
field in the GraphQL schema.
name (optional, str): the name of the GraphQL input field (must be unique in a type).
Defaults to attribute name.
default_value (optional, Any): Default value to use as input if none set in user operation (
query, mutation, etc.).
deprecation_reason (optional, str): Setting this value indicates that the field is
depreciated and may provide instruction or reason on how for clients to proceed.
description (optional, str): the description of the GraphQL field in the schema.
required (optional, bool). Indicates this input field as not null in the graphql scehma.
Raises a validation error if argument not provided. Same behavior as graphene.NonNull.
Default False.
**extra_args (optional, Dict): Not used.
"""
def __init__(
self,
type,

24
graphene/types/inputobjecttype.py
View File

@ -36,7 +36,29 @@ class InputObjectType(UnmountedType, BaseType):
An input object defines a structured collection of fields which may be
supplied to a field argument.
Using `NonNull` will ensure that a value must be provided by the query
Using ``graphene.NonNull`` will ensure that a input value must be provided by the query.
All class attributes of ``graphene.InputObjectType`` are implicitly mounted as InputField
using the below Meta class options.
.. code:: python
class Person(graphene.InputObjectType):
first_name = graphene.String(required=True) # implicitly mounted as Input Field
last_name = graphene.InputField(String, description='Surname') # explicitly mounted as Input Field
The fields on an input object type can themselves refer to input object types, but you can't
mix input and output types in your schema.
Meta class options (optional):
name (str): the name of the GraphQL type (must be unique in schema). Defaults to class
name.
description (str): the description of the GraphQL type in the schema. Defaults to class
docstring.
container (class): A class reference for a value object that allows for
attribute initialization and access. Default InputObjectTypeContainer.
fields (Dict[str, graphene.InputField]): Dictionary of field name to InputField. Not
recommended to use (prefer class attributes).
"""
@classmethod

20
graphene/types/interface.py
View File

@ -22,6 +22,26 @@ class Interface(BaseType):
is used to describe what types are possible, what fields are in common across
all types, as well as a function to determine which type is actually used
when the field is resolved.
.. code:: python
class HasAddress(graphene.Interface):
class Meta:
description = 'Address fields'
address1 = String()
address2 = String()
If a field returns an Interface Type, the ambiguous type of the object can be determined using
``resolve_type`` on Interface and an ObjectType with ``Meta.possible_types`` or ``is_type_of``.
Meta:
name (str): the name of the GraphQL type (must be unique in schema). Defaults to class
name.
description (str): the description of the GraphQL type in the schema. Defaults to class
docstring.
fields (Dict[str, graphene.Field]): dictionary of field name to Field. Not recommended to
use (prefer class attributes).
"""
@classmethod

7
graphene/types/json.py
View File

@ -8,7 +8,12 @@ from .scalars import Scalar
class JSONString(Scalar):
"""JSON String"""
"""
Allows use of a JSON String for input / output from the GraphQL schema.
Use of this type is *not recommended* as you lose the benefits of having a defined, static
schema (one of the key benefits of GraphQL).
"""
@staticmethod
def serialize(dt):

40
graphene/types/mutation.py
View File

@ -22,7 +22,44 @@ class MutationOptions(ObjectTypeOptions):
class Mutation(ObjectType):
"""
Mutation Type Definition
Object Type Definition (mutation field)
Mutation is a convenience type that helps us build a Field which takes Arguments and returns a
mutation Output ObjectType.
.. code:: python
class CreatePerson(graphene.Mutation):
class Arguments:
name = graphene.String()
ok = graphene.Boolean()
person = graphene.Field(Person)
def mutate(parent, info, name):
person = Person(name=name)
ok = True
return CreatePerson(person=person, ok=ok)
class Mutation(graphene.ObjectType):
create_person = CreatePerson.Field()
Meta class options (optional):
output (graphene.ObjectType): Or ``Output`` inner class with attributes on Mutation class.
Or attributes from Mutation class. Fields which can be returned from this mutation
field.
resolver (Callable resolver method): Or ``mutate`` method on Mutation class. Perform data
change and return output.
arguments (Dict[str, graphene.Argument]): Or ``Arguments`` inner class with attributes on
Mutation class. Arguments to use for the mutation Field.
name (str): the name of the GraphQL type (must be unique in schema). Defaults to class
name.
description (str): the description of the GraphQL type in the schema. Defaults to class
docstring.
interfaces (Iterable[graphene.Interface]): GraphQL interfaces to extend with the payload
object. All fields from interface will be included in this object's schema.
fields (Dict[str, graphene.Field]): dictionary of field name to Field. Not recommended to
use (prefer class attributes or ``Meta.output``).
"""
@classmethod
@ -80,6 +117,7 @@ class Mutation(ObjectType):
def Field(
cls, name=None, description=None, deprecation_reason=None, required=False
):
""" Mount instance of mutation Field. """
return Field(
cls._meta.output,
args=cls._meta.arguments,

56
graphene/types/objecttype.py
View File

@ -22,6 +22,62 @@ class ObjectType(BaseType):
Almost all of the GraphQL types you define will be object types. Object types
have a name, but most importantly describe their fields.
The name of the type defined by an _ObjectType_ defaults to the class name. The type
description defaults to the class docstring. This can be overriden by adding attributes
to a Meta inner class.
The class attributes of an _ObjectType_ are mounted as instances of ``graphene.Field``.
Methods starting with ``resolve_<field_name>`` are bound as resolvers of the matching Field
name. If no resolver is provided, the default resolver is used.
Ambiguous types with Interface and Union can be determined through``is_type_of`` method and
``Meta.possible_types`` attribute.
.. code:: python
class Person(ObjectType):
class Meta:
description = 'A human'
first_name = graphene.String() # implicitly mounted as Field
last_name = graphene.Field(String) # explicitly mounted as Field
def resolve_last_name(parent, info):
return last_name
ObjectType must be mounted using ``graphene.Field``.
.. code:: python
graphene.Feild(Person, description='My favorite person')``.
Meta class options (optional):
name (str): the name of the GraphQL type (must be unique in schema). Defaults to class
name.
description (str): the description of the GraphQL type in the schema. Defaults to class
docstring.
interfaces (Iterable[graphene.Interface]): GraphQL interfaces to extend with this object.
all fields from interface will be included in this object's schema.
possible_types (Iterable[class]): used to test parent value object via isintance to see if
this type can be used to resolve an ambigous type (interface, union).
default_resolver (any Callable resolver): Override the default resolver for this
type. Defaults to graphene default resolver which returns an attribute or dictionary
key with the same name as the field.
fields (Dict[str, graphene.Field]): dictionary of field name to Field. Not recommended to
use (prefer class attributes).
An _ObjectType_ can be used as a simple value object by creating an instance of the class.
.. code:: python
p = Person(first_name='Bob', last_name='Roberts')
assert p.first_name == 'Bob'
Args:
*args (List[Any]): positional values to use for Field values of value object
**kwargs (Dict[str: Any]): keyword arguments to use for Field values of value object
"""
@classmethod

14
graphene/types/structures.py
View File

@ -39,6 +39,12 @@ class List(Structure):
A list is a kind of type marker, a wrapping type which points to another
type. Lists are often created within the context of defining the fields of
an object type.
List indicates that many values will be returned (or input) for this field.
.. code:: python
field_name = graphene.List(graphene.String, description='There will be many values')
"""
def __str__(self):
@ -63,6 +69,14 @@ class NonNull(Structure):
usually the id field of a database row will never be null.
Note: the enforcement of non-nullability occurs within the executor.
NonNull can also be indicated on all Mounted types with the argument ``required``.
.. code:: python
field_name = graphene.NonNull(graphene.String, description='This field will not be null')
another_field = graphene.String(required=True, description='This is equivalent to the above')
"""
def __init__(self, *args, **kwargs):

26
graphene/types/union.py
View File

@ -19,6 +19,32 @@ class Union(UnmountedType, BaseType):
When a field can return one of a heterogeneous set of types, a Union type
is used to describe what types are possible as well as providing a function
to determine which type is actually used when the field is resolved.
The schema in this example can take a search text and return any of the GraphQL object types
indicated: Human, Droid or Startship.
Ambigous return types can be resolved on each ObjectType through ``Meta.possible_types``
attribute or ``is_type_of`` method. Or by implementing ``resolve_type`` class method on the
Union.
.. code:: python
class SearchResult(graphene.Union):
class Meta:
types = (Human, Droid, Starship)
class Query(graphene.ObjectType):
search = graphene.List(SearchResult.Field(
search_text=String(description='Value to search for'))
)
Meta:
types (Iterable[graphene.ObjectType)]: Required. Collection of types that may be returned
by this Union for the graphQL schema.
name (optional, str): the name of the GraphQL type (must be unique in schema). Defaults to class
name.
description (optional, str): the description of the GraphQL type in the schema. Defaults to class
docstring.
"""
@classmethod

32
graphene/types/unmountedtype.py
View File

@ -6,13 +6,33 @@ class UnmountedType(OrderedType):
This class acts a proxy for a Graphene Type, so it can be mounted
dynamically as Field, InputField or Argument.
Instead of writing
>>> class MyObjectType(ObjectType):
>>> my_field = Field(String, description='Description here')
Instead of writing:
It let you write
>>> class MyObjectType(ObjectType):
>>> my_field = String(description='Description here')
.. code:: python
class MyObjectType(ObjectType):
my_field = Field(String, description='Description here')
It lets you write:
.. code:: python
class MyObjectType(ObjectType):
my_field = String(description='Description here')
It is not used directly, but is inherited by other types and streamlines their use in
different context:
- Object Type
- Scalar Type
- Enum
- Interface
- Union
An unmounted type will accept arguments based upon its context (ObjectType, Field or
InputObjectType) and pass it on to the appropriate MountedType (Field, Argument or InputField).
See each Mounted type reference for more information about valid parameters.
"""
def __init__(self, *args, **kwargs):

5
graphene/types/uuid.py
View File

@ -8,7 +8,10 @@ from .scalars import Scalar
class UUID(Scalar):
"""UUID"""
"""
Leverages the internal Python implmeentation of UUID (uuid.UUID) to provide native UUID objects
in fields, resolvers and input.
"""
@staticmethod
def serialize(uuid):