From d9a3e5fa58cf98b8ab623f5b702bcbe823f90c1c Mon Sep 17 00:00:00 2001 From: Richard Smith Date: Tue, 22 Sep 2026 12:16:53 +0100 Subject: [PATCH 1/2] Add description support to ObjectType, InterfaceType, InputObjectType, fields, params and input fields Threads an optional description= kwarg through the graph-side schema builders (ObjectType, InterfaceType, InputObjectType, field, param, input_field) and propagates it into the generated GraphQLObjectType / GraphQLInterfaceType / GraphQLInputObjectType / GraphQLField / GraphQLArgument / GraphQLInputField, so descriptions show up in introspection and GraphiQL. Bump version to 0.5.0. Co-Authored-By: Claude Sonnet 5 --- graphlayer/graphql/schema.py | 8 ++- graphlayer/schema.py | 38 ++++++++---- setup.py | 2 +- tests/graphql/test_schema.py | 115 ++++++++++++++++++++++++++++++++--- 4 files changed, 138 insertions(+), 25 deletions(-) diff --git a/graphlayer/graphql/schema.py b/graphlayer/graphql/schema.py index f415d50..690c639 100644 --- a/graphlayer/graphql/schema.py +++ b/graphlayer/graphql/schema.py @@ -51,6 +51,7 @@ 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): @@ -58,6 +59,7 @@ def generate_graphql_type(graph_type): 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): @@ -74,6 +76,7 @@ def generate_graphql_type(graph_type): to_graphql_type(interface).of_type for interface in graph_type.interfaces ), + description=graph_type.description, )) else: @@ -85,7 +88,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) def to_graphql_fields(graph_fields): return lambda: iterables.to_dict( @@ -100,6 +103,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): @@ -108,7 +112,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: diff --git a/graphlayer/schema.py b/graphlayer/schema.py index 116a6f3..45a236f 100644 --- a/graphlayer/schema.py +++ b/graphlayer/schema.py @@ -145,10 +145,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 @@ -222,15 +223,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): @@ -241,9 +243,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) @@ -399,11 +402,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(): @@ -579,21 +583,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)) @@ -731,15 +742,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): diff --git a/setup.py b/setup.py index f969fd1..8cee992 100644 --- a/setup.py +++ b/setup.py @@ -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', diff --git a/tests/graphql/test_schema.py b/tests/graphql/test_schema.py index f1eef6f..f115a8d 100644 --- a/tests/graphql/test_schema.py +++ b/tests/graphql/test_schema.py @@ -86,6 +86,82 @@ def test_object_type_is_converted_to_non_null_graphql_object_type(): )) +def test_object_type_description_is_converted_to_graphql_object_type_description(): + graph_type = g.ObjectType("Obj", description="An object.", fields=( + g.field("value", type=g.String), + )) + + assert_that(to_graphql_type(graph_type), is_graphql_non_null( + is_graphql_object_type(description=equal_to("An object.")), + )) + + +def test_field_description_is_converted_to_graphql_field_description(): + graph_type = g.ObjectType("Obj", fields=( + g.field("value", type=g.String, description="A value."), + )) + + assert_that(to_graphql_type(graph_type), is_graphql_non_null( + is_graphql_object_type( + fields=is_mapping({ + "value": is_graphql_field(description=equal_to("A value.")), + }), + ), + )) + + +def test_param_description_is_converted_to_graphql_argument_description(): + graph_type = g.ObjectType("Obj", fields=( + g.field("value", type=g.String, params=( + g.param("arg", g.Int, description="An argument."), + )), + )) + + assert_that(to_graphql_type(graph_type), is_graphql_non_null( + is_graphql_object_type( + fields=is_mapping({ + "value": is_graphql_field(args=is_mapping({ + "arg": is_graphql_argument(description=equal_to("An argument.")), + })), + }), + ), + )) + + +def test_interface_type_description_is_converted_to_graphql_interface_type_description(): + graph_type = g.InterfaceType("Item", description="An item.", fields=( + g.field("value", type=g.String), + )) + + assert_that(to_graphql_type(graph_type), is_graphql_non_null( + is_graphql_interface_type(name="Item", description=equal_to("An item.")), + )) + + +def test_input_object_type_description_is_converted_to_graphql_input_object_type_description(): + graph_type = g.InputObjectType("Obj", description="An input object.", fields=( + g.input_field("value", type=g.String), + )) + + assert_that(to_graphql_input_type(graph_type), is_graphql_non_null( + is_graphql_input_object_type(name="Obj", description=equal_to("An input object.")), + )) + + +def test_input_field_description_is_converted_to_graphql_input_field_description(): + graph_type = g.InputObjectType("Obj", fields=( + g.input_field("value", type=g.String, description="A value."), + )) + + assert_that(to_graphql_input_type(graph_type), is_graphql_non_null( + is_graphql_input_object_type( + fields=is_mapping({ + "value": is_graphql_input_field(description=equal_to("A value.")), + }), + ), + )) + + def test_object_type_field_names_are_converted_from_snake_case_to_camel_case(): graph_type = g.ObjectType("Obj", fields=( g.field("field_name", type=g.String), @@ -273,37 +349,48 @@ def is_graphql_enum_value(value): ) -def is_graphql_input_field(type): +def is_graphql_input_field(type=None, description=None): + if type is None: + type = anything + if description is None: + description = anything + return all_of( is_instance(graphql.GraphQLInputField), - has_attrs(type=type), + has_attrs(type=type, description=description), ) -def is_graphql_input_object_type(name=None, fields=None): +def is_graphql_input_object_type(name=None, fields=None, description=None): if name is None: name = anything if fields is None: fields = anything + if description is None: + description = anything return all_of( is_instance(graphql.GraphQLInputObjectType), has_attrs( name=name, fields=fields, + description=description, ), ) -def is_graphql_interface_type(name, fields=None): +def is_graphql_interface_type(name, fields=None, description=None): if fields is None: fields = anything + if description is None: + description = anything return all_of( is_instance(graphql.GraphQLInterfaceType), has_attrs( name=name, fields=fields, + description=description, ), ) @@ -322,7 +409,7 @@ def is_graphql_non_null(element_matcher): ) -def is_graphql_object_type(name=None, fields=None, interfaces=None): +def is_graphql_object_type(name=None, fields=None, interfaces=None, description=None): if name is None: name = anything @@ -332,35 +419,45 @@ def is_graphql_object_type(name=None, fields=None, interfaces=None): if interfaces is None: interfaces = anything + if description is None: + description = anything + return all_of( is_instance(graphql.GraphQLObjectType), has_attrs( name=name, fields=fields, interfaces=interfaces, + description=description, ), ) -def is_graphql_field(type=None, args=None): +def is_graphql_field(type=None, args=None, description=None): if type is None: type = anything if args is None: args = anything + if description is None: + description = anything + return all_of( is_instance(graphql.GraphQLField), - has_attrs(type=type, args=args), + has_attrs(type=type, args=args, description=description), ) -def is_graphql_argument(type=None): +def is_graphql_argument(type=None, description=None): if type is None: type = anything + if description is None: + description = anything + return all_of( is_instance(graphql.GraphQLArgument), - has_attrs(type=type), + has_attrs(type=type, description=description), ) From dc47fdf70ffdb3dd35def5867a596729b294fe2f Mon Sep 17 00:00:00 2001 From: Richard Smith Date: Thu, 8 Oct 2026 16:41:12 +0100 Subject: [PATCH 2/2] Add description support to EnumType and document schema descriptions in README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses review feedback on #6: EnumType was the one named/documented schema type still missing description= support, so it's added here and propagated into the generated GraphQLEnumType. The built-in scalar types (Boolean, Float, Int, String) are left as-is — they map directly onto graphql-core's standard scalar types, which already carry fixed, spec-mandated descriptions, and graphlayer doesn't support defining custom scalar types at all. Documented this reasoning in the new README section alongside a worked example of every type/field that does accept description=. Co-Authored-By: Claude Sonnet 5 --- README.rst | 57 ++++++++++++++++++++++++++++++++++++ graphlayer/graphql/schema.py | 6 +++- graphlayer/schema.py | 3 +- tests/graphql/test_schema.py | 22 ++++++++++++-- 4 files changed, 84 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index d9490b6..4737fd6 100644 --- a/README.rst +++ b/README.rst @@ -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. + diff --git a/graphlayer/graphql/schema.py b/graphlayer/graphql/schema.py index 690c639..7822c1e 100644 --- a/graphlayer/graphql/schema.py +++ b/graphlayer/graphql/schema.py @@ -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): diff --git a/graphlayer/schema.py b/graphlayer/schema.py index 45a236f..e76c161 100644 --- a/graphlayer/schema.py +++ b/graphlayer/schema.py @@ -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): diff --git a/tests/graphql/test_schema.py b/tests/graphql/test_schema.py index f115a8d..7e16a58 100644 --- a/tests/graphql/test_schema.py +++ b/tests/graphql/test_schema.py @@ -45,6 +45,21 @@ class Season(enum.Enum): ))) +def test_enum_description_is_converted_to_graphql_enum_type_description(): + class Season(enum.Enum): + winter = "WINTER" + + SeasonGraphType = g.EnumType(Season, description="The four seasons.") + + graphql_type = to_graphql_type(SeasonGraphType) + + assert_that(graphql_type, is_graphql_non_null(is_graphql_enum_type( + name="Season", + values=anything, + description=equal_to("The four seasons."), + ))) + + def test_interface_type_is_converted_to_non_null_graphql_interface_type(): graph_type = g.InterfaceType("Obj", fields=( g.field("value", type=g.String), @@ -335,10 +350,13 @@ def to_graphql_input_type(graph_type): is_graphql_string = equal_to(graphql.GraphQLString) -def is_graphql_enum_type(name, values): +def is_graphql_enum_type(name, values, description=None): + if description is None: + description = anything + return all_of( is_instance(graphql.GraphQLEnumType), - has_attrs(name=name, values=values), + has_attrs(name=name, values=values, description=description), )