Skip to content

Commit 52a963e

Browse files
koxudaxikoxudaxi
committed
Add CLI topic pages
1 parent 0f09aee commit 52a963e

8 files changed

Lines changed: 520 additions & 0 deletions

File tree

‎docs/cli-reference/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,17 @@ This documentation is auto-generated from test cases.
1818
| ⚙️ [General Options](general-options.md) | 18 | Utilities and meta options |
1919
| 📝 [Utility Options](utility-options.md) | 10 | Help, version, debug options |
2020

21+
## 🎯 Focused Topics
22+
23+
Use these pages when you know the workflow area but not the exact option name.
24+
25+
| Topic | Options | Groups |
26+
|-------|---------|--------|
27+
| [Model Customization](topics/model-customization.md) | 23 | Model Naming, Model Reuse, Model Shape, Root Model |
28+
| [Template Customization](topics/template-customization.md) | 19 | Custom Templates, Generated Output, Imports, Output Formatting |
29+
| [Typing Customization](topics/typing-customization.md) | 20 | Imports, Collection Types, Type Alias, Type Mapping, Type Syntax |
30+
| [OpenAPI](topics/openapi.md) | 7 | OpenAPI Naming, OpenAPI Paths, OpenAPI Scopes, Read Only Write Only |
31+
2132
## All Options
2233

2334
**Jump to:** [A](#a) · [B](#b) · [C](#c) · [D](#d) · [E](#e) · [F](#f) · [G](#g) · [H](#h) · [I](#i) · [K](#k) · [L](#l) · [M](#m) · [N](#n) · [O](#o) · [P](#p) · [R](#r) · [S](#s) · [T](#t) · [U](#u) · [V](#v) · [W](#w)

‎docs/cli-reference/topics/model-customization.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Model Customization
2+
3+
Choose model class shape, naming, reuse, and root-model behavior.
4+
5+
Options are grouped from shared CLI metadata and link back to their generated reference sections.
6+
7+
## Groups
8+
9+
| Group | Options | Description |
10+
|-------|---------|-------------|
11+
| [Model Naming](#model-naming) | 9 | Class names, suffixes, prefixes, and duplicate-name behavior. |
12+
| [Model Reuse](#model-reuse) | 4 | Schema deduplication and shared generated modules. |
13+
| [Model Shape](#model-shape) | 6 | Output model family and compatibility targets. |
14+
| [Root Model](#root-model) | 4 | Root model creation, collapse, and alias behavior. |
15+
16+
## Model Naming {#model-naming}
17+
18+
Class names, suffixes, prefixes, and duplicate-name behavior.
19+
20+
| Option | Description |
21+
|--------|-------------|
22+
| [`--allow-leading-underscore-class-name`](../model-customization.md#allow-leading-underscore-class-name) | Allow an explicitly specified root class name to start with an underscore. |
23+
| [`--class-name`](../model-customization.md#class-name) | Override the auto-generated class name with a custom name. |
24+
| [`--class-name-affix-scope`](../model-customization.md#class-name-affix-scope) | Control which classes receive the prefix/suffix. |
25+
| [`--class-name-prefix`](../model-customization.md#class-name-prefix) | Add a prefix to all generated class names. |
26+
| [`--class-name-suffix`](../model-customization.md#class-name-suffix) | Add a suffix to all generated class names. |
27+
| [`--duplicate-name-suffix`](../model-customization.md#duplicate-name-suffix) | Customize suffix for duplicate model names. |
28+
| [`--model-name-map`](../model-customization.md#model-name-map) | Rename generated model classes from a JSON mapping. |
29+
| [`--naming-strategy`](../model-customization.md#naming-strategy) | Use parent-prefixed naming strategy for duplicate model names. |
30+
| [`--parent-scoped-naming`](../model-customization.md#parent-scoped-naming) | Namespace models by their parent scope to avoid naming conflicts. |
31+
32+
## Model Reuse {#model-reuse}
33+
34+
Schema deduplication and shared generated modules.
35+
36+
| Option | Description |
37+
|--------|-------------|
38+
| [`--collapse-reuse-models`](../model-customization.md#collapse-reuse-models) | Collapse duplicate models by replacing references instead of inheritance. |
39+
| [`--reuse-model`](../model-customization.md#reuse-model) | Reuse identical model definitions instead of generating duplicates. |
40+
| [`--reuse-scope`](../model-customization.md#reuse-scope) | Scope for model reuse detection (root or tree). |
41+
| [`--shared-module-name`](../general-options.md#shared-module-name) | Customize the name of the shared module for deduplicated models. |
42+
43+
## Model Shape {#model-shape}
44+
45+
Output model family and compatibility targets.
46+
47+
| Option | Description |
48+
|--------|-------------|
49+
| [`--base-class`](../model-customization.md#base-class) | Specify a custom base class for generated models. |
50+
| [`--base-class-map`](../model-customization.md#base-class-map) | Specify different base classes for specific models via JSON mapping. |
51+
| [`--output-model-type`](../model-customization.md#output-model-type) | Select the output model type (Pydantic v2, Pydantic v2 dataclass, dataclasses, T... |
52+
| [`--target-pydantic-version`](../model-customization.md#target-pydantic-version) | Target Pydantic version for generated code compatibility. |
53+
| [`--target-python-version`](../model-customization.md#target-python-version) | Target Python version for generated code syntax and imports. |
54+
| [`--use-generic-base-class`](../model-customization.md#use-generic-base-class) | Generate a shared base class with model configuration to avoid repetition (DRY). |
55+
56+
## Root Model {#root-model}
57+
58+
Root model creation, collapse, and alias behavior.
59+
60+
| Option | Description |
61+
|--------|-------------|
62+
| [`--collapse-root-models`](../model-customization.md#collapse-root-models) | Inline root model definitions instead of creating separate wrapper classes. |
63+
| [`--collapse-root-models-name-strategy`](../model-customization.md#collapse-root-models-name-strategy) | Select which name to keep when collapsing root models with object references. |
64+
| [`--skip-root-model`](../model-customization.md#skip-root-model) | Skip generation of root model when schema contains nested definitions. |
65+
| [`--use-root-model-sequence-interface`](../model-customization.md#use-root-model-sequence-interface) | Make non-null sequence-like Pydantic v2 RootModel classes implement collections.... |

‎docs/cli-reference/topics/openapi.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# OpenAPI
2+
3+
Handle OpenAPI operation naming, path selection, scopes, and readOnly/writeOnly behavior.
4+
5+
Options are grouped from shared CLI metadata and link back to their generated reference sections.
6+
7+
## Groups
8+
9+
| Group | Options | Description |
10+
|-------|---------|-------------|
11+
| [OpenAPI Naming](#openapi-naming) | 2 | Operation and response model naming. |
12+
| [OpenAPI Paths](#openapi-paths) | 2 | Path selection and path parameter output. |
13+
| [OpenAPI Scopes](#openapi-scopes) | 1 | OpenAPI generation scopes. |
14+
| [Read Only Write Only](#read-only-write-only) | 2 | readOnly/writeOnly model behavior. |
15+
16+
## OpenAPI Naming {#openapi-naming}
17+
18+
Operation and response model naming.
19+
20+
| Option | Description |
21+
|--------|-------------|
22+
| [`--use-operation-id-as-name`](../openapi-only-options.md#use-operation-id-as-name) | Use OpenAPI operationId as the generated function/class name. |
23+
| [`--use-status-code-in-response-name`](../openapi-only-options.md#use-status-code-in-response-name) | Include HTTP status code in response model names. |
24+
25+
## OpenAPI Paths {#openapi-paths}
26+
27+
Path selection and path parameter output.
28+
29+
| Option | Description |
30+
|--------|-------------|
31+
| [`--include-path-parameters`](../openapi-only-options.md#include-path-parameters) | Include OpenAPI path parameters in generated parameter models. |
32+
| [`--openapi-include-paths`](../openapi-only-options.md#openapi-include-paths) | Filter OpenAPI paths to include in model generation. |
33+
34+
## OpenAPI Scopes {#openapi-scopes}
35+
36+
OpenAPI generation scopes.
37+
38+
| Option | Description |
39+
|--------|-------------|
40+
| [`--openapi-scopes`](../openapi-only-options.md#openapi-scopes) | Specify OpenAPI scopes to generate (schemas, paths, parameters). |
41+
42+
## Read Only Write Only {#read-only-write-only}
43+
44+
readOnly/writeOnly model behavior.
45+
46+
| Option | Description |
47+
|--------|-------------|
48+
| [`--read-only-write-only-model-type`](../openapi-only-options.md#read-only-write-only-model-type) | Generate separate request and response models for readOnly/writeOnly fields. |
49+
| [`--use-frozen-field`](../model-customization.md#use-frozen-field) | Generate frozen (immutable) field definitions for readOnly properties. |

‎docs/cli-reference/topics/template-customization.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Template Customization
2+
3+
Tune generated file headers, imports, decorators, templates, and formatting.
4+
5+
Options are grouped from shared CLI metadata and link back to their generated reference sections.
6+
7+
## Groups
8+
9+
| Group | Options | Description |
10+
|-------|---------|-------------|
11+
| [Custom Templates](#custom-templates) | 3 | Custom templates and extra template data. |
12+
| [Generated Output](#generated-output) | 7 | Generated file headers and reproducible output. |
13+
| [Imports](#imports) | 4 | Generated imports and type-checking import behavior. |
14+
| [Output Formatting](#output-formatting) | 5 | Formatter selection, quote style, and string wrapping. |
15+
16+
## Custom Templates {#custom-templates}
17+
18+
Custom templates and extra template data.
19+
20+
| Option | Description |
21+
|--------|-------------|
22+
| [`--custom-template-dir`](../template-customization.md#custom-template-dir) | Use custom Jinja2 templates for model generation. |
23+
| [`--extra-template-data`](../template-customization.md#extra-template-data) | Pass custom template variables via inline JSON or a JSON file path. |
24+
| [`--validators`](../template-customization.md#validators) | Add custom field validators to generated Pydantic v2 models. |
25+
26+
## Generated Output {#generated-output}
27+
28+
Generated file headers and reproducible output.
29+
30+
| Option | Description |
31+
|--------|-------------|
32+
| [`--class-decorators`](../template-customization.md#class-decorators) | Add custom decorators to generated model classes. |
33+
| [`--custom-file-header`](../template-customization.md#custom-file-header) | Add custom header text to the generated file. |
34+
| [`--custom-file-header-path`](../template-customization.md#custom-file-header-path) | Add custom header content from file to generated code. |
35+
| [`--disable-timestamp`](../template-customization.md#disable-timestamp) | Disable timestamp in generated file header for reproducible output. |
36+
| [`--enable-command-header`](../template-customization.md#enable-command-header) | Include command-line options in file header for reproducibility. |
37+
| [`--enable-generated-header-marker`](../template-customization.md#enable-generated-header-marker) | Include the @generated marker in file header for generated-code tooling. |
38+
| [`--enable-version-header`](../template-customization.md#enable-version-header) | Include tool version information in file header. |
39+
40+
## Imports {#imports}
41+
42+
Generated imports and type-checking import behavior.
43+
44+
| Option | Description |
45+
|--------|-------------|
46+
| [`--additional-imports`](../template-customization.md#additional-imports) | Add custom imports to generated output files. |
47+
| [`--no-use-type-checking-imports`](../template-customization.md#no-use-type-checking-imports) | Keep generated model imports available at runtime when using Ruff fixes. |
48+
| [`--use-exact-imports`](../template-customization.md#use-exact-imports) | Import exact types instead of modules. |
49+
| [`--use-type-checking-imports`](../template-customization.md#use-type-checking-imports) | Allow Ruff to move typing-only imports into TYPE_CHECKING blocks. |
50+
51+
## Output Formatting {#output-formatting}
52+
53+
Formatter selection, quote style, and string wrapping.
54+
55+
| Option | Description |
56+
|--------|-------------|
57+
| [`--custom-formatters`](../template-customization.md#custom-formatters) | Apply custom Python code formatters to generated output. |
58+
| [`--custom-formatters-kwargs`](../template-customization.md#custom-formatters-kwargs) | Pass custom arguments to custom formatters via inline JSON or a JSON file path. |
59+
| [`--formatters`](../template-customization.md#formatters) | Specify code formatters to apply to generated output. |
60+
| [`--use-double-quotes`](../template-customization.md#use-double-quotes) | Use double quotes for string literals in generated code. |
61+
| [`--wrap-string-literal`](../template-customization.md#wrap-string-literal) | Wrap long string literals across multiple lines. |

‎docs/cli-reference/topics/typing-customization.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Typing Customization
2+
3+
Control Python annotation syntax, collection types, imports, and type mappings.
4+
5+
Options are grouped from shared CLI metadata and link back to their generated reference sections.
6+
7+
## Groups
8+
9+
| Group | Options | Description |
10+
|-------|---------|-------------|
11+
| [Imports](#imports) | 1 | Generated imports and type-checking import behavior. |
12+
| [Collection Types](#collection-types) | 5 | Collection and tuple/set generation. |
13+
| [Type Alias](#type-alias) | 2 | TypeAlias and root-model alias output. |
14+
| [Type Mapping](#type-mapping) | 9 | Scalar, date/time, and custom type mapping. |
15+
| [Type Syntax](#type-syntax) | 3 | Modern annotation syntax and Annotated usage. |
16+
17+
## Imports {#imports}
18+
19+
Generated imports and type-checking import behavior.
20+
21+
| Option | Description |
22+
|--------|-------------|
23+
| [`--disable-future-imports`](../typing-customization.md#disable-future-imports) | Prevent automatic addition of __future__ imports in generated code. |
24+
25+
## Collection Types {#collection-types}
26+
27+
Collection and tuple/set generation.
28+
29+
| Option | Description |
30+
|--------|-------------|
31+
| [`--no-use-standard-collections`](../typing-customization.md#no-use-standard-collections) | Use typing.Dict/List instead of built-in dict/list for container types. |
32+
| [`--use-generic-container-types`](../typing-customization.md#use-generic-container-types) | Use generic container types (Sequence, Mapping) for type hinting. |
33+
| [`--use-standard-collections`](../typing-customization.md#use-standard-collections) | Use built-in dict/list instead of typing.Dict/List. |
34+
| [`--use-tuple-for-fixed-items`](../typing-customization.md#use-tuple-for-fixed-items) | Generate tuple types for arrays with items array syntax. |
35+
| [`--use-unique-items-as-set`](../typing-customization.md#use-unique-items-as-set) | Generate set types for arrays with uniqueItems constraint. |
36+
37+
## Type Alias {#type-alias}
38+
39+
TypeAlias and root-model alias output.
40+
41+
| Option | Description |
42+
|--------|-------------|
43+
| [`--use-root-model-type-alias`](../typing-customization.md#use-root-model-type-alias) | Generate RootModel as type alias format for better mypy support. |
44+
| [`--use-type-alias`](../typing-customization.md#use-type-alias) | Use TypeAlias instead of root models for type definitions (experimental). |
45+
46+
## Type Mapping {#type-mapping}
47+
48+
Scalar, date/time, and custom type mapping.
49+
50+
| Option | Description |
51+
|--------|-------------|
52+
| [`--output-date-class`](../typing-customization.md#output-date-class) | Specify date class type for date schema fields. |
53+
| [`--output-datetime-class`](../typing-customization.md#output-datetime-class) | Specify datetime class type for date-time schema fields. |
54+
| [`--strict-types`](../typing-customization.md#strict-types) | Enable strict type validation for specified Python types. |
55+
| [`--type-mappings`](../typing-customization.md#type-mappings) | Override default type mappings for schema formats. |
56+
| [`--type-overrides`](../typing-customization.md#type-overrides) | Replace schema model types with custom Python types via JSON mapping. |
57+
| [`--use-decimal-for-multiple-of`](../typing-customization.md#use-decimal-for-multiple-of) | Generate Decimal types for fields with multipleOf constraint. |
58+
| [`--use-object-type`](../typing-customization.md#use-object-type) | Use object instead of Any for unspecified object and array values. |
59+
| [`--use-pendulum`](../typing-customization.md#use-pendulum) | Use pendulum types for date, time, and duration fields. |
60+
| [`--use-standard-primitive-types`](../typing-customization.md#use-standard-primitive-types) | Use Python standard library types for string formats instead of str. |
61+
62+
## Type Syntax {#type-syntax}
63+
64+
Modern annotation syntax and Annotated usage.
65+
66+
| Option | Description |
67+
|--------|-------------|
68+
| [`--no-use-union-operator`](../typing-customization.md#no-use-union-operator) | Use Union\[X, Y\] / Optional\[X\] instead of X \| Y union operator. |
69+
| [`--use-annotated`](../typing-customization.md#use-annotated) | Use typing.Annotated for Field() with constraints. |
70+
| [`--use-union-operator`](../typing-customization.md#use-union-operator) | Use \| operator for Union types (PEP 604). |

0 commit comments

Comments
 (0)