Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1061,4 +1061,61 @@ Similarly, we can use the ``graphlayer.sqlalchemy`` module to define the resolve
},
)

Schema documentation
---------------------

GraphQL schemas built with GraphLayer can carry descriptions, which are exposed through
introspection and shown by tools such as GraphiQL once the schema is converted to a
``graphql-core`` schema via ``graphlayer.graphql.create_graphql_schema`` (or
``graphlayer.graphql.execute``/``executor``, which use it internally).

Pass ``description`` when defining a type or field:

.. code-block:: python

Season = g.EnumType(SeasonEnum, description="The four meteorological seasons.")

Book = g.ObjectType(
"Book",
description="A published book.",
fields=lambda: (
g.field(
"title",
type=g.String,
description="The book's title.",
),
g.field(
"editions",
type=g.ListType(Edition),
description="The editions of this book, newest first.",
params=(
g.param(
"limit",
type=g.Int,
default=None,
description="The maximum number of editions to return.",
),
),
),
),
)

``description`` is accepted by:

* ``g.ObjectType``
* ``g.InterfaceType``
* ``g.InputObjectType``
* ``g.EnumType``
* ``g.field``
* ``g.param``
* ``g.input_field``

The built-in scalar types (``g.Boolean``, ``g.Float``, ``g.Int``, ``g.String``) always use the
fixed descriptions mandated by the GraphQL specification and don't accept a ``description``
argument, since they map directly onto ``graphql-core``'s standard scalar types rather than a
type defined per-schema. GraphLayer doesn't currently support defining custom scalar types.

Descriptions have no effect outside of GraphQL schema generation; they're ignored by GraphLayer's
own query resolution.


14 changes: 11 additions & 3 deletions graphlayer/graphql/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,11 @@ def generate_graphql_type(graph_type):
(member.value, graphql.GraphQLEnumValue(member.value))
for member in graph_type.enum
)
graphql_type = graphql.GraphQLEnumType(graph_type.name, values=values)
graphql_type = graphql.GraphQLEnumType(
graph_type.name,
values=values,
description=graph_type.description,
)
return graphql.GraphQLNonNull(graphql_type)

elif isinstance(graph_type, schema.InputObjectType):
Expand All @@ -51,13 +55,15 @@ def generate_graphql_type(graph_type):
(snake_case_to_camel_case(field.name), to_graphql_input_field(field))
for field in graph_type.fields
),
description=graph_type.description,
))

elif isinstance(graph_type, schema.InterfaceType):
return graphql.GraphQLNonNull(graphql.GraphQLInterfaceType(
name=graph_type.name,
fields=to_graphql_fields(graph_type.fields),
resolve_type=lambda: None,
description=graph_type.description,
))

elif isinstance(graph_type, schema.ListType):
Expand All @@ -74,6 +80,7 @@ def generate_graphql_type(graph_type):
to_graphql_type(interface).of_type
for interface in graph_type.interfaces
),
description=graph_type.description,
))

else:
Expand All @@ -85,7 +92,7 @@ def to_graphql_input_field(graph_field):
if graph_field.has_default and isinstance(graphql_type, graphql.GraphQLNonNull):
graphql_type = graphql_type.of_type

return graphql.GraphQLInputField(type_=graphql_type)
return graphql.GraphQLInputField(type_=graphql_type, description=graph_field.description)
Comment thread
rnsmith marked this conversation as resolved.
Resolved

def to_graphql_fields(graph_fields):
return lambda: iterables.to_dict(
Expand All @@ -100,6 +107,7 @@ def to_graphql_field(graph_field):
(snake_case_to_camel_case(param.name), to_graphql_argument(param))
for param in graph_field.params
),
description=graph_field.description,
)

def to_graphql_argument(param):
Expand All @@ -108,7 +116,7 @@ def to_graphql_argument(param):
if param.has_default and isinstance(graphql_type, graphql.GraphQLNonNull):
graphql_type = graphql_type.of_type

return graphql.GraphQLArgument(type_=graphql_type)
return graphql.GraphQLArgument(type_=graphql_type, description=param.description)

graphql_query_type = to_graphql_type(query_type).of_type
if mutation_type is None:
Expand Down
41 changes: 27 additions & 14 deletions graphlayer/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,9 @@ def __str__(self):


class EnumType(object):
def __init__(self, enum):
def __init__(self, enum, description=None):
self.enum = enum
self.description = description

@property
def name(self):
Expand Down Expand Up @@ -145,10 +146,11 @@ def __str__(self):


class InputObjectType(object):
def __init__(self, name, fields):
def __init__(self, name, fields, description=None):
self.name = name
self.fields = Fields(name, fields)
self.instance_type = memoize(self._create_instance_type)
self.description = description

def _create_instance_type(self):
name = self.name
Expand Down Expand Up @@ -222,15 +224,16 @@ def coerce(self, value):
raise _coercion_error(value, self.name)


def input_field(name, type, default=_undefined):
return InputField(name, type, default)
def input_field(name, type, default=_undefined, description=None):
return InputField(name, type, default, description=description)


class InputField(object):
def __init__(self, name, type, default):
def __init__(self, name, type, default, description=None):
self.name = name
self.type = type
self.default = default
self.description = description

@property
def has_default(self):
Expand All @@ -241,9 +244,10 @@ def __repr__(self):


class InterfaceType(object):
def __init__(self, name, fields):
def __init__(self, name, fields, description=None):
self.name = name
self.fields = Fields(name, fields)
self.description = description

def __call__(self, *field_queries):
return ObjectQuery.create(self, field_queries=field_queries)
Expand Down Expand Up @@ -399,11 +403,12 @@ def __str__(self):


class ObjectType(object):
def __init__(self, name, fields, interfaces=None):
def __init__(self, name, fields, interfaces=None, description=None):
if interfaces is None:
interfaces = ()

self.name = name
self.description = description
if not callable(fields):
fields = lambdaize(fields)
def owned_fields():
Expand Down Expand Up @@ -579,21 +584,28 @@ class Args(object):
pass


def field(name, type, params=None):
def field(name, type, params=None, description=None):
if params is None:
params = ()
return Field(owner_type=None, name=name, type=type, params=params)
return Field(owner_type=None, name=name, type=type, params=params, description=description)


class Field(object):
def __init__(self, owner_type, name, type, params):
def __init__(self, owner_type, name, type, params, description=None):
self.owner_type = owner_type
self.name = name
self.type = type
self.params = Params(name, params)
self.description = description

def with_owner_type(self, owner_type):
return Field(owner_type=owner_type, name=self.name, type=self.type, params=self.params)
return Field(
owner_type=owner_type,
name=self.name,
type=self.type,
params=self.params,
description=self.description,
)

def __call__(self, *args):
field_queries, field_args = _partition_by_type(args, (FieldQuery, Argument))
Expand Down Expand Up @@ -731,15 +743,16 @@ def key(key, field_query):
)


def param(name, type, default=_undefined):
return Parameter(name=name, type=type, default=default)
def param(name, type, default=_undefined, description=None):
return Parameter(name=name, type=type, default=default, description=description)


class Parameter(object):
def __init__(self, name, type, default):
def __init__(self, name, type, default, description=None):
self.name = name
self.type = type
self.default = default
self.description = description

@property
def has_default(self):
Expand Down
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ def read(fname):

setup(
name='graphlayer',
version='0.4.0',
version='0.5.0',
description='High-performance library for implementing GraphQL APIs',
long_description=read("README.rst"),
author='Michael Williamson',
Expand Down
Loading