From 738461498fff589c2ab94303a82d9eebb890fc57 Mon Sep 17 00:00:00 2001 From: Dave A Date: Tue, 21 May 2019 23:15:48 -0400 Subject: [PATCH 01/15] expose livehtml autobuild in Makefile --- Makefile | 9 +++++---- docs/Makefile | 8 ++++++-- docs/requirements.txt | 1 + 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index c1a000542..a905f8315 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,8 @@ help: .PHONY: docs ## Generate docs docs: - @cd docs &&\ - pip install -r requirements.txt &&\ - make html &&\ - cd - + cd docs && make install && make html + +.PHONY: docs-live ## Generate docs with live reloading +docs-live: + cd docs && make install && make livehtml diff --git a/docs/Makefile b/docs/Makefile index 3eb7e6383..fbc765777 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -19,7 +19,11 @@ help: @echo "Please use \`make ' where is one of" @grep -E '^\.PHONY: [a-zA-Z_-]+ .*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = "(: |##)"}; {printf "\033[36m%-30s\033[0m %s\n", $$2, $$3}' -.PHONY: clean +.PHONY: install ## to install all documentation related requirements +install: + pip install -r requirements.txt + +.PHONY: clean ## to remove all built documentation clean: rm -rf $(BUILDDIR)/* @@ -199,6 +203,6 @@ dummy: @echo @echo "Build finished. Dummy builder generates no files." -.PHONY: livehtml +.PHONY: livehtml ## to build and serve live-reloading documentation livehtml: sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/requirements.txt b/docs/requirements.txt index b6e0cd759..e63ca5916 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ # Required library Sphinx==1.5.3 +sphinx-autobuild # Docs template http://graphene-python.org/sphinx_graphene_theme.zip From 79f84706ec55bd53b83156a055922242b9ad4496 Mon Sep 17 00:00:00 2001 From: Dave A Date: Sat, 25 May 2019 05:38:06 -0400 Subject: [PATCH 02/15] add API documentation for schema --- Makefile | 11 ++++- docs/Makefile | 2 +- docs/_static/.gitkeep | 0 docs/api/index.rst | 101 +++++++++++++++++++++++++++++++++++++++ docs/conf.py | 7 +-- docs/index.rst | 3 +- graphene/types/schema.py | 50 +++++++++++++++++-- 7 files changed, 163 insertions(+), 11 deletions(-) create mode 100644 docs/_static/.gitkeep create mode 100644 docs/api/index.rst diff --git a/Makefile b/Makefile index a905f8315..b4e6c928f 100644 --- a/Makefile +++ b/Makefile @@ -3,10 +3,17 @@ help: @echo "Please use \`make ' where is one of" @grep -E '^\.PHONY: [a-zA-Z_-]+ .*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = "(: |##)"}; {printf "\033[36m%-30s\033[0m %s\n", $$2, $$3}' +.PHONY: install-dev ## Install development dependencies +install-dev: + pip install -e ".[test]" + +test: + py.test graphene + .PHONY: docs ## Generate docs -docs: +docs: install-dev cd docs && make install && make html .PHONY: docs-live ## Generate docs with live reloading -docs-live: +docs-live: install-dev cd docs && make install && make livehtml diff --git a/docs/Makefile b/docs/Makefile index fbc765777..8753f2998 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -205,4 +205,4 @@ dummy: .PHONY: livehtml ## to build and serve live-reloading documentation livehtml: - sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + sphinx-autobuild -b html --watch ../graphene $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 000000000..86460918c --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,101 @@ +API Reference +============= + +Schema +------ + +.. autoclass:: graphene.types.schema.Schema + :members: + +.. Uncomment sections / types as API documentation is fleshed out +.. in each class + +.. Object types +.. ------------ + +.. .. autoclass:: graphene.ObjectType + +.. .. autoclass:: graphene.InputObjectType + +.. Fields (Mounted Types) +.. ---------------------- + +.. .. autoclass:: graphene.Field + +.. .. autoclass:: graphene.Argument + +.. .. autoclass:: graphene.InputField + +.. GraphQL Scalars +.. --------------- + +.. .. autoclass:: graphene.Int + +.. .. autoclass:: graphene.Float + +.. .. autoclass:: graphene.String + +.. .. autoclass:: graphene.Boolean + +.. .. autoclass:: graphene.ID + +.. Graphene Scalars +.. ---------------- + +.. .. autoclass:: graphene.Date + +.. .. autoclass:: graphene.DateTime + +.. .. autoclass:: graphene.Time + +.. .. autoclass:: graphene.Decimal + +.. .. autoclass:: graphene.UUID + +.. .. autoclass:: graphene.JSONString + +.. Structures +.. ---------- + +.. .. autoclass:: graphene.List + +.. .. autoclass:: graphene.NonNull + +.. Enum +.. ---- + +.. .. autoclass:: graphene.Enum + +.. Type Extension +.. -------------- + +.. .. autoclass:: graphene.Interface + +.. .. autoclass:: graphene.Union + +.. Execution Metadata +.. ------------------ + +.. .. autoclass:: graphene.ResolveInfo + +.. .. autoclass:: graphene.Context + +.. Mutation +.. -------- + +.. .. autoclass:: graphene.Mutation + +.. Relay +.. ----- + +.. .. autoclass:: graphene.Node + +.. .. autoclass:: graphene.GlobalID + +.. .. autoclass:: graphene.ClientIDMutation + +.. .. autoclass:: graphene.Connection + +.. .. autoclass:: graphene.ConnectionField + +.. .. autoclass:: graphene.PageInfo diff --git a/docs/conf.py b/docs/conf.py index c7927ec28..b67e3a215 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,9 +22,9 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('..')) # -- General configuration ------------------------------------------------ @@ -41,6 +41,7 @@ "sphinx.ext.todo", "sphinx.ext.coverage", "sphinx.ext.viewcode", + "sphinx.ext.napoleon", ] if not on_rtd: extensions += ["sphinx.ext.githubpages"] diff --git a/docs/index.rst b/docs/index.rst index aff3960f5..eb78f902b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,9 +11,10 @@ Contents: execution/index relay/index testing/index + api/index Integrations ------ +------------ * `Graphene-Django `_ (`source `_) * `Graphene-SQLAlchemy `_ (`source `_) diff --git a/graphene/types/schema.py b/graphene/types/schema.py index a885c88a6..07c25763c 100644 --- a/graphene/types/schema.py +++ b/graphene/types/schema.py @@ -27,10 +27,26 @@ def assert_valid_root_type(_type): class Schema(GraphQLSchema): """ - Schema Definition - - A Schema is created by supplying the root types of each type of operation, - query and mutation (optional). + Graphene Schema can execute operations (query, mutation, subscription) against the defined + types. + + For advanced purposes, the schema can be used to lookup type definitions and answer questions + about the types through introspection. + + Args: + query (ObjectType): Root query *ObjectType*. Describes entry point for fields to *read* + data in your Schema. + mutation (ObjectType, optional): Root mutation *ObjectType*. Describes entry point for + fields to *create, update or delete* data in your API. + subscription (ObjectType, optional): Root subscription *ObjectType*. Describes entry point + for fields to receive continuous updates. + directives (List[GraphQLDirective], optional): List of custom directives to include in + GraphQL schema. Defaults to only include directives definved by GraphQL spec (@include + and @skip) [GraphQLIncludeDirective, GraphQLSkipDirective]. + types (List[GraphQLType], optional): List of any types to include in schema that + may not be introspected through root types. + auto_camelcase (bool): Fieldnames will be transformed in Schema's TypeMap from snake_case + to camelCase (preferred by GraphQL standard). Default True. """ def __init__( @@ -99,6 +115,32 @@ def get_graphql_type(self, _type): raise Exception("{} is not a valid GraphQL type.".format(_type)) def execute(self, *args, **kwargs): + """ + Use the `graphql` function from `graphql-core` to provide the result for a query string. + Most of the time this method will be called by one of the Graphene :ref:`Integrations` + via a web request. + + Args: + request_string (str or Document): GraphQL request (query, mutation or subscription) in + string or parsed AST form from `graphql-core`. + root (Any, optional): Value to use as the parent value object when resolving root + types. + context (Any, optional): Value to be made avaiable to all resolvers via + `info.context`. Can be used to share authorization, dataloaders or other + information needed to resolve an operation. + variables (dict, optional): If variables are used in the request string, they can be + provided in dictionary form mapping the variable name to the variable value. + operation_name (str, optional): If mutiple operations are provided in the + request_string, an operation name must be provided for the result to be provided. + middleware (List[SupportsGraphQLMiddleware]): Supply request level middleware as + defined in `graphql-core`. + backend (GraphQLCoreBackend, optional): Override the default GraphQLCoreBackend. + **execute_options (Any): Depends on backend selected. Default backend has several + options such as: validate, allow_subscriptions, return_promise, executor. + + Returns: + :obj:`ExecutionResult` containing any data and errors for the operation. + """ return graphql(self, *args, **kwargs) def introspect(self): From 882d18e245439bd4851673f181d83c03e34785a8 Mon Sep 17 00:00:00 2001 From: Dave A Date: Sat, 25 May 2019 15:45:54 -0400 Subject: [PATCH 03/15] document graphene core API --- docs/api/index.rst | 89 ++++++++++++++++--------------- graphene/types/argument.py | 29 ++++++++++ graphene/types/context.py | 19 +++++++ graphene/types/enum.py | 22 ++++++++ graphene/types/field.py | 41 ++++++++++++++ graphene/types/inputfield.py | 36 +++++++++++++ graphene/types/inputobjecttype.py | 24 ++++++++- graphene/types/interface.py | 20 +++++++ graphene/types/json.py | 7 ++- graphene/types/mutation.py | 40 +++++++++++++- graphene/types/objecttype.py | 56 +++++++++++++++++++ graphene/types/structures.py | 14 +++++ graphene/types/union.py | 26 +++++++++ graphene/types/unmountedtype.py | 32 ++++++++--- graphene/types/uuid.py | 5 +- 15 files changed, 408 insertions(+), 52 deletions(-) diff --git a/docs/api/index.rst b/docs/api/index.rst index 86460918c..47b8b84f5 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -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: + +Fields (Mounted Types) +---------------------- + +.. autoclass:: graphene.Field -.. .. autoclass:: graphene.Field +.. autoclass:: graphene.Argument -.. .. autoclass:: graphene.Argument +.. autoclass:: graphene.InputField -.. .. autoclass:: graphene.InputField +Fields (Unmounted Types) +------------------------ -.. GraphQL Scalars -.. --------------- +.. autoclass:: graphene.types.unmountedtype.UnmountedType -.. .. autoclass:: graphene.Int +GraphQL Scalars +--------------- -.. .. autoclass:: graphene.Float +.. autoclass:: graphene.Int() -.. .. autoclass:: graphene.String +.. autoclass:: graphene.Float() -.. .. autoclass:: graphene.Boolean +.. autoclass:: graphene.String() -.. .. autoclass:: graphene.ID +.. autoclass:: graphene.Boolean() -.. Graphene Scalars -.. ---------------- +.. autoclass:: graphene.ID() -.. .. autoclass:: graphene.Date +Graphene Scalars +---------------- -.. .. autoclass:: graphene.DateTime +.. autoclass:: graphene.Date() -.. .. autoclass:: graphene.Time +.. autoclass:: graphene.DateTime() -.. .. autoclass:: graphene.Decimal +.. autoclass:: graphene.Time() -.. .. autoclass:: graphene.UUID +.. autoclass:: graphene.Decimal() -.. .. autoclass:: graphene.JSONString +.. autoclass:: graphene.UUID() -.. Structures -.. ---------- +.. autoclass:: graphene.JSONString() -.. .. autoclass:: graphene.List +Enum +---- -.. .. autoclass:: graphene.NonNull +.. autoclass:: graphene.Enum() -.. Enum -.. ---- +Structures +---------- -.. .. autoclass:: graphene.Enum +.. autoclass:: graphene.List -.. Type Extension -.. -------------- +.. autoclass:: graphene.NonNull -.. .. autoclass:: graphene.Interface +Type Extension +-------------- -.. .. autoclass:: graphene.Union +.. autoclass:: graphene.Interface() -.. Execution Metadata -.. ------------------ +.. autoclass:: graphene.Union() -.. .. autoclass:: graphene.ResolveInfo +Execution Metadata +------------------ -.. .. autoclass:: graphene.Context +.. autoclass:: graphene.ResolveInfo -.. Mutation -.. -------- +.. autoclass:: graphene.Context -.. .. autoclass:: graphene.Mutation +.. autoclass:: graphql.execution.base.ExecutionResult .. Relay .. ----- diff --git a/graphene/types/argument.py b/graphene/types/argument.py index bf3046082..67af1d986 100644 --- a/graphene/types/argument.py +++ b/graphene/types/argument.py @@ -8,6 +8,35 @@ 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, diff --git a/graphene/types/context.py b/graphene/types/context.py index bac2073c5..d7be7ac99 100644 --- a/graphene/types/context.py +++ b/graphene/types/context.py @@ -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) diff --git a/graphene/types/enum.py b/graphene/types/enum.py index 7b8e71f52..418885059 100644 --- a/graphene/types/enum.py +++ b/graphene/types/enum.py @@ -67,6 +67,28 @@ def from_enum(cls, enum, description=None, deprecation_reason=None): # noqa: N8 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: diff --git a/graphene/types/field.py b/graphene/types/field.py index a14286328..f9275da00 100644 --- a/graphene/types/field.py +++ b/graphene/types/field.py @@ -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, diff --git a/graphene/types/inputfield.py b/graphene/types/inputfield.py index cdfea1144..43405b4bb 100644 --- a/graphene/types/inputfield.py +++ b/graphene/types/inputfield.py @@ -4,6 +4,42 @@ 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, diff --git a/graphene/types/inputobjecttype.py b/graphene/types/inputobjecttype.py index 8116a8274..1d3e99d85 100644 --- a/graphene/types/inputobjecttype.py +++ b/graphene/types/inputobjecttype.py @@ -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 diff --git a/graphene/types/interface.py b/graphene/types/interface.py index f2c9749c4..2148259b3 100644 --- a/graphene/types/interface.py +++ b/graphene/types/interface.py @@ -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 diff --git a/graphene/types/json.py b/graphene/types/json.py index 495943a92..6b87ae6e1 100644 --- a/graphene/types/json.py +++ b/graphene/types/json.py @@ -8,7 +8,12 @@ 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): diff --git a/graphene/types/mutation.py b/graphene/types/mutation.py index dd09e4614..372daeecf 100644 --- a/graphene/types/mutation.py +++ b/graphene/types/mutation.py @@ -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 @@ def __init_subclass_with_meta__( 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, diff --git a/graphene/types/objecttype.py b/graphene/types/objecttype.py index be4addb26..1017cb8ef 100644 --- a/graphene/types/objecttype.py +++ b/graphene/types/objecttype.py @@ -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_`` 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 diff --git a/graphene/types/structures.py b/graphene/types/structures.py index dde68f0f4..44012aed3 100644 --- a/graphene/types/structures.py +++ b/graphene/types/structures.py @@ -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): diff --git a/graphene/types/union.py b/graphene/types/union.py index dc207e8ea..e05d78820 100644 --- a/graphene/types/union.py +++ b/graphene/types/union.py @@ -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 diff --git a/graphene/types/unmountedtype.py b/graphene/types/unmountedtype.py index 5bcdab55f..dd2045ef6 100644 --- a/graphene/types/unmountedtype.py +++ b/graphene/types/unmountedtype.py @@ -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): diff --git a/graphene/types/uuid.py b/graphene/types/uuid.py index b9687e1e2..0628200b7 100644 --- a/graphene/types/uuid.py +++ b/graphene/types/uuid.py @@ -8,7 +8,10 @@ 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): From 1184f07071564ef2334fef9dc27cc9e859d2b1c1 Mon Sep 17 00:00:00 2001 From: Dave A Date: Sat, 25 May 2019 16:35:40 -0400 Subject: [PATCH 04/15] fixes black lint --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index b67e3a215..26becbc22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,7 +24,8 @@ # import os import sys -sys.path.insert(0, os.path.abspath('..')) + +sys.path.insert(0, os.path.abspath("..")) # -- General configuration ------------------------------------------------ From 07b87c50708ba8216a89693db3ce9f8935c5995a Mon Sep 17 00:00:00 2001 From: David Anderson Date: Tue, 4 Jun 2019 07:59:25 -0400 Subject: [PATCH 05/15] Update graphene/types/union.py Co-Authored-By: Jonathan Kim --- graphene/types/union.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graphene/types/union.py b/graphene/types/union.py index e05d78820..38e4a0a8b 100644 --- a/graphene/types/union.py +++ b/graphene/types/union.py @@ -39,7 +39,7 @@ class Query(graphene.ObjectType): ) Meta: - types (Iterable[graphene.ObjectType)]: Required. Collection of types that may be returned + 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. From f8a6aa201b45a1f53baf616ec741f9bad72607c4 Mon Sep 17 00:00:00 2001 From: David Anderson Date: Tue, 4 Jun 2019 17:50:36 -0400 Subject: [PATCH 06/15] Update graphene/types/argument.py Co-Authored-By: Jonathan Kim --- graphene/types/argument.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graphene/types/argument.py b/graphene/types/argument.py index 67af1d986..7dc7d179f 100644 --- a/graphene/types/argument.py +++ b/graphene/types/argument.py @@ -29,7 +29,7 @@ class Argument(MountedType): 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 + 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. From 2b01a8ece2693a5a004f4f7c8ae7822e488c8cbc Mon Sep 17 00:00:00 2001 From: David Anderson Date: Tue, 4 Jun 2019 17:52:06 -0400 Subject: [PATCH 07/15] Update graphene/types/field.py Co-Authored-By: Jonathan Kim --- graphene/types/field.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graphene/types/field.py b/graphene/types/field.py index f9275da00..7f63a8535 100644 --- a/graphene/types/field.py +++ b/graphene/types/field.py @@ -50,7 +50,7 @@ class Person(ObjectType): 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 + 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. From 0bd4d93288be1e92eaad2ffe65f04dc83354cdea Mon Sep 17 00:00:00 2001 From: David Anderson Date: Tue, 4 Jun 2019 17:52:27 -0400 Subject: [PATCH 08/15] Update graphene/types/inputfield.py Co-Authored-By: Jonathan Kim --- graphene/types/inputfield.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/graphene/types/inputfield.py b/graphene/types/inputfield.py index 43405b4bb..c53aa26a6 100644 --- a/graphene/types/inputfield.py +++ b/graphene/types/inputfield.py @@ -34,7 +34,7 @@ class Person(graphene.InputObjectType): 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. + 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. From e141e43a6f3245c2b0b9519c8fbcee3f1c1a4066 Mon Sep 17 00:00:00 2001 From: Dave A Date: Tue, 4 Jun 2019 19:00:18 -0400 Subject: [PATCH 09/15] add note about non-functional `interfaces` meta argument in mutation --- graphene/types/mutation.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/graphene/types/mutation.py b/graphene/types/mutation.py index 372daeecf..9c7355c96 100644 --- a/graphene/types/mutation.py +++ b/graphene/types/mutation.py @@ -56,7 +56,8 @@ class Mutation(graphene.ObjectType): 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 + interfaces (Iterable[graphene.Interface]): NOT IMPLEMENTED (use ``output`` to define a + payload implementing interfaces). 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``). From 67f6976cc105c2c6b05bb6231a059d0989e2db5f Mon Sep 17 00:00:00 2001 From: Dave A Date: Tue, 4 Jun 2019 19:34:45 -0400 Subject: [PATCH 10/15] update with other virtual environment configuration --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index 0e3fcd9ed..77ac057a5 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,8 @@ __pycache__/ # Distribution / packaging .Python env/ +venv/ +.venv/ build/ develop-eggs/ dist/ From 17e57e737383e010fb2adee9fb33585ca4f65f04 Mon Sep 17 00:00:00 2001 From: Dave A Date: Sun, 9 Jun 2019 08:50:40 -0400 Subject: [PATCH 11/15] pin autobuild --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index e63ca5916..dcc403123 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ # Required library Sphinx==1.5.3 -sphinx-autobuild +sphinx-autobuild==0.7.1 # Docs template http://graphene-python.org/sphinx_graphene_theme.zip From 42bfb37d26c50630542b0cadfba277379f0d9c0e Mon Sep 17 00:00:00 2001 From: Dave A Date: Sun, 9 Jun 2019 09:16:52 -0400 Subject: [PATCH 12/15] format argument example code --- graphene/types/argument.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/graphene/types/argument.py b/graphene/types/argument.py index 7dc7d179f..cb72322ce 100644 --- a/graphene/types/argument.py +++ b/graphene/types/argument.py @@ -18,11 +18,13 @@ class Argument(MountedType): .. code:: python - age = graphene.String( + from graphene import String, Boolean, Argument + + age = String( # Boolean implicitly mounted as Argument - dog_years=graphene.Boolean(description='convert to dog years'), + dog_years=Boolean(description="convert to dog years"), # Boolean explicitly mounted as Argument - decades=graphene.Argument(graphene.Boolean, default_value=False) + decades=Argument(Boolean, default_value=False), ) args: From e761d2562f0e40c283cf82e072e74aff7a5ebfd4 Mon Sep 17 00:00:00 2001 From: Dave A Date: Sun, 9 Jun 2019 09:25:08 -0400 Subject: [PATCH 13/15] format enum input object and interface examples --- graphene/types/enum.py | 8 +++++--- graphene/types/inputobjecttype.py | 10 +++++++--- graphene/types/interface.py | 6 ++++-- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/graphene/types/enum.py b/graphene/types/enum.py index 418885059..5a21e32fc 100644 --- a/graphene/types/enum.py +++ b/graphene/types/enum.py @@ -74,9 +74,11 @@ class Enum(six.with_metaclass(EnumMeta, UnmountedType, BaseType)): .. code:: python - class NameFormat(graphene.Enum): - FIRST_LAST = 'first_last' - LAST_FIRST = 'last_first' + from graphene import Enum + + class NameFormat(Enum): + FIRST_LAST = "first_last" + LAST_FIRST = "last_first" Meta: enum (optional, Enum): Python enum to use as a base for GraphQL Enum. diff --git a/graphene/types/inputobjecttype.py b/graphene/types/inputobjecttype.py index 1d3e99d85..d13689313 100644 --- a/graphene/types/inputobjecttype.py +++ b/graphene/types/inputobjecttype.py @@ -43,9 +43,13 @@ class InputObjectType(UnmountedType, BaseType): .. 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 + from graphene import InputObjectType, String, InputField + + class Person(InputObjectType): + # implicitly mounted as Input Field + first_name = String(required=True) + # explicitly mounted as Input Field + last_name = InputField(String, description="Surname") 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. diff --git a/graphene/types/interface.py b/graphene/types/interface.py index 2148259b3..bb9cf13e9 100644 --- a/graphene/types/interface.py +++ b/graphene/types/interface.py @@ -25,9 +25,11 @@ class Interface(BaseType): .. code:: python - class HasAddress(graphene.Interface): + from graphene import Interface, String + + class HasAddress(Interface): class Meta: - description = 'Address fields' + description = "Address fields" address1 = String() address2 = String() From 37d32de39f571bb19e270c68e563173910aa41be Mon Sep 17 00:00:00 2001 From: Dave A Date: Sun, 9 Jun 2019 09:32:49 -0400 Subject: [PATCH 14/15] format enum mutation union examples --- graphene/types/enum.py | 6 +++--- graphene/types/mutation.py | 10 ++++++---- graphene/types/union.py | 8 +++++--- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/graphene/types/enum.py b/graphene/types/enum.py index 5a21e32fc..8c95efbe6 100644 --- a/graphene/types/enum.py +++ b/graphene/types/enum.py @@ -68,7 +68,7 @@ def from_enum(cls, enum, description=None, deprecation_reason=None): # noqa: N8 class Enum(six.with_metaclass(EnumMeta, UnmountedType, BaseType)): """ - Enum type defintion + Enum type definition Defines a static set of values that can be provided as a Field, Argument or InputField. @@ -83,9 +83,9 @@ class NameFormat(Enum): 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 (optional, str): 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 + description (optional, str): 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. diff --git a/graphene/types/mutation.py b/graphene/types/mutation.py index 9c7355c96..b238ba144 100644 --- a/graphene/types/mutation.py +++ b/graphene/types/mutation.py @@ -29,12 +29,14 @@ class Mutation(ObjectType): .. code:: python - class CreatePerson(graphene.Mutation): + from graphene import Mutation, String, Boolean, Field + + class CreatePerson(Mutation): class Arguments: - name = graphene.String() + name = String() - ok = graphene.Boolean() - person = graphene.Field(Person) + ok = Boolean() + person = Field(Person) def mutate(parent, info, name): person = Person(name=name) diff --git a/graphene/types/union.py b/graphene/types/union.py index 38e4a0a8b..194ba1da7 100644 --- a/graphene/types/union.py +++ b/graphene/types/union.py @@ -29,12 +29,14 @@ class Union(UnmountedType, BaseType): .. code:: python - class SearchResult(graphene.Union): + from graphene import Union, ObjectType, List + + class SearchResult(Union): class Meta: types = (Human, Droid, Starship) - class Query(graphene.ObjectType): - search = graphene.List(SearchResult.Field( + class Query(ObjectType): + search = List(SearchResult.Field( search_text=String(description='Value to search for')) ) From 125ef518364c2367e633a131ca39729f1d4a525a Mon Sep 17 00:00:00 2001 From: Dave A Date: Sun, 9 Jun 2019 09:50:10 -0400 Subject: [PATCH 15/15] revise documentation with imports, capitalization --- graphene/types/context.py | 2 ++ graphene/types/inputfield.py | 18 +++++++++++------- graphene/types/interface.py | 6 +++--- graphene/types/mutation.py | 10 +++++----- graphene/types/objecttype.py | 26 +++++++++++++++++--------- graphene/types/structures.py | 12 ++++++++---- graphene/types/unmountedtype.py | 4 ++++ 7 files changed, 50 insertions(+), 28 deletions(-) diff --git a/graphene/types/context.py b/graphene/types/context.py index d7be7ac99..70b1a5b26 100644 --- a/graphene/types/context.py +++ b/graphene/types/context.py @@ -5,6 +5,8 @@ class Context(object): .. code:: python + from graphene import Context + context = Context(loaders=build_dataloaders(), request=my_web_request) schema.execute('{ hello(name: "world") }', context=context) diff --git a/graphene/types/inputfield.py b/graphene/types/inputfield.py index c53aa26a6..ed9b96ab0 100644 --- a/graphene/types/inputfield.py +++ b/graphene/types/inputfield.py @@ -19,22 +19,26 @@ class InputField(MountedType): .. 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 + from graphene import InputObjectType, String, InputField + + class Person(InputObjectType): + # implicitly mounted as Input Field + first_name = String(required=True) + # explicitly mounted as Input Field + last_name = InputField(String, description="Surname") args: - type (class for a graphene.UnmountedType): must be a class (not an instance) of an + 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). + name (optional, str): 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. + description (optional, str): 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. diff --git a/graphene/types/interface.py b/graphene/types/interface.py index bb9cf13e9..59184a1f0 100644 --- a/graphene/types/interface.py +++ b/graphene/types/interface.py @@ -38,11 +38,11 @@ class Meta: ``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 (str): 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 + description (str): 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 + fields (Dict[str, graphene.Field]): Dictionary of field name to Field. Not recommended to use (prefer class attributes). """ diff --git a/graphene/types/mutation.py b/graphene/types/mutation.py index b238ba144..504d8470c 100644 --- a/graphene/types/mutation.py +++ b/graphene/types/mutation.py @@ -29,7 +29,7 @@ class Mutation(ObjectType): .. code:: python - from graphene import Mutation, String, Boolean, Field + from graphene import Mutation, ObjectType, String, Boolean, Field class CreatePerson(Mutation): class Arguments: @@ -43,7 +43,7 @@ def mutate(parent, info, name): ok = True return CreatePerson(person=person, ok=ok) - class Mutation(graphene.ObjectType): + class Mutation(ObjectType): create_person = CreatePerson.Field() Meta class options (optional): @@ -54,14 +54,14 @@ class Mutation(graphene.ObjectType): 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 (str): 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 + description (str): Description of the GraphQL type in the schema. Defaults to class docstring. interfaces (Iterable[graphene.Interface]): NOT IMPLEMENTED (use ``output`` to define a payload implementing interfaces). 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 + fields (Dict[str, graphene.Field]): Dictionary of field name to Field. Not recommended to use (prefer class attributes or ``Meta.output``). """ diff --git a/graphene/types/objecttype.py b/graphene/types/objecttype.py index 1017cb8ef..edd687c58 100644 --- a/graphene/types/objecttype.py +++ b/graphene/types/objecttype.py @@ -37,12 +37,16 @@ class ObjectType(BaseType): .. code:: python + from graphene import ObjectType, String, Field + 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 + # implicitly mounted as Field + first_name = String() + # explicitly mounted as Field + last_name = Field(String) def resolve_last_name(parent, info): return last_name @@ -51,21 +55,25 @@ def resolve_last_name(parent, info): .. code:: python - graphene.Feild(Person, description='My favorite person')``. + from graphene import ObjectType, Field + + class Query(ObjectType): + + person = Field(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 (str): 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 + description (str): 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 + 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 + 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. @@ -76,8 +84,8 @@ def resolve_last_name(parent, info): 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 + *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 diff --git a/graphene/types/structures.py b/graphene/types/structures.py index 44012aed3..3341e0227 100644 --- a/graphene/types/structures.py +++ b/graphene/types/structures.py @@ -44,7 +44,9 @@ class List(Structure): .. code:: python - field_name = graphene.List(graphene.String, description='There will be many values') + from graphene import List, String + + field_name = List(String, description="There will be many values") """ def __str__(self): @@ -70,12 +72,14 @@ class NonNull(Structure): Note: the enforcement of non-nullability occurs within the executor. - NonNull can also be indicated on all Mounted types with the argument ``required``. + NonNull can also be indicated on all Mounted types with the keyword 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') + from graphene import NonNull, String + + field_name = NonNull(String, description='This field will not be null') + another_field = String(required=True, description='This is equivalent to the above') """ diff --git a/graphene/types/unmountedtype.py b/graphene/types/unmountedtype.py index dd2045ef6..081c4ba00 100644 --- a/graphene/types/unmountedtype.py +++ b/graphene/types/unmountedtype.py @@ -10,6 +10,8 @@ class UnmountedType(OrderedType): .. code:: python + from graphene import ObjectType, Field, String + class MyObjectType(ObjectType): my_field = Field(String, description='Description here') @@ -17,6 +19,8 @@ class MyObjectType(ObjectType): .. code:: python + from graphene import ObjectType, String + class MyObjectType(ObjectType): my_field = String(description='Description here')