github datamodel-code-generator/datamodel-code-generator 0.97.0

one hour ago

Breaking Changes

Error Handling Changes

  • Unmatched --type-overrides keys now emit a UserWarning - The --type-overrides option (and the type_overrides argument of the Python API and parsers) now checks every key after parsing. If any key names no generated model or field, it emits a single UserWarning such 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.price for Item.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, pytest filterwarnings = 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 Error for a preset that does not fit the target Python version (experimental) - When generate() runs with the experimental generate_server or generate_client target and its preset does not match target_python_version, it now raises datamodel_code_generator.Error with the same message a model-only run gives. Before, it raised datamodel_code_generator.preset.PresetError, which is not a subclass of Error, so code that caught PresetError around a target run no longer catches it and should catch datamodel_code_generator.Error instead. The command line is unchanged. (#6864)
  • A new UserWarning is emitted when an option is turned off but another option turns it back on - --use-annotated turns on --field-constraints, --use-type-alias-type turns on --use-type-alias and --intersect-combined-schema-keywords turns 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, with false in pyproject.toml, or with False passed to generate(). Now such a run emits a UserWarning that 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 error or pytest filterwarnings = error) now get an error for these combinations. The warning is not shown under --disable-warnings. It is also not emitted for a pyproject.toml value that a --preset argument replaces, for use_type_alias passed to generate(), or for values of a config returned by load_pyproject_config() (#6889)
  • A dataclass instance passed to --input-model now fails with a clear error - Pointing --input-model at an instance of a dataclass, for example module: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 an AttributeError; pass the class (module:User) instead.
  • New SchemaResourceRefWarning before fetching a document whose own $id ends with an empty fragment - When a JSON Schema or OpenAPI document declares an $id ending with an empty fragment and a $ref in 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 a SchemaResourceRefWarning. 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 error or warnings.simplefilter("error")) now get an error instead of a successful run. To avoid it, pass --read-ids-with-empty-fragment or write the $id without the trailing fragment marker (#6898)
  • New UserWarning when a command-line argument turns off an option that pyproject.toml turned on - With use-annotated = true and field-constraints = false in pyproject.toml, passing --no-use-annotated turns --use-annotated off. --field-constraints stays on, because the command line applies the pyproject.toml values, and the option they imply, before the arguments. That was already the 0.96.0 behaviour, but such a run now emits a UserWarning: --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 error or pytest filterwarnings = error, now fail. To avoid the warning, set use-annotated = false in pyproject.toml instead 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-constraints off, which changes the output to conint. (#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 query or headers now warns the query schema of its HTTP binding has no model (or the headers equivalent) instead of the HTTP binding of an AsyncAPI 2 operation on it declares query, which no model types. A query or headers object is now reported as is not an object of properties only 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 a message_content_types warning in two cases. The first is an AsyncAPI 2 message trait that gives a schemaFormat the parser does not read, such as application/schema;version=draft-07. The client used to accept any application/schema or application/vnd.aai.asyncapi spelling through a regex, and now codes only formats whose kind is asyncapi, jsonschema or openapi. The second is a message contentType that is not a valid media type but ends in +json, such as x+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 as message_content_types. These are channels whose payload gives its schemaFormat in 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 a schemaFormat now binds the model generated for its schema. Generation used to fail with The use has no generated native type when it was the channel's only message, and the channel was skipped as several_messages when 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 example SOCKET_6 becomes SOCKET_7 in protocols/_plans.py and codec_13 becomes codec_14 in _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-client feature. 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 raw bytes in 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 to bytes. 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-client feature. Two kinds of message are now typed str and sent and received as UTF-8 text frames, where they were bytes in binary frames: an application/octet-stream message whose payload is an enum of strings, and a text message whose binary-string payload the models type as str (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-client on AsyncAPI documents, the query and header parameters of a channel's connect(...) or open(...) are now the fields of the models generated for its binding's query and headers objects, including inherited ones, and are required only where the models require them. Under --force-optional every handshake parameter is now optional, where it used to be required whenever the binding object required it. A parameter written as a $ref now takes the description of 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 whose query or headers object uses allOf, has keywords beside its properties (such as $schema, examples, default, minProperties or deprecated), or names a required property it does not declare, and AsyncAPI 2 operations whose HTTP binding comes from a trait under components/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-Protocol header written as a oneOf of consts 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's Accept or Content-Type header whose type admits only text/event-stream now marks the channel as a server-sent event stream, including when it is written as a oneOf of that const or inside a headers object that has other keywords beside its properties. As a result, a channel that no ws or wss server 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-client option, a WebSocket binding header Sec-WebSocket-Protocol whose schema references a root model or type alias of a union of Literals (for example a oneOf of $refs to const schemas) 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 a Sec-WebSocket-Protocol header for such channels, and their channel plans carry the subprotocols (#6959)
  • AsyncAPI 2 client handshake parameters now ignore a sibling default beside $ref under --ignore-ref-siblings-by-schema-version - This affects the experimental --generate-client feature. When --ignore-ref-siblings-by-schema-version is set, a query or header parameter in an AsyncAPI 2 channel's WebSocket binding whose property writes a default next to its $ref no longer uses that sibling default as the argument default of the generated connect() 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' becomes token: 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-naming are prefixed instead of numbered - This affects the experimental --generate-client and --generate-server features. When --parent-scoped-naming is used with --naming-strategy numbered, primary-first or definitions-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_1 becomes default_get_a_b and GetAB1 becomes DefaultGetAB. The target names now apply the parent-prefixed row 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-naming with full-path get both prefixes - This affects the experimental --generate-client and --generate-server features. When --parent-scoped-naming is used with --naming-strategy full-path, a colliding method, handler or class name now gets both the parent-prefixed and the full-path prefixes, so the enclosing scope names appear twice. This matches what the models' class names already do under the legacy-both-prefixes row. For example, item_store_get_item becomes item_store_item_store_get_item and ItemStoreGetItemResponse becomes ItemStoreItemStoreGetItemResponse. The code shows that enclosing-model gets 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

Don't miss a new datamodel-code-generator release

NewReleases is sending notifications on new releases.