mirror of
https://github.com/koxudaxi/datamodel-code-generator.git
synced 2024-03-18 14:54:37 +03:00
Update documentation (#1316)
* Make small grammatical and phrasing changes, update external like to JSON schema docs, remove unused schema keywords, unify JSON Schema language * Title case some headers, modify some phrasing, remove duplicate custom template docs, clean up using_as_module with phrasing and removal of redundant ending. * Add crosslinks between documents for clarity, rephrase sectinos, unify representation of "JSON Schema", remove specifictation of temporary directory use * Reword "File" to "Data" to include python dicts, update working on project mentions * Update language from "repositories" to "projects" to include links that are not repos * Small phrasing update * Update phrasing of supported data page for clairty * Unify representation of "JSON", remove redundant information from index * Synchronize changes between readme and index page * Standardize formatting, fix heading levels
This commit is contained in:
Noddy
@@ -1,4 +1,4 @@
|
||||
## Custom template
|
||||
# Custom Templates
|
||||
|
||||
One of the powerful features of the `datamodel-code-generator` is the ability to use custom templates with the `--custom-template-dir` option.
|
||||
This option allows you to provide a directory containing Jinja2 templates for customizing the generated code. In this document, we'll explore how to use this option and provide an example to help you understand its usage.
|
||||
@@ -16,7 +16,8 @@ Replace {your_input_file}, {your_output_file}, and {your_custom_template_directo
|
||||
Let's say you want to generate a custom Python data model from a JSON Schema file called person.json. You want the generated data model to include a custom comment at the top of the file. To achieve this, you can create a custom template using Jinja2.
|
||||
|
||||
First, create a directory called `custom_templates` in your project directory. Inside this folder, create another folder called pydantic. Now, inside the `pydantic` folder, create a new file called `BaseModel.jinja2` with the following content:
|
||||
#### custom_templates/pydantic/BaseModel.jinja2
|
||||
|
||||
**custom_templates/pydantic/BaseModel.jinja2**
|
||||
```jinja2
|
||||
# This is a custom comment generated with custom_template!!
|
||||
|
||||
@@ -34,7 +35,8 @@ $ datamodel-codegen --input person.json --output person.py --custom-template-dir
|
||||
```
|
||||
|
||||
The generated `person.py` file will now include your custom comment at the top:
|
||||
#### person.py
|
||||
|
||||
**person.py**
|
||||
```python
|
||||
# generated by datamodel-codegen:
|
||||
# filename: person.json
|
||||
|
||||
@@ -1,94 +0,0 @@
|
||||
# Using as module
|
||||
|
||||
One of the powerful features of the `datamodel-code-generator` is the ability to use custom templates with the `--custom-template-dir` option.
|
||||
|
||||
This option allows you to provide a directory containing Jinja2 templates for customizing the generated code. In this document, we'll explore how to use this option and provide an example to help you understand its usage.
|
||||
|
||||
## Usage
|
||||
To use the `--custom-template-dir` option, you'll need to pass the directory path containing your custom templates as an argument. The command will look like this:
|
||||
|
||||
datamodel-code-generator is a CLI. But, it has another side as a python module.
|
||||
|
||||
You can call this code-generator in your python code.
|
||||
|
||||
## How to use it as module
|
||||
|
||||
You can generate models with `datamodel_code_generator.generate` into a temporary directory.
|
||||
|
||||
And, you can read files from the directory.
|
||||
|
||||
### Installation
|
||||
```sh
|
||||
pip install "datamodel-code-generator[http]"
|
||||
```
|
||||
|
||||
### Example
|
||||
```python
|
||||
from pathlib import Path
|
||||
from tempfile import TemporaryDirectory
|
||||
from datamodel_code_generator import InputFileType, generate
|
||||
|
||||
json_schema: str = """{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"number": {"type": "number"},
|
||||
"street_name": {"type": "string"},
|
||||
"street_type": {"type": "string",
|
||||
"enum": ["Street", "Avenue", "Boulevard"]
|
||||
}
|
||||
}
|
||||
}"""
|
||||
|
||||
with TemporaryDirectory() as temporary_directory_name:
|
||||
temporary_directory = Path(temporary_directory_name)
|
||||
output = Path(temporary_directory / 'model.py')
|
||||
generate(
|
||||
json_schema,
|
||||
input_file_type=InputFileType.JsonSchema,
|
||||
input_filename="example.json",
|
||||
output=output,
|
||||
)
|
||||
model: str = output.read_text()
|
||||
print(model)
|
||||
```
|
||||
|
||||
The result of print(model)
|
||||
```python
|
||||
# generated by datamodel-codegen:
|
||||
# filename: example.json
|
||||
# timestamp: 2020-12-21T08:01:06+00:00
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from enum import Enum
|
||||
from typing import Optional
|
||||
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
class StreetType(Enum):
|
||||
Street = 'Street'
|
||||
Avenue = 'Avenue'
|
||||
Boulevard = 'Boulevard'
|
||||
|
||||
|
||||
class Model(BaseModel):
|
||||
number: Optional[float] = None
|
||||
street_name: Optional[str] = None
|
||||
street_type: Optional[StreetType] = None
|
||||
```
|
||||
|
||||
## Why doesn't the function return str?
|
||||
|
||||
If generated code are modular files then, str can't reproduce the structure of modules.
|
||||
|
||||
Also, `TemporaryDirectory` and `Path` provide an easy way to read files.
|
||||
|
||||
There is an example when a generated model file is only one.
|
||||
|
||||
Otherwise, You should walk in a directory to find modular files.
|
||||
|
||||
|
||||
## Related projects
|
||||
|
||||
[fastapi-code-generator](https://github.com/koxudaxi/fastapi-code-generator) uses `datamodel-code-generator` as module to create models from OpenAPI.
|
||||
@@ -8,7 +8,9 @@ skip-string-normalization with using datamodel-codegen option `--use-double-quot
|
||||
it will override your black config skip-string-normalization value.
|
||||
Using --use-double-quotes may be useful if you can't use black config.
|
||||
|
||||
Example `pyproject.toml`:
|
||||
## Example
|
||||
|
||||
**pyproject.toml**
|
||||
```toml
|
||||
[tool.black]
|
||||
skip-string-normalization = true
|
||||
@@ -23,4 +25,4 @@ line_length = 100
|
||||
known_first_party = "kelvin"
|
||||
```
|
||||
|
||||
See the [Black Project](https://black.readthedocs.io/en/stable/pyproject_toml.html) for more information.
|
||||
See the [Black Project](https://pypi.org/project/black/) for more information.
|
||||
|
||||
@@ -4,6 +4,7 @@ This code generator creates [pydantic](https://docs.pydantic.dev/) model and [da
|
||||
|
||||
[](https://github.com/koxudaxi/datamodel-code-generator/actions?query=workflow%3ATest)
|
||||
[](https://pypi.python.org/pypi/datamodel-code-generator)
|
||||
[](https://anaconda.org/conda-forge/datamodel-code-generator)
|
||||
[](https://pepy.tech/project/datamodel-code-generator)
|
||||
[](https://pypi.python.org/pypi/datamodel-code-generator)
|
||||
[](https://codecov.io/gh/koxudaxi/datamodel-code-generator)
|
||||
@@ -11,9 +12,6 @@ This code generator creates [pydantic](https://docs.pydantic.dev/) model and [da
|
||||
[](https://github.com/psf/black)
|
||||
|
||||
|
||||
## Help
|
||||
See [documentation](https://koxudaxi.github.io/datamodel-code-generator) for more details.
|
||||
|
||||
## Sponsors
|
||||
[](https://github.com/JetBrainsOfficial)
|
||||
|
||||
@@ -24,7 +22,7 @@ To install `datamodel-code-generator`:
|
||||
$ pip install datamodel-code-generator
|
||||
```
|
||||
|
||||
## Simple usage
|
||||
## Simple Usage
|
||||
You can generate models from a local file.
|
||||
```bash
|
||||
$ datamodel-codegen --input api.yaml --output model.py
|
||||
@@ -234,14 +232,14 @@ class Apis(BaseModel):
|
||||
```
|
||||
</details>
|
||||
|
||||
## Which project uses it?
|
||||
These OSS use datamodel-code-generator to generate many models. We can learn about use-cases from these projects.
|
||||
## Projects that use datamodel-code-generator
|
||||
These OSS projects use datamodel-code-generator to generate many models. See the following linked projects for real world examples and inspiration.
|
||||
- [Netflix/consoleme](https://github.com/Netflix/consoleme)
|
||||
- *[How do I generate models from the Swagger specification?](https://github.com/Netflix/consoleme/blob/master/docs/gitbook/faq.md#how-do-i-generate-models-from-the-swagger-specification)*
|
||||
- [DataDog/integrations-core](https://github.com/DataDog/integrations-core)
|
||||
- *[Config models](https://github.com/DataDog/integrations-core/blob/master/docs/developer/meta/config-models.md)*
|
||||
- [awslabs/aws-lambda-powertools-python](https://github.com/awslabs/aws-lambda-powertools-python)
|
||||
- *Not used. But, introduced [advanced-use-cases](https://awslabs.github.io/aws-lambda-powertools-python/2.6.0/utilities/parser/#advanced-use-cases) in the official document*
|
||||
- *Recommended for [advanced-use-cases](https://awslabs.github.io/aws-lambda-powertools-python/2.6.0/utilities/parser/#advanced-use-cases) in the official documentation*
|
||||
- [open-metadata/OpenMetadata](https://github.com/open-metadata/OpenMetadata)
|
||||
- [Makefile](https://github.com/open-metadata/OpenMetadata/blob/main/Makefile)
|
||||
- [airbytehq/airbyte](https://github.com/airbytehq/airbyte)
|
||||
@@ -260,7 +258,6 @@ These OSS use datamodel-code-generator to generate many models. We can learn abo
|
||||
- [pydantic](https://docs.pydantic.dev/).BaseModel
|
||||
- [dataclasses.dataclass](https://docs.python.org/3/library/dataclasses.html)
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
To install `datamodel-code-generator`:
|
||||
@@ -285,7 +282,7 @@ You can genearte models from a URL.
|
||||
```bash
|
||||
$ datamodel-codegen --url https://<INPUT FILE URL> --output model.py
|
||||
```
|
||||
This method needs [http extra option](#http-extra-option)
|
||||
This method needs the [http extra option](#http-extra-option)
|
||||
|
||||
|
||||
## All Command Options
|
||||
@@ -319,7 +316,7 @@ usage: datamodel-codegen [-h] [--input INPUT] [--url URL]
|
||||
[--use-field-description] [--use-default-kwarg]
|
||||
[--reuse-model] [--keep-model-order]
|
||||
[--collapse-root-models]
|
||||
[--enum-field-as-literal {all,one}]
|
||||
[--enum-field-as-literal {all,one}] [--use-one-literal-as-default]
|
||||
[--set-default-enum-member]
|
||||
[--empty-enum-field-name EMPTY_ENUM_FIELD_NAME]
|
||||
[--capitalise-enum-members]
|
||||
@@ -333,7 +330,7 @@ usage: datamodel-codegen [-h] [--input INPUT] [--url URL]
|
||||
[--target-python-version {3.6,3.7,3.8,3.9,3.10,3.11}]
|
||||
[--wrap-string-literal] [--validation]
|
||||
[--use-double-quotes] [--encoding ENCODING] [--debug]
|
||||
[--disable-warnings] [--version]
|
||||
[--disable-warnings] [--version]
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
@@ -413,6 +410,8 @@ options:
|
||||
Parse enum field as literal. all: all enum field type
|
||||
are Literal. one: field type is Literal when an enum
|
||||
has only one possible value
|
||||
--use-one-literal-as-default
|
||||
Use one literal as default value for one literal field
|
||||
--set-default-enum-member
|
||||
Set enum members as default values for enum field
|
||||
--empty-enum-field-name EMPTY_ENUM_FIELD_NAME
|
||||
@@ -451,40 +450,7 @@ options:
|
||||
--version show version
|
||||
```
|
||||
|
||||
|
||||
## Implemented list
|
||||
### OpenAPI 3 and JsonSchema
|
||||
#### DataType
|
||||
- string (include patter/minLength/maxLenght)
|
||||
- number (include maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf/le/ge)
|
||||
- integer (include maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf/le/ge)
|
||||
- boolean
|
||||
- array
|
||||
- object
|
||||
|
||||
##### String Format
|
||||
- date
|
||||
- datetime
|
||||
- time
|
||||
- password
|
||||
- email
|
||||
- idn-email
|
||||
- uuid (uuid1/uuid2/uuid3/uuid4/uuid5)
|
||||
- ipv4
|
||||
- ipv6
|
||||
- ipv4-network
|
||||
- ipv6-network
|
||||
- hostname
|
||||
- decimal
|
||||
|
||||
#### Other schema
|
||||
- enum (as enum.Enum or typing.Literal)
|
||||
- allOf (as Multiple inheritance)
|
||||
- anyOf (as typing.Union)
|
||||
- oneOf (as typing.Union)
|
||||
- $ref ([http extra](#http-extra-option) is required when resolving $ref for remote files.)
|
||||
- $id (for [JSONSchema](https://json-schema.org/understanding-json-schema/structuring.html#the-id-property))
|
||||
|
||||
<a href="./supported-data-types.md" style="font-size: 2em; ">Click here to see supported input formats</a>
|
||||
|
||||
## Related projects
|
||||
### fastapi-code-generator
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Generate from JsonData
|
||||
# Generate from JSON Data
|
||||
|
||||
The codegen generate pydantic models from JSON Data
|
||||
This code generator can create pydantic models from JSON Data. Under the hood, the generator uses [GenSON](https://pypi.org/project/genson/) to create JSON Schema from your input. The generated schema is then processed the in the same manner as [JSON Schema input data](./jsonschema.md).
|
||||
|
||||
## Example
|
||||
|
||||
@@ -8,7 +8,7 @@ The codegen generate pydantic models from JSON Data
|
||||
$ datamodel-codegen --input pets.json --input-file-type json --output model.py
|
||||
```
|
||||
|
||||
`pets.json`:
|
||||
**pets.json**
|
||||
```json
|
||||
{
|
||||
"pets": [
|
||||
@@ -31,7 +31,7 @@ $ datamodel-codegen --input pets.json --input-file-type json --output model.py
|
||||
```
|
||||
|
||||
|
||||
`model.py`:
|
||||
**model.py**
|
||||
```py
|
||||
# generated by datamodel-codegen:
|
||||
# filename: pets.json
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Generate from JsonSchema
|
||||
# Generate from JSON Schema
|
||||
|
||||
The codegen generate pydantic models from JSON Schema
|
||||
The code generator can create pydantic models from JSON Schema. See more information about supported JSON Schema data types and features [here](./supported-data-types.md#openapi-3-and-json-schema).
|
||||
|
||||
## Example
|
||||
|
||||
@@ -8,7 +8,7 @@ The codegen generate pydantic models from JSON Schema
|
||||
$ datamodel-codegen --input person.json --input-file-type jsonschema --output model.py
|
||||
```
|
||||
|
||||
`person.json`:
|
||||
**person.json**
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
@@ -39,7 +39,7 @@ $ datamodel-codegen --input person.json --input-file-type jsonschema --output m
|
||||
```
|
||||
|
||||
|
||||
`model.py`:
|
||||
**model.py**
|
||||
```py
|
||||
# generated by datamodel-codegen:
|
||||
# filename: person.json
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Generate from OpenAPI
|
||||
|
||||
The codegen generate pydantic models from OpenAPI
|
||||
The code generator can create pydantic models from OpenAPI schema definitions, particularly using the data from the `schema` field.
|
||||
|
||||
## Example
|
||||
|
||||
@@ -164,7 +164,7 @@ components:
|
||||
</pre>
|
||||
</details>
|
||||
|
||||
`model.py`:
|
||||
**model.py**
|
||||
```py
|
||||
# generated by datamodel-codegen:
|
||||
# filename: api.yaml
|
||||
|
||||
@@ -1,23 +1,25 @@
|
||||
# Target Source files
|
||||
# Supported Input Formats
|
||||
|
||||
This code generator supports the following input formats:
|
||||
|
||||
- OpenAPI 3 (YAML/JSON, [OpenAPI Data Type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types))
|
||||
- JSON Schema ([JSON Schema Core](http://json-schema.org/draft/2019-09/json-schema-validation.html) /[JSON Schema Validation](http://json-schema.org/draft/2019-09/json-schema-validation.html))
|
||||
- JSON/YAML Data (it will be converted to JSON Schema)
|
||||
- Python dictionary (it will be converted to JSON Schema)
|
||||
|
||||
# Implemented list
|
||||
## Implemented data types and features
|
||||
|
||||
This codegen supports major data types to OpenAPI/JSON Schema
|
||||
Below are the data types and features recognized by datamodel-code-generator for OpenAPI 3 and JSON Schema.
|
||||
|
||||
## OpenAPI 3 and JsonSchema
|
||||
### DataType
|
||||
- string (include patter/minLength/maxLenght)
|
||||
- number (include maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf/le/ge)
|
||||
- integer (include maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf/le/ge)
|
||||
### Data Types
|
||||
- string (supported keywords: pattern/minLength/maxLength)
|
||||
- number (supported keywords: maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf)
|
||||
- integer (supported keywords: maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf)
|
||||
- boolean
|
||||
- array
|
||||
- object
|
||||
|
||||
#### String Format
|
||||
### String Formats
|
||||
- date
|
||||
- datetime
|
||||
- time
|
||||
@@ -36,4 +38,4 @@ This codegen supports major data types to OpenAPI/JSON Schema
|
||||
- anyOf (as typing.Union)
|
||||
- oneOf (as typing.Union)
|
||||
- $ref ([http extra](../#http-extra-option) is required when resolving $ref for remote files.)
|
||||
- $id (for [JSONSchema](https://json-schema.org/understanding-json-schema/structuring.html#the-id-property))
|
||||
- $id (for [JSONSchema](https://json-schema.org/understanding-json-schema/structuring.html#id)
|
||||
@@ -1,14 +1,14 @@
|
||||
# Using as module
|
||||
# Using datamode-code-generator as a Module
|
||||
|
||||
datamodel-code-generator is a CLI. But, it has another side as a python module.
|
||||
datamodel-code-generator is a CLI tool, but it can also be used as a module.
|
||||
|
||||
You can call this code-generator in your python code.
|
||||
|
||||
## How to use it as module
|
||||
|
||||
You can generate models with `datamodel_code_generator.generate` into a temporary directory.
|
||||
You can generate models with `datamodel_code_generator.generate` using parameters that match the [arguments provided to the CLI tool](./index.md#all-command-options). The generated files can be written to and read from the `Path` object supplied to *output*.
|
||||
|
||||
And, you can read files from the directory.
|
||||
In the below example, we use a file in a `TemporaryDirectory` to store our output.
|
||||
|
||||
### Installation
|
||||
```sh
|
||||
@@ -45,7 +45,7 @@ with TemporaryDirectory() as temporary_directory_name:
|
||||
print(model)
|
||||
```
|
||||
|
||||
The result of print(model)
|
||||
The result of `print(model)`:
|
||||
```python
|
||||
# generated by datamodel-codegen:
|
||||
# filename: example.json
|
||||
@@ -71,17 +71,10 @@ class Model(BaseModel):
|
||||
street_type: Optional[StreetType] = None
|
||||
```
|
||||
|
||||
## Why doesn't the function return str?
|
||||
## Why doesn't `datamodel_code_generator.generate` return a string?
|
||||
|
||||
If generated code are modular files then, str can't reproduce the structure of modules.
|
||||
The above example schema only generates a single python module, but a single schema may generate multiple modules. There is no way to represent these modules as a single string, so the `generate` method returns `None`.
|
||||
|
||||
Also, `TemporaryDirectory` and `Path` provide an easy way to read files.
|
||||
Note that the *output* parameter can take any `Path` object, which includes both file and directory paths. If a file name is provided and multiple modules are generated, `generate` will raise a `datamodel_code_gen.Error` exception.
|
||||
|
||||
There is an example when a generated model file is only one.
|
||||
|
||||
Otherwise, You should walk in a directory to find modular files.
|
||||
|
||||
|
||||
## Related projects
|
||||
|
||||
[fastapi-code-generator](https://github.com/koxudaxi/fastapi-code-generator) uses `datamodel-code-generator` as module to create models from OpenAPI.
|
||||
If multiple modules are generated, you will need to walk through the supplied *output* directory to find all of them.
|
||||
Reference in New Issue
Block a user