[2ynn]

Why

Every generated Python model with optional or nullable fields has a wrap model_serializer. It rebuilds the output field by field from Pydantic's own dump and writes required fields, and nullable fields that were explicitly set, even when Pydantic left them out. A field that the caller filtered out therefore came back as None:

model = shared.FilteredFields(display_name="name", required_nullable=None)
model.model_dump(exclude={"display_name"})
# before: {'displayName': None, 'requiredNullable': None, 'kind': 'filtered', 'nullDefault': None, 'withDefault': 'fallback'}
# after:  {'requiredNullable': None, 'kind': 'filtered', 'nullDefault': None, 'withDefault': 'fallback'}

The same happened with include, exclude_unset and exclude_defaults, for required fields, const fields and nullable fields with a null default, including in nested models.

The write-back is needed in one case: request bodies are dumped with exclude_none=True, and must still send null for required fields and explicitly set nullable fields.

What changed

• Skipping filtered fields. The serializer skips a declared field that is absent from Pydantic's dump under both its API name and its Python name, unless the dump uses exclude_none. Both spellings are checked because a nested model's serializer also runs on its own earlier output, which is keyed by API name.

• Reading exclude_none without changing serialize_model's signature. Pydantic only passes info to a serializer whose signature requires it, and subclasses that override serialize_model and delegate with super().serialize_model(handler) must keep working. The generated code is now:

  @model_serializer(mode="wrap")
  def _serialize_model_with_info(self, handler, info):
      return serialize_with_info(self.serialize_model, handler, info)
  
  def serialize_model(self, handler):
      ...
      exclude_none = current_exclude_none()

  serialize_with_info and current_exclude_none live in types/basemodel.py. They hold info.exclude_none in a context variable for the duration of the call. serialize_model keeps its (self, handler) signature and skips filtered fields only when exclude_none is False. When serialize_model is called directly, the value is None and the output matches the previous serializer, apart from the empty-alias fix below.

• The read expression and the additional-properties handling are unchanged, so JSON request bodies are unchanged: marshal_json always dumps with exclude_none=True, where the new skip never runs, and it is the only model dump the SDK runtime performs.

• Fields whose API name is the empty string. Multipart file models declare their content field with alias="". The serializer computed the API name as f.alias or n, so it looked for content while Pydantic's by-alias output holds "". With by_alias=True this was already broken: the value was lost and written back as None ({'fileName': 'a', 'content': None, 'Content-Type': None}), and with the skip above the field would have disappeared entirely. The API name is now f.alias if f.alias is not None else n, so the value is kept under "" in model_dump(), model_dump(by_alias=True) and marshal_json. Plain model_dump() previously kept it under content; it now uses "", like every other field uses its API name. Multipart requests are serialized from field metadata, not from these dumps, and the multipart upload tests pass unchanged.

• Review SDK: each of the 66 wrap serializers gains _serialize_model_with_info, the current_exclude_none() read, the skip lines and the new API-name line; types/basemodel.py and types/__init__.py gain the two helpers; gen.lock changes.

Known limitations

• A dump that combines exclude_none=True with include, exclude, exclude_unset or exclude_defaults can still write excluded required fields back as None. The serializer cannot tell a field dropped for being None from one dropped by another filter, and request bodies rely on the former.
• A subclass override decorated with @model_serializer that takes only (self, handler) and delegates with super().serialize_model(handler) gets the previous output, filtered fields included, because it never receives info; when the model is dumped as part of another generated model, the enclosing serializer's exclude_none applies and the filtering works. Declaring info and delegating with serialize_with_info(super().serialize_model, handler, info) restores the filtering. Overrides without the decorator keep the filtering.
• A field excluded from the dump is still written when an additional property uses the field's other spelling (display_name next to displayName).

Test coverage

New model-dump-filters primary fragment: FilteredFields (required renamed field, required and optional nullable fields, a defaulted field, a nullable field with a null default, a const field, a nested copy and an array of copies), FilteredFieldsWithAdditionalProperties, and an error response whose body nests FilteredFields.

test_model_dump_filters_additional.py (19 tests) covers:

• include, exclude, exclude_unset and exclude_defaults, top level and nested;
• the exclude_none limitation above;
• default model_dump() / model_dump_json() of nested models and TypeAdapter(List[...]) of model lists keeping API names;
• request bodies: explicit nulls (top level and nested), a required nullable field, an omitted null additional property, an additional property under a field's Python name, and a top-level None body;
• error-data models, which have no wrap serializer: plain Pydantic filtering, and exclude honoured by the nested model;
• a field with an empty API name (BinaryString.content) keeping its value, and staying out when excluded;
• subclass overrides of serialize_model: a decorated two-argument override delegating with super(), and an undecorated override keeping exclude.

Testing

• TARGET=primary make test-pythonv2: 701 passed, including the multipart upload tests.
• TARGET=secondary make test-pythonv2: 264 passed, 1 skipped.
• TARGET=tertiary make test-pythonv2: 214 passed, 1 skipped.
• TARGET=quaternary make test-pythonv2: 248 passed, 1 skipped.
• TARGET=review make test-pythonv2: 36 passed, 6 skipped; regenerating the review SDK on main produces no further diff.
• pyright and mypy pass on the generated primary SDK.

Stack

1. fix(python): serialize unrecognized open enum values #145: unrecognized enum serialization (merged)
2. This PR: honour include/exclude filters in model dumps
3. feat(python): add preserveUnknownFields option #146: preserveUnknownFields
4. feat(python): add modelSerializationMethods option #147: modelSerializationMethods

Public-safety check

• This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
• Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
• Generated fixtures and review SDK changes are public-safe.
• I reviewed git diff --check.

[cubic-dev-ai]

All reported issues were addressed across 55 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[speakeasy-generator-bot]

Generator Snapshot Testing

Selector(s)	Result	Summary
snapshot-python	✅	Snapshot run completed

Snapshot results: https://github.com/speakeasy-api/openapi-generation-snapshots/issues/136#issuecomment-6449573495

Snapshot results are summarized above. Additional run context is linked for maintainers with access.

[cubic-dev-ai]

0 issues found across 52 reviewed files. 1 file intentionally excluded from review.

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Fixes generated Python model serializers to honour include/exclude/exclude_unset/exclude_defaults by skipping absent fields unless exclude_none, and corrects empty-alias handling. Bounded template/generated-code bug fix with new tests; request-body dumps remain unchanged.
Tip: Get a Slack DM when cubic finishes reviewing your PRs. Connect Slack

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[TristanSpeakEasy]

The filtering fix looks good. Left one non-blocking comment on compatibility with existing serializer overrides, worth sorting before you merge.

[cubic-dev-ai]

All reported issues were addressed

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>