Skip to content

Commit 290d5e1

Browse files
denisartdenisart
authored
Feature/update docs (#20)
* feature: Add config references to README.md * feature: Added config references to docs * feature: Added deprecation directive example
1 parent 23401ba commit 290d5e1

File tree

4 files changed

+187
-4
lines changed

4 files changed

+187
-4
lines changed

‎README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,58 @@ and run the following command
3535
```bash
3636
graphql2python render --config ./graphql2python.yaml
3737
```
38+
39+
## Config reference
40+
41+
Global keywords
42+
43+
| keyword | description |
44+
|----------------|---------------------------------------------------------------|
45+
| `schema` | A path to the target GraphQL schema file. |
46+
| `output` | A file name for output `py` file. |
47+
| `license_file` | An optional path to a file with license for output `py` file. |
48+
| `options` | Optional options for render of output `py` file. |
49+
50+
Options keywords
51+
52+
| keywords | description |
53+
|-----------------------|------------------------------------------------------------------------------------------------------------------------|
54+
| `max_line_len` | The maximum of line length of output `py` file. Default is `120`. |
55+
| `name_suffix` | A suffix for invalid field name (as python object name). Default is `"_"`. |
56+
| `each_field_optional` | Each fields of interfaces and objects are optional. Default is `false`. |
57+
| `add_from_dict` | Add `from_dict` (dict -> model) method to the general class. Default is `false`. |
58+
| `add_to_dict` | Add `to_dict` (model -> dict) method to the general class. Default is `false`. |
59+
| `scalar_pytypes` | A dict with python types for custom GraphQL scalars. Maps from scalar name to python type name. Default is empty dict. |
60+
| `fields_setting` | Settings for interfaces or objects fields. Maps from object name to a dict with setting. Default is empty dict. |
61+
62+
`fields_setting` keywords for some object name
63+
64+
| keywords | desciption |
65+
|------------|-----------------------------------------------------------------------|
66+
| `alias` | An alias for a field (see Field.alias for pydantic). Default is null. |
67+
| `new_name` | A new name for a field. Default is null. |
68+
69+
An example for `graphql2python.yaml` config:
70+
71+
```yaml
72+
# graphql2python.yaml
73+
schema: ./schema/schema.graphql
74+
output: ./model/model.py
75+
license_file: ./LICENSE
76+
options:
77+
scalar_pytypes:
78+
String: str
79+
Float: float
80+
Int: int
81+
ID: str
82+
Boolean: bool
83+
DateTime: datetime
84+
Date: date
85+
max_line_len: 79
86+
each_field_optional: true
87+
fields_setting:
88+
MyObjectName:
89+
from:
90+
alias: from
91+
new_name: correct_from
92+
```

‎docs/source/index.rst‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,84 @@ and run the following command
5656
5757
See the documentation for all the possibilities (
5858
while it is `docs/source/`).
59+
60+
Config reference
61+
----
62+
63+
Global keywords
64+
65+
.. list-table::
66+
:widths: auto
67+
:align: left
68+
69+
* - keyword
70+
- description
71+
* - `schema`
72+
- A path to the target GraphQL schema file.
73+
* - `output`
74+
- A file name for output `py` file.
75+
* - `license_file`
76+
- An optional path to a file with license for output `py` file.
77+
* - `options`
78+
- Optional options for render of output `py` file.
79+
80+
Options keywords
81+
82+
.. list-table::
83+
:widths: auto
84+
:align: left
85+
86+
* - keywords
87+
- description
88+
* - `max_line_len`
89+
- The maximum of line length of output `py` file. Default is `120`.
90+
* - `name_suffix`
91+
- A suffix for invalid field name (as python object name). Default is `"_"`.
92+
* - `each_field_optional`
93+
- Each fields of interfaces and objects are optional. Default is `false`.
94+
* - `add_from_dict`
95+
- Add `from_dict` (dict -> model) method to the general class. Default is `false`.
96+
* - `add_to_dict`
97+
- Add `to_dict` (model -> dict) method to the general class. Default is `false`.
98+
* - `scalar_pytypes`
99+
- A dict with python types for custom GraphQL scalars. Maps from scalar name to python type name. Default is empty dict.
100+
* - `fields_setting`
101+
- Settings for interfaces or objects fields. Maps from object name to a dict with setting. Default is empty dict.
102+
103+
`fields_setting` keywords for some object name
104+
105+
.. list-table::
106+
:widths: auto
107+
:align: left
108+
109+
* - keywords
110+
- description
111+
* - `alias`
112+
- An alias for a field (see Field.alias for pydantic). Default is null.
113+
* - `new_name`
114+
- A new name for a field. Default is null.
115+
116+
An example for `graphql2python.yaml` config:
117+
118+
.. code-block:: yaml
119+
120+
# graphql2python.yaml
121+
schema: ./schema/schema.graphql
122+
output: ./model/model.py
123+
license_file: ./LICENSE
124+
options:
125+
scalar_pytypes:
126+
String: str
127+
Float: float
128+
Int: int
129+
ID: str
130+
Boolean: bool
131+
DateTime: datetime
132+
Date: date
133+
max_line_len: 79
134+
each_field_optional: true
135+
fields_setting:
136+
MyObjectName:
137+
from:
138+
alias: from
139+
new_name: correct_from

‎docs/source/model.rst‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -351,4 +351,49 @@ For rename field we can using the following config:
351351
id: 'ID'
352352
character_name: 'String' = Field(..., alias='name')
353353
friends: _t.Optional[_t.List[_t.Optional['Character']]] = Field(default_factory=list)
354-
typename__: _t.Literal["Character"] = Field(default="Character", alias="__typename")
354+
typename__: _t.Literal["Character"] = Field(default="Character", alias="__typename")
355+
356+
Deprecation field
357+
-----
358+
359+
graphql2python support only `@deprecated` directive for fields
360+
(because graphql-core supported only this directive https://github.com/graphql-python/graphql-core/issues/162).
361+
Example of result with `@deprecated`:
362+
363+
.. code-block:: graphql
364+
365+
# schema.graphql
366+
type Country {
367+
code: ID! @deprecated(reason: "my reason") @requires(fields: "name")
368+
name: String! @requires(fields: "phone")
369+
native: String!
370+
phone: String!
371+
continent: Continent!
372+
capital: String
373+
currency: String
374+
languages: [Language!]!
375+
emoji: String!
376+
emojiU: String!
377+
states: [State!]!
378+
}
379+
380+
.. code-block:: python
381+
382+
# output.py
383+
class Country(GraphQLBaseModel):
384+
"""
385+
An Object type
386+
See https://graphql.org/learn/schema/#object-types-and-fields
387+
"""
388+
capital: _t.Optional['String'] = Field(default=None)
389+
code: _t.Optional['ID'] = Field(default=None) # deprecation_reason: my reason
390+
continent: _t.Optional['Continent'] = Field(default=None)
391+
currency: _t.Optional['String'] = Field(default=None)
392+
emoji: _t.Optional['String'] = Field(default=None)
393+
emojiU: _t.Optional['String'] = Field(default=None)
394+
languages: _t.Optional[_t.List['Language']] = Field(default_factory=list)
395+
name: _t.Optional['String'] = Field(default=None)
396+
native: _t.Optional['String'] = Field(default=None)
397+
phone: _t.Optional['String'] = Field(default=None)
398+
states: _t.Optional[_t.List['State']] = Field(default_factory=list)
399+
typename__: _t.Literal["Country"] = Field(default="Country", alias="__typename")

‎graphql2python/model/config.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,17 @@
1515

1616

1717
class FieldSetting(BaseModel):
18-
alias: Optional[str] = Field(default=None)
19-
new_name: Optional[str] = Field(default=None)
18+
"""Settings for an object field."""
19+
20+
alias: Optional[str] = Field(default=None, description="An alias for a field (see Field.alias for pydantic).")
21+
new_name: Optional[str] = Field(default=None, description="")
2022

2123

2224
class GraphQL2PythonModelOptions(BaseModel):
2325
"""Data-model render options."""
2426

2527
scalar_pytypes: Dict[str, str] = Field(
26-
description="Python types for custom GraphQL scalars.",
28+
description="A dict with python types for custom GraphQL scalars.",
2729
default_factory=dict
2830
)
2931
fields_setting: Dict[str, Dict[str, FieldSetting]] = Field(

0 commit comments

Comments
 (0)