Skip to content

Commit 24cad44

Browse files
jhggjhgg
committed
introspection descriptions for scalars and introspection
1 parent 82b0e8c commit 24cad44

File tree

3 files changed

+423
-370
lines changed

3 files changed

+423
-370
lines changed

‎graphql/core/type/introspection.py‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,9 @@
1818

1919
__Schema = GraphQLObjectType(
2020
'__Schema',
21-
description='A GraphQL Schema defines the capabilities of a GraphQL '
22-
'server. It exposes all available types and directives on '
23-
'the server, as well as the entry points for query and '
24-
'mutation operations.',
21+
description='A GraphQL Schema defines the capabilities of a GraphQL server. It '
22+
'exposes all available types and directives on the server, as well as '
23+
'the entry points for query and mutation operations.',
2524
fields=lambda: OrderedDict([
2625
('types', GraphQLField(
2726
description='A list of all types supported by this server.',
@@ -54,6 +53,12 @@
5453

5554
__Directive = GraphQLObjectType(
5655
'__Directive',
56+
description='A Directives provides a way to describe alternate runtime execution and '
57+
'type validation behavior in a GraphQL document.'
58+
'\n\nIn some cases, you need to provide options to alter GraphQL\'s '
59+
'execution behavior in ways field arguments will not suffice, such as '
60+
'conditionally including or skipping a field. Directives provide this by '
61+
'describing additional information to the executor.',
5762
fields=lambda: OrderedDict([
5863
('name', GraphQLField(GraphQLNonNull(GraphQLString))),
5964
('description', GraphQLField(GraphQLString)),
@@ -143,6 +148,14 @@ def input_fields(type, *_):
143148

144149
__Type = GraphQLObjectType(
145150
'__Type',
151+
description='The fundamental unit of any GraphQL Schema is the type. There are '
152+
'many kinds of types in GraphQL as represented by the `__TypeKind` enum.'
153+
'\n\nDepending on the kind of a type, certain fields describe '
154+
'information about that type. Scalar types provide no information '
155+
'beyond a name and description, while Enum types provide their values. '
156+
'Object and Interface types provide the fields they describe. Abstract '
157+
'types, Union and Interface, provide the Object types possible '
158+
'at runtime. List and NonNull types compose other types.',
146159
fields=lambda: OrderedDict([
147160
('kind', GraphQLField(
148161
type=GraphQLNonNull(__TypeKind),
@@ -190,6 +203,8 @@ def input_fields(type, *_):
190203

191204
__Field = GraphQLObjectType(
192205
'__Field',
206+
description='Object and Interface types are described by a list of Fields, each of '
207+
'which has a name, potentially a list of arguments, and a return type.',
193208
fields=lambda: OrderedDict([
194209
('name', GraphQLField(GraphQLNonNull(GraphQLString))),
195210
('description', GraphQLField(GraphQLString)),
@@ -211,6 +226,9 @@ def input_fields(type, *_):
211226

212227
__InputValue = GraphQLObjectType(
213228
'__InputValue',
229+
description='Arguments provided to Fields or Directives and the input fields of an '
230+
'InputObject are represented as Input Values which describe their type '
231+
'and optionally a default value.',
214232
fields=lambda: OrderedDict([
215233
('name', GraphQLField(GraphQLNonNull(GraphQLString))),
216234
('description', GraphQLField(GraphQLString)),
@@ -225,6 +243,9 @@ def input_fields(type, *_):
225243

226244
__EnumValue = GraphQLObjectType(
227245
'__EnumValue',
246+
description='One possible value for a given Enum. Enum values are unique values, not '
247+
'a placeholder for a string or numeric value. However an Enum value is '
248+
'returned in a JSON response as a string.',
228249
fields=lambda: OrderedDict([
229250
('name', GraphQLField(GraphQLNonNull(GraphQLString))),
230251
('description', GraphQLField(GraphQLString)),
@@ -240,7 +261,7 @@ def input_fields(type, *_):
240261

241262
__TypeKind = GraphQLEnumType(
242263
'__TypeKind',
243-
description='An enum describing what kind of type a given __Type is',
264+
description='An enum describing what kind of type a given `__Type` is',
244265
values=OrderedDict([
245266
('SCALAR', GraphQLEnumValue(
246267
TypeKind.SCALAR,
@@ -305,7 +326,8 @@ def input_fields(type, *_):
305326
del TypeMetaFieldDef_args_name
306327

307328
TypeNameMetaFieldDef = GraphQLField(
308-
GraphQLNonNull(GraphQLString),
329+
type=GraphQLNonNull(GraphQLString),
330+
description='The name of the current Object type at runtime.',
309331
resolver=lambda source, args, info: info.parent_type.name,
310332
args=[]
311333
)

‎graphql/core/type/scalars.py‎

Lines changed: 46 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,16 @@ def parse_int_literal(ast):
3333
if MIN_INT <= num <= MAX_INT:
3434
return num
3535

36-
GraphQLInt = GraphQLScalarType(name='Int',
37-
serialize=coerce_int,
38-
parse_value=coerce_int,
39-
parse_literal=parse_int_literal)
36+
37+
GraphQLInt = GraphQLScalarType(
38+
name='Int',
39+
description='The `Int` scalar type represents non-fractional signed whole numeric '
40+
'values. Int can represent values between -(2^53 - 1) and 2^53 - 1 since '
41+
'represented in JSON as double-precision floating point numbers specified'
42+
'by [IEEE 754](http://en.wikipedia.org/wiki/IEEE_floating_point).',
43+
serialize=coerce_int,
44+
parse_value=coerce_int,
45+
parse_literal=parse_int_literal)
4046

4147

4248
def coerce_float(value):
@@ -54,10 +60,15 @@ def parse_float_literal(ast):
5460
return float(ast.value)
5561
return None
5662

57-
GraphQLFloat = GraphQLScalarType(name='Float',
58-
serialize=coerce_float,
59-
parse_value=coerce_float,
60-
parse_literal=parse_float_literal)
63+
64+
GraphQLFloat = GraphQLScalarType(
65+
name='Float',
66+
description='The `Float` scalar type represents signed double-precision fractional '
67+
'values as specified by '
68+
'[IEEE 754](http://en.wikipedia.org/wiki/IEEE_floating_point). ',
69+
serialize=coerce_float,
70+
parse_value=coerce_float,
71+
parse_literal=parse_float_literal)
6172

6273

6374
def coerce_string(value):
@@ -73,29 +84,44 @@ def parse_string_literal(ast):
7384

7485
return None
7586

76-
GraphQLString = GraphQLScalarType(name='String',
77-
serialize=coerce_string,
78-
parse_value=coerce_string,
79-
parse_literal=parse_string_literal)
87+
88+
GraphQLString = GraphQLScalarType(
89+
name='String',
90+
description='The `String` scalar type represents textual data, represented as UTF-8 '
91+
'character sequences. The String type is most often used by GraphQL to '
92+
'represent free-form human-readable text.',
93+
serialize=coerce_string,
94+
parse_value=coerce_string,
95+
parse_literal=parse_string_literal)
8096

8197

8298
def parse_boolean_literal(ast):
8399
if isinstance(ast, BooleanValue):
84100
return ast.value
85101
return None
86102

87-
GraphQLBoolean = GraphQLScalarType(name='Boolean',
88-
serialize=bool,
89-
parse_value=bool,
90-
parse_literal=parse_boolean_literal)
103+
104+
GraphQLBoolean = GraphQLScalarType(
105+
name='Boolean',
106+
description='The `Boolean` scalar type represents `true` or `false`.',
107+
serialize=bool,
108+
parse_value=bool,
109+
parse_literal=parse_boolean_literal)
91110

92111

93112
def parse_id_literal(ast):
94113
if isinstance(ast, (StringValue, IntValue)):
95114
return ast.value
96115
return None
97116

98-
GraphQLID = GraphQLScalarType(name='ID',
99-
serialize=str,
100-
parse_value=str,
101-
parse_literal=parse_id_literal)
117+
118+
GraphQLID = GraphQLScalarType(
119+
name='ID',
120+
description='The `ID` scalar type represents a unique identifier, often used to '
121+
'refetch an object or as key for a cache. The ID type appears in a JSON '
122+
'response as a String; however, it is not intended to be human-readable. '
123+
'When expected as an input type, any string (such as `"4"`) or integer '
124+
'(such as `4`) input value will be accepted as an ID.',
125+
serialize=str,
126+
parse_value=str,
127+
parse_literal=parse_id_literal)

0 commit comments

Comments
 (0)