Breaking Changes
Error Handling Changes
- Unmatched
--type-overrideskeys now emit aUserWarning- The--type-overridesoption (and thetype_overridesargument of the Python API and parsers) now checks every key after parsing. If any key names no generated model or field, it emits a singleUserWarningsuch as--type-overrides: 2 keys matched no generated model or field: 'Order.itme' (did you mean 'Order.item'?), 'Ordr' (did you mean 'Order'?). Where a close key exists, the warning suggests it, for example the class name a schema name was renamed to (ItemModel.priceforItem.price). The generated code does not change. Previously such keys were silently ignored, so runs that passed with no warnings can now print a warning on stderr. Callers that turn warnings into errors (-W error, pytestfilterwarnings = error) will now get an error. To fix it, correct or remove the keys the warning names. With--diff-against, the warning covers only the current input, not the baseline. (#6838) - Server and client targets raise
Errorfor a preset that does not fit the target Python version (experimental) - Whengenerate()runs with the experimentalgenerate_serverorgenerate_clienttarget and itspresetdoes not matchtarget_python_version, it now raisesdatamodel_code_generator.Errorwith the same message a model-only run gives. Before, it raiseddatamodel_code_generator.preset.PresetError, which is not a subclass ofError, so code that caughtPresetErroraround a target run no longer catches it and should catchdatamodel_code_generator.Errorinstead. The command line is unchanged. (#6864) - A new
UserWarningis emitted when an option is turned off but another option turns it back on ---use-annotatedturns on--field-constraints,--use-type-alias-typeturns on--use-type-aliasand--intersect-combined-schema-keywordsturns on--intersect-allof-keywords, including when a preset sets the first option or the output model type does (for example msgspec turning on--use-annotated). Previously, a run that turned the second option off kept it on without saying so. This happened with an argument such as--no-intersect-allof-keywords, withfalseinpyproject.toml, or withFalsepassed togenerate(). Now such a run emits aUserWarningthat names both options, says where the implying option came from, and explains how to turn both off. The generated code does not change, but callers that turn warnings into errors (for example-W erroror pytestfilterwarnings = error) now get an error for these combinations. The warning is not shown under--disable-warnings. It is also not emitted for apyproject.tomlvalue that a--presetargument replaces, foruse_type_aliaspassed togenerate(), or for values of a config returned byload_pyproject_config()(#6889) - A dataclass instance passed to
--input-modelnow fails with a clear error - Pointing--input-modelat an instance of a dataclass, for examplemodule:default_user, now reports'default_user' is not a supported type. Supported: dict, Pydantic v2 BaseModel, dataclass, TypedDict. In 0.96.0 it crashed with anAttributeError; pass the class (module:User) instead. - New
SchemaResourceRefWarningbefore fetching a document whose own$idends with an empty fragment - When a JSON Schema or OpenAPI document declares an$idending with an empty fragment and a$refin that same document names that URI or a pointer under it, the generator still fetches the document from that URL as in 0.96.0, but now warns first with aSchemaResourceRefWarning. The warning names the document, the URL and the written$id, and suggests--read-ids-with-empty-fragment. The generated output does not change. Callers that turn warnings into errors (for example-W errororwarnings.simplefilter("error")) now get an error instead of a successful run. To avoid it, pass--read-ids-with-empty-fragmentor write the$idwithout the trailing fragment marker (#6898) - New
UserWarningwhen a command-line argument turns off an option thatpyproject.tomlturned on - Withuse-annotated = trueandfield-constraints = falseinpyproject.toml, passing--no-use-annotatedturns--use-annotatedoff.--field-constraintsstays on, because the command line applies thepyproject.tomlvalues, and the option they imply, before the arguments. That was already the 0.96.0 behaviour, but such a run now emits aUserWarning:--field-constraints was turned off but stays on: use-annotated = true in pyproject.toml turns it on, which --no-use-annotated does not undo; use-annotated = false in pyproject.toml or --read-implied-options-from-merged-values turns it off. The generated output does not change. Callers that turn warnings into errors, for example with-W erroror pytestfilterwarnings = error, now fail. To avoid the warning, setuse-annotated = falseinpyproject.tomlinstead of passing--no-use-annotated, or pass--disable-warnings. You can also opt in to the new--read-implied-options-from-merged-values, under which the argument also turns--field-constraintsoff, which changes the output toconint. (#6911) - AsyncAPI client skip warnings reworded - In the experimental generated AsyncAPI client, a channel skipped because an AsyncAPI 2 operation's own HTTP binding declares
queryorheadersnow warnsthe query schema of its HTTP binding has no model(or theheadersequivalent) instead ofthe HTTP binding of an AsyncAPI 2 operation on it declares query, which no model types. Aqueryorheadersobject is now reported asis not an object of propertiesonly when the models type it as something other than an object, so some skip warnings disappear or change their text and tooling that matches these warning messages needs updating (#6958)
Code Generation Changes
- Generated AsyncAPI clients skip channels whose payload format generation does not read - With the experimental
--generate-client, a channel is now left out with amessage_content_typeswarning in two cases. The first is an AsyncAPI 2 message trait that gives aschemaFormatthe parser does not read, such asapplication/schema;version=draft-07. The client used to accept anyapplication/schemaorapplication/vnd.aai.asyncapispelling through a regex, and now codes only formats whose kind isasyncapi,jsonschemaoropenapi. The second is a messagecontentTypethat is not a valid media type but ends in+json, such asx+json, which is no longer treated as JSON. These channels used to be generated with a JSON codec, so their helpers are missing after regenerating. Write the format as the AsyncAPI specification lists it (application/schema+json;version=draft-07) and the content type as a real media type (application/x+json). (#6939) - Generated AsyncAPI clients now generate channels that were skipped or failed - With the experimental
--generate-client, some channels are now generated instead of being skipped asmessage_content_types. These are channels whose payload gives itsschemaFormatin another case or with spaces (application/SCHEMA+JSON;version=draft-07,application/schema+json ; version=draft-07), in an OpenAPI format (application/vnd.oai.openapi;version=3.0.0), or in such a spelling through an AsyncAPI 2 trait. Also, a payload written{schema: ...}without aschemaFormatnow binds the model generated for itsschema. Generation used to fail withThe use has no generated native typewhen it was the channel's only message, and the channel was skipped asseveral_messageswhen it sat beside another JSON message. A regenerated client gains helpers for these channels and loses their skip warnings. The numbered internal names after them shift, for exampleSOCKET_6becomesSOCKET_7inprotocols/_plans.pyandcodec_13becomescodec_14in_generated/model_bindings.py, so snapshot tests and committed generated clients change. (#6939) - Generated AsyncAPI clients carry binary-string JSON messages as raw bytes - This affects the experimental
--generate-clientfeature. A WebSocket channel message with a JSON content type whose payload is a binary string (type: string, format: binary) is now typed, sent and received as rawbytesin binary frames. Before, the payload's model encoded and decoded it in text frames. Code that passes or expects the model type for such channels must switch tobytes. Server-sent event channels still decode the event data with the model (#6957) - Generated AsyncAPI clients type some octet-stream and text messages as str instead of bytes - This affects the experimental
--generate-clientfeature. Two kinds of message are now typedstrand sent and received as UTF-8 text frames, where they werebytesin binary frames: anapplication/octet-streammessage whose payload is an enum of strings, and a text message whose binary-string payload the models type asstr(for example with--type-mappings binary=string). The send and receive types of the generated channel helpers change for these channels (#6957) - AsyncAPI client handshake parameters now follow the generated models - With the experimental
--generate-clienton AsyncAPI documents, the query and header parameters of a channel'sconnect(...)oropen(...)are now the fields of the models generated for its binding'squeryandheadersobjects, including inherited ones, and are required only where the models require them. Under--force-optionalevery handshake parameter is now optional, where it used to be required whenever the binding object required it. A parameter written as a$refnow takes thedescriptionof the schema it names in the generated helper. Some channels that used to be skipped with a warning are now generated and add new helpers to the client: channels whosequeryorheadersobject usesallOf, has keywords beside its properties (such as$schema,examples,default,minPropertiesordeprecated), or names a required property it does not declare, and AsyncAPI 2 operations whose HTTP binding comes from a trait undercomponents/operationTraits. With--force-optional, channels with a required header that the handshake writes itself, or with bindings that disagree on whether a parameter is required, are now generated as well (#6958) - AsyncAPI client subprotocols and server-sent event detection now use the values the models admit - In the experimental generated AsyncAPI client, a
Sec-WebSocket-Protocolheader written as aoneOfofconsts now offers each value as a subprotocol of the handshake. Before, such a header was not sent when optional and left the channel out when required, so an existing WebSocket helper now sends this header and expects the server to select one. An HTTP binding'sAcceptorContent-Typeheader whose type admits onlytext/event-streamnow marks the channel as a server-sent event stream, including when it is written as aoneOfof thatconstor inside aheadersobject that has other keywords beside its properties. As a result, a channel that nowsorwssserver serves can now be generated as an event stream helper instead of a WebSocket helper (#6958) - Generated AsyncAPI clients offer subprotocols from referenced unions of constants - With the experimental
--generate-clientoption, a WebSocket binding headerSec-WebSocket-Protocolwhose schema references a root model or type alias of a union ofLiterals (for example aoneOfof$refs toconstschemas) now offers each of those values as a subprotocol of the handshake, in order, and the server selects one. Before, an optional header like this offered no subprotocol and was not sent, and a required one left the channel out. Regenerated clients now send aSec-WebSocket-Protocolheader for such channels, and their channel plans carry the subprotocols (#6959) - AsyncAPI 2 client handshake parameters now ignore a sibling default beside
$refunder--ignore-ref-siblings-by-schema-version- This affects the experimental--generate-clientfeature. When--ignore-ref-siblings-by-schema-versionis set, a query or header parameter in an AsyncAPI 2 channel's WebSocket binding whose property writes adefaultnext to its$refno longer uses that sibling default as the argument default of the generatedconnect()helper. This matches the generated models, which also drop the sibling. The parameter now takes the default the referenced schema gives, or none. For example,token: str = 'abc'becomestoken: str | UNSET = UNSET, so callers that relied on the old implicit default must now pass the value explicitly. Without the option, the client keeps the sibling default as before. (#6973) - Colliding generated client and server names under
--parent-scoped-namingare prefixed instead of numbered - This affects the experimental--generate-clientand--generate-serverfeatures. When--parent-scoped-namingis used with--naming-strategy numbered,primary-firstordefinitions-first, a method, handler or class name that its scope already holds now gets the name of its enclosing scope in front of it instead of a number. For example,get_a_b_1becomesdefault_get_a_bandGetAB1becomesDefaultGetAB. The target names now apply theparent-prefixedrow on top of the strategy's row, as the models do. Code that calls the old numbered method names or imports the old numbered type names must be updated. Model class names do not change. (#6978) - Colliding generated client and server names under
--parent-scoped-namingwithfull-pathget both prefixes - This affects the experimental--generate-clientand--generate-serverfeatures. When--parent-scoped-namingis used with--naming-strategy full-path, a colliding method, handler or class name now gets both theparent-prefixedand thefull-pathprefixes, so the enclosing scope names appear twice. This matches what the models' class names already do under thelegacy-both-prefixesrow. For example,item_store_get_itembecomesitem_store_item_store_get_itemandItemStoreGetItemResponsebecomesItemStoreItemStoreGetItemResponse. The code shows thatenclosing-modelgets both prefixes in the same way. Code that uses the old single-prefixed names must be updated. (#6978)
What's Changed
- Type x-python-import pointer targets by the import under an option by @koxudaxi in #6806
- Type an x-python-import allOf by the import under request-response by @koxudaxi in #6807
- Don't split models on fields an import types under request-response by @koxudaxi in #6808
- Document reading pyproject.toml settings when calling generate() by @koxudaxi in #6812
- Document which options replace common post-processing by @koxudaxi in #6813
- Keep CLI notices at the package's call site by @koxudaxi in #6805
- Open marked or all enums on the project's own Enum base classes by @koxudaxi in #6824
- Write open enums without a base class as Literal joined with their type by @koxudaxi in #6825
- Infer union discriminators from tags under an option by @koxudaxi in #6826
- Read the Kubernetes schema extensions under an opt-in option by @koxudaxi in #6827
- Add --read-format-as-annotation to type values by their type keyword by @koxudaxi in #6828
- Add --untyped-value-type to write untyped values as one type by @koxudaxi in #6829
- Build a per-release upgrade guide from a declarative change list by @koxudaxi in #6830
- Require guide entries for accepted output changes and removals by @koxudaxi in #6831
- Prove upgrade guide claims by running the releases by @koxudaxi in #6832
- Build the upgrade guide and Kubernetes pages in the docs and CI by @koxudaxi in #6833
- Install msgspec in the release environments of behaviour records by @koxudaxi in #6823
- Show new warnings that are not deprecations in the upgrade guide by @koxudaxi in #6837
- Warn about --type-overrides keys that match nothing by @koxudaxi in #6838
- Read the members of a module from one function by @koxudaxi in #6843
- Read XSD value constraints and occurrence bounds in one place each by @koxudaxi in #6846
- Apply the implied options from the whole table at every stage by @koxudaxi in #6847
- Walk the allOf sources of schema validator rules in one function by @koxudaxi in #6856
- Create references through one allocation core in ModelResolver by @koxudaxi in #6857
- Find the ancestor that declares a property in one walk by @koxudaxi in #6859
- Hold the shared import bindings on the module import target by @koxudaxi in #6860
- Import the enum a Literal member names after a collapsed alias by @koxudaxi in #6861
- Decide the None a type hint writes in one function by @koxudaxi in #6862
- Read the JSON kind and equality of values from one rule each by @koxudaxi in #6863
- Resolve a preset once for generate(), targets and dynamic generation by @koxudaxi in #6864
- Read a union site and a variant's tag fields from one home each by @koxudaxi in #6870
- Read the constructs a field writes from its render plan by @koxudaxi in #6871
- Resolve the command line's options through the one resolver by @koxudaxi in #6872
- Read an inherited property's schema in the class order behind an option by @koxudaxi in #6873
- Compare JSON values by one key by @koxudaxi in #6887
- Read input model classes and their annotations through one reader by @koxudaxi in #6888
- Warn when an implied option replaces a value that was given by @koxudaxi in #6889
- Write no discriminator whose written tags two variants share by @koxudaxi in #6890
- Name Swagger 2.0 in the messages of the input type by @koxudaxi in #6893
- Refuse a dataclass instance named as the input model by @koxudaxi in #6894
- Keep the schema order of contains keywords beside a reference by @koxudaxi in #6895
- Refuse a root id that is not a string with a message by @koxudaxi in #6896
- Skip a $defs member that is not a schema where the draft allows it by @koxudaxi in #6897
- Read an $id with an empty fragment as its document behind an option by @koxudaxi in #6898
- Count repetitions and Unicode classes in the regex size check by @koxudaxi in #6899
- Read YAML 1.1-only numbers as text where a string is required by @koxudaxi in #6900
- Write Python literals and test Literal annotations by one rule each by @koxudaxi in #6901
- Check the relations between options from one table by @koxudaxi in #6902
- Write the discriminator of inlined list item unions as their site does by @koxudaxi in #6903
- Write no discriminator for a nested variant without its tag by @koxudaxi in #6904
- Report an invalid pyproject.toml as a configuration error by @koxudaxi in #6910
- Let an argument undo an option that pyproject.toml implied by @koxudaxi in #6911
- Read a variant's tag field as Pydantic collects it by @koxudaxi in #6912
- Parse the values of one allOf or union site once by @koxudaxi in #6916
- Change a module's member list through one store operation by @koxudaxi in #6917
- Read the render plan of a field through one accessor by @koxudaxi in #6919
- Bound more regex classes from below in the size check by @koxudaxi in #6920
- Read a one-letter property as a range start in a class by @koxudaxi in #6921
- Read a class escape at the end of a range in a class by @koxudaxi in #6929
- Read the value a JSON pointer names through one reader by @koxudaxi in #6930
- Run each parse of a generation through one attempt step by @koxudaxi in #6931
- Add the symbol imports of a field's call in one place by @koxudaxi in #6932
- Walk the children of a type node by one rule by @koxudaxi in #6938
- Read the client's parameter types and payload formats from one home by @koxudaxi in #6939
- Read a literal escape whole in a character class by @koxudaxi in #6940
- Read the subschema keywords of a raw document from one table by @koxudaxi in #6950
- Read a lone allOf reference in its own document behind an option by @koxudaxi in #6951
- Restore inherited field names of unique aliases in one pass by @koxudaxi in #6952
- Apply the target-implied settings as one recorded stage by @koxudaxi in #6953
- Read each input type's parser settings from one row by @koxudaxi in #6954
- Build the run values of a configuration in one place by @koxudaxi in #6955
- Spell the default OpenAPI scopes once by @koxudaxi in #6956
- Choose an AsyncAPI message codec from the bound payload by @koxudaxi in #6957
- Read AsyncAPI handshake parameters and fixed values from the models by @koxudaxi in #6958
- Decide whether each pass runs in the pipeline table by @koxudaxi in #6959 (fixes #6969: msgspec output no longer fails at import when a derived model collides with two or more required inherited fields)
- Know whether a field writes a call without building its plan by @koxudaxi in #6966
- Store a field's render parts once when render plans freeze by @koxudaxi in #6967
- Keep the base sites of each target once by @koxudaxi in #6968
- Build the null sources of a schema in one place by @koxudaxi in #6972
- Read the keywords a schema gives through its ref chain once by @koxudaxi in #6973
- Write the reference facts of a definition once by @koxudaxi in #6977
- Name models and targets by one naming-strategy table by @koxudaxi in #6978
- State the contribution policy for issues, pull requests and AI tools by @koxudaxi in #6980
Full Changelog: 0.96.0...0.97.0