Feature/update docs

README.md

@@ -35,3 +35,58 @@ and run the following command
 ```bash
 graphql2python render --config ./graphql2python.yaml
 ```
+
+## Config reference
+
+Global keywords
+
+| keyword | description |
+|----------------|---------------------------------------------------------------|
+| `schema` | A path to the target GraphQL schema file. |
+| `output` | A file name for output `py` file. |
+| `license_file` | An optional path to a file with license for output `py` file. |
+| `options` | Optional options for render of output `py` file. |
+
+Options keywords
+
+| keywords | description |
+|-----------------------|------------------------------------------------------------------------------------------------------------------------|
+| `max_line_len` | The maximum of line length of output `py` file. Default is `120`. |
+| `name_suffix` | A suffix for invalid field name (as python object name). Default is `"_"`. |
+| `each_field_optional` | Each fields of interfaces and objects are optional. Default is `false`. |
+| `add_from_dict` | Add `from_dict` (dict -> model) method to the general class. Default is `false`. |
+| `add_to_dict` | Add `to_dict` (model -> dict) method to the general class. Default is `false`. |
+| `scalar_pytypes` | A dict with python types for custom GraphQL scalars. Maps from scalar name to python type name. Default is empty dict. |
+| `fields_setting` | Settings for interfaces or objects fields. Maps from object name to a dict with setting. Default is empty dict. |
+
+`fields_setting` keywords for some object name
+
+| keywords | desciption |
+|------------|-----------------------------------------------------------------------|
+| `alias` | An alias for a field (see Field.alias for pydantic). Default is null. |
+| `new_name` | A new name for a field. Default is null. |
+
+An example for `graphql2python.yaml` config:
+
+```yaml
+# graphql2python.yaml
+schema: ./schema/schema.graphql
+output: ./model/model.py
+license_file: ./LICENSE
+options:
+ scalar_pytypes:
+ String: str
+ Float: float
+ Int: int
+ ID: str
+ Boolean: bool
+ DateTime: datetime
+ Date: date
+ max_line_len: 79
+ each_field_optional: true
+ fields_setting:
+ MyObjectName:
+ from:
+ alias: from
+ new_name: correct_from
+```

docs/source/index.rst

@@ -56,3 +56,84 @@ and run the following command
 
 See the documentation for all the possibilities (
 while it is `docs/source/`).
+
+Config reference
+----
+
+Global keywords
+
+.. list-table::
+ :widths: auto
+ :align: left
+
+ * - keyword
+ - description
+ * - `schema`
+ - A path to the target GraphQL schema file.
+ * - `output`
+ - A file name for output `py` file.
+ * - `license_file`
+ - An optional path to a file with license for output `py` file.
+ * - `options`
+ - Optional options for render of output `py` file.
+
+Options keywords
+
+.. list-table::
+ :widths: auto
+ :align: left
+
+ * - keywords
+ - description
+ * - `max_line_len`
+ - The maximum of line length of output `py` file. Default is `120`.
+ * - `name_suffix`
+ - A suffix for invalid field name (as python object name). Default is `"_"`.
+ * - `each_field_optional`
+ - Each fields of interfaces and objects are optional. Default is `false`.
+ * - `add_from_dict`
+ - Add `from_dict` (dict -> model) method to the general class. Default is `false`.
+ * - `add_to_dict`
+ - Add `to_dict` (model -> dict) method to the general class. Default is `false`.
+ * - `scalar_pytypes`
+ - A dict with python types for custom GraphQL scalars. Maps from scalar name to python type name. Default is empty dict.
+ * - `fields_setting`
+ - Settings for interfaces or objects fields. Maps from object name to a dict with setting. Default is empty dict.
+
+`fields_setting` keywords for some object name
+
+.. list-table::
+ :widths: auto
+ :align: left
+
+ * - keywords
+ - description
+ * - `alias`
+ - An alias for a field (see Field.alias for pydantic). Default is null.
+ * - `new_name`
+ - A new name for a field. Default is null.
+
+An example for `graphql2python.yaml` config:
+
+.. code-block:: yaml
+
+ # graphql2python.yaml
+ schema: ./schema/schema.graphql
+ output: ./model/model.py
+ license_file: ./LICENSE
+ options:
+ scalar_pytypes:
+ String: str
+ Float: float
+ Int: int
+ ID: str
+ Boolean: bool
+ DateTime: datetime
+ Date: date
+ max_line_len: 79
+ each_field_optional: true
+ fields_setting:
+ MyObjectName:
+ from:
+ alias: from
+ new_name: correct_from

docs/source/model.rst

@@ -351,4 +351,49 @@ For rename field we can using the following config:
  id: 'ID'
  character_name: 'String' = Field(..., alias='name')
  friends: _t.Optional[_t.List[_t.Optional['Character']]] = Field(default_factory=list)
- typename__: _t.Literal["Character"] = Field(default="Character", alias="__typename")
+ typename__: _t.Literal["Character"] = Field(default="Character", alias="__typename")
+
+Deprecation field
+-----
+
+graphql2python support only `@deprecated` directive for fields
+(because graphql-core supported only this directive https://github.com/graphql-python/graphql-core/issues/162).
+Example of result with `@deprecated`:
+
+.. code-block:: graphql
+
+ # schema.graphql
+ type Country {
+ code: ID! @deprecated(reason: "my reason") @requires(fields: "name")
+ name: String! @requires(fields: "phone")
+ native: String!
+ phone: String!
+ continent: Continent!
+ capital: String
+ currency: String
+ languages: [Language!]!
+ emoji: String!
+ emojiU: String!
+ states: [State!]!
+ }
+
+.. code-block:: python
+
+ # output.py
+ class Country(GraphQLBaseModel):
+ """
+ An Object type
+ See https://graphql.org/learn/schema/#object-types-and-fields
+ """
+ capital: _t.Optional['String'] = Field(default=None)
+ code: _t.Optional['ID'] = Field(default=None) # deprecation_reason: my reason
+ continent: _t.Optional['Continent'] = Field(default=None)
+ currency: _t.Optional['String'] = Field(default=None)
+ emoji: _t.Optional['String'] = Field(default=None)
+ emojiU: _t.Optional['String'] = Field(default=None)
+ languages: _t.Optional[_t.List['Language']] = Field(default_factory=list)
+ name: _t.Optional['String'] = Field(default=None)
+ native: _t.Optional['String'] = Field(default=None)
+ phone: _t.Optional['String'] = Field(default=None)
+ states: _t.Optional[_t.List['State']] = Field(default_factory=list)
+ typename__: _t.Literal["Country"] = Field(default="Country", alias="__typename")

graphql2python/model/config.py

@@ -15,15 +15,17 @@
 
 
 class FieldSetting(BaseModel):
- alias: Optional[str] = Field(default=None)
- new_name: Optional[str] = Field(default=None)
+ """Settings for an object field."""
+
+ alias: Optional[str] = Field(default=None, description="An alias for a field (see Field.alias for pydantic).")
+ new_name: Optional[str] = Field(default=None, description="")
 
 
 class GraphQL2PythonModelOptions(BaseModel):
  """Data-model render options."""
 
  scalar_pytypes: Dict[str, str] = Field(
- description="Python types for custom GraphQL scalars.",
+ description="A dict with python types for custom GraphQL scalars.",
  default_factory=dict
  )
  fields_setting: Dict[str, Dict[str, FieldSetting]] = Field(