$ show openapi-generators/openapi-python-client
This repository is a CLI tool and Python library that generates modern, typed Python HTTP client libraries from OpenAPI 3.0 and 3.1 specifications. The system parses an OpenAPI document (YAML or JSON), validates it against Pydantic models of the OpenAPI schema, and then converts the parsed structure into an internal representation of endpoints, models, and properties. Using Jinja2 templates, it generates a complete Python package with attrs-based model classes, httpx-based sync/async endpoint functions, a Client class with authentication support, and packaging metadata (Poetry, PDM, uv, or setup.py). The generated code is fully typed and includes serialization/deserialization methods, error handling, and support for complex OpenAPI features like allOf, oneOf, discriminated unions, enums, circular references, and custom content types. The architecture is a monolithic Python package with clear separation of concerns: a CLI entry point (typer), a configuration system (YAML/JSON config files with class overrides), a parser module that converts OpenAPI schemas into a property type hierarchy (StringProperty, IntProperty, UnionProperty, ModelProperty, etc.), and a template rendering engine. The parser uses a protocol-based design for property types, making it extensible. The system also includes a vendored copy of the openapi-schema-pydantic library for schema validation. Security is a key concern, with features like UntrustedString to prevent code injection in generated output and fuzz testing that generates random OpenAPI documents with dangerous strings. The project has extensive testing: unit tests for all parser components, end-to-end snapshot tests using golden records, functional tests that execute the generated code, integration tests against a live test server, and property-based fuzz testing. The generated client libraries are production-ready, using modern Python features like `from __future__ import annotations`, `|` union syntax, StrEnum/IntEnum, and the UNSET sentinel for optional fields. The tool is configurable via CLI flags and config files, supporting custom templates, post-generation hooks, and various packaging backends.
The LLM identified 4 files worth highlighting for reuse:
Provides a collection of string transformation and escaping functions (snakecase, pascalcase, safe_for_docstring, in_f_string_literal, in_double_quote_literal, remove_string_escapes) that are critical for safely embedding user-controlled OpenAPI strings into generated Python code. The functions are designed to prevent code injection (e.g., f-string injection, docstring breakage) and are used throughout the template system. This module is self-contained, has no internal dependencies beyond standard library, and could be extracted as a standalone utility library for any code generation project that needs to safely interpolate untrusted strings into Python source code.
Defines the PropertyProtocol, a Python Protocol class that establishes a standard interface for all property types in the parser. It specifies methods like build (classmethod), convert_value, get_type_string, get_imports, and attributes like string_type, template. This protocol enables the parser to treat all property types polymorphically, and new property types can be added by implementing this protocol. The module is small, self-contained, and demonstrates a clean use of Python's structural subtyping. It could be extracted as a pattern for any system that needs an extensible type hierarchy with a common interface.
Implements an UntrustedString Pydantic type that wraps raw strings from OpenAPI documents. In Python mode, it stores the original string; in JSON mode, it serializes to the raw string. This prevents accidental direct use of user-controlled strings in generated code, forcing explicit escaping via the strings module. The type also includes a Ref variant for handling $ref strings. This is a reusable security pattern for any code generation tool that processes untrusted input, and the module has no internal dependencies beyond pydantic.
Contains the merge_properties function that implements the logic for merging OpenAPI allOf schemas into a single property. It handles merging of same-type properties (e.g., two string properties with different constraints), enum merging, numeric merging, and string+format merging. It also manages attribute overrides and produces a merged property with combined constraints. This is a non-trivial algorithm that could be reused in any schema merging or inheritance resolution system, and it is isolated enough to be extracted with minimal changes.