Python & Pydantic Generation

Relevant source files

The following files were used as context for generating this wiki page:

• internal/translate/python/translator.go
• internal/translate/pydantic/translator.go
• internal/translate/python/translator_test.go
• internal/translate/pydantic/translator_test.go
• internal/translate/prepare_test.go
• cmd/gendocs/main.go

The Python and Pydantic generation system provides automated translation of JSON Schemas into idiomatic Python code. The system supports two primary output formats: standard Python 3.7+ dataclasses and Pydantic BaseModel definitions. These translators are part of the core translate package, enabling the project to generate strongly-typed data structures for various Python-based environments.

Sources: internal/translate/python/translator.go:21, internal/translate/pydantic/translator.go:22, cmd/gendocs/main.go:37-38

Architecture and Components

The translation logic is encapsulated in distinct Translator structs for both Python and Pydantic. Both follow a shared execution pattern: preparing schema data, managing imports, sorting fields, and executing embedded templates.

Core Translation Logic

The translation process follows a structured pipeline:

1. Preparation: The translate.Prepare function converts the raw JSON Schema into an intermediate translate.Data structure.
2. Dependency Analysis: The system checks for specific types (like datetime.datetime) to determine necessary module imports.
3. Field Optimization: Fields are sorted to ensure required fields appear before optional fields, complying with Python's argument default rules.
4. Templating: The final code is generated using Go's text/template engine with embedded .go.tmpl files.

Sources: internal/translate/python/translator.go:32-72, internal/translate/pydantic/translator.go:33-73

Workflow Diagram

The following diagram illustrates the flow from a JSON Schema to a generated Python file.

The process ensures that generated classes are valid Python syntax, specifically handling the requirement that fields with default values (optional fields) must follow fields without default values (required fields).

Sources: internal/translate/python/translator.go:53-62, internal/translate/pydantic/translator.go:54-63

Python Dataclass Generation

The standard Python translator generates classes decorated with @dataclasses.dataclass. This implementation focuses on using standard library features for data modeling.

Key Features

• Dataclass Support: Uses the @dataclasses.dataclass decorator for class definitions.
• Type Hinting: Implements Optional[T] for nullable fields and standard type hints (e.g., str, int, float, bool).
• Default Values: Optional fields are initialized with None.

Sources: internal/translate/python/translator_test.go:27-31, internal/translate/python/translator_test.go:121

Type Mapping Table

JSON Schema Type	Format	Python Type
string	-	str
string	date-time	datetime.datetime
string	date	datetime.date
integer	-	int
number	-	float
boolean	-	bool
array	-	list[T]

Sources: internal/translate/python/translator_test.go:48-52, internal/translate/python/translator_test.go:67-72, internal/translate/python/translator_test.go:102

Pydantic BaseModel Generation

The Pydantic translator targets data validation and settings management by inheriting from pydantic.BaseModel.

Functional Differences

• Validation: Generated classes inherit from BaseModel, providing runtime type validation.
• Import Management: Specifically handles from pydantic import BaseModel.
• Field Requirements: Required fields are defined without defaults, while optional fields use Optional[T] = None.

Sources: internal/translate/pydantic/translator_test.go:28, internal/translate/pydantic/translator_test.go:138, internal/translate/pydantic/translator_test.go:247

Implementation Example

The translator ensures that if a schema contains nested objects, they are extracted into separate classes to maintain a flat dependency structure.

The generator identifies nested definitions and produces separate class blocks, ensuring Address is defined before UserSchema to avoid forward reference issues.

Sources: internal/translate/pydantic/translator_test.go:109-114, internal/translate/pydantic/translator_test.go:142-147

Data Preparation and Resolution

The system utilizes an intermediate preparation layer that standardizes how JSON Schemas are processed across different translators.

Preparation Logic

The Prepare function (tested in prepare_test.go) handles:

• Root Name Formatting: Appending suffixes like _root or Schema to the port name.
• Topological Sorting: Definitions are sorted based on their dependencies so that referenced classes are defined before the classes that reference them.
• Inline Extraction: Objects defined inline within properties or arrays are extracted into their own named types.

Sources: internal/translate/prepare_test.go:49-51, internal/translate/prepare_test.go:106-110, internal/translate/prepare_test.go:217-221

Dependency Resolution Flow

Summary

The Python & Pydantic generation module enables the transformation of JSON Schema specifications into production-ready Python code. By utilizing a shared preparation layer, the system ensures consistent field ordering, proper topological sorting of dependencies, and accurate type mapping for both standard dataclasses and Pydantic models. This dual-translator approach allows users to choose between minimal standard library dependencies or robust runtime validation.

Sources: internal/translate/python/translator.go:25, internal/translate/pydantic/translator.go:26, internal/translate/prepare_test.go:110