Skip to content

feat: rename inconsistent config fields, keeping the old names as deprecated aliases - #351

Merged
lesnik512 merged 2 commits into
mainfrom
rename-config-fields
Oct 28, 2026
Merged

lesnik512 merged 2 commits into
mainfrom
rename-config-fields

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Part of #318: the 1.x half. The 2.0 half, which deletes the old field names, stays open on the issue.

Nine config fields get consistent names. The old names keep working until 2.0, with a DeprecationWarning.

Config Old name New name
FastAPI, FastMCP prometheus_instrumentator_params prometheus_instrumentator_additional_params
FastAPI, FastMCP prometheus_instrument_params prometheus_instrument_additional_params
FastAPI prometheus_expose_params prometheus_expose_additional_params
Litestar swagger_extra_params swagger_additional_params
FastAPI fastapi_logging_middleware_enabled logging_access_log_enabled
Litestar litestar_logging_middleware_enabled logging_access_log_enabled
FastMCP fastmcp_logging_middleware_enabled logging_access_log_enabled

Every forwarded-kwargs escape hatch now ends in _additional_params, as four of them already did. The access-log flag has one name on the three HTTP configs and stays off LoggingConfig, because FastStream and Free mix that in and have no access log. litestar_logging_middleware_config keeps its prefix because it carries a Litestar type, and its warning now names the new flag.

How the aliases work:

  • Each old name is still a field on its config, defaulting to UNSET, with repr=False and compare=False. A class-level _renamed_fields map links it to its replacement.
  • BaseConfig.__post_init__ runs first in every config's cascade. If the caller set an old name, it copies the value into the new field, warns through warn_at_caller (so the warning points at the user's line), and resets the old field to UNSET. The reset keeps dataclasses.replace() working on a config built from an old name.
  • "Set" for the new field means "differs from its default". Old and new both set raises ConfigurationError. An old name plus the new one at its default value is taken as the old one.
  • from_dict and from_object read dataclasses.fields, so they accept the old keys too. A settings object that carries both names raises rather than silently picking one.
  • I put the forwarding in BaseConfig and not in a __post_init__ per config. FastMCP has no __post_init__ of its own, and the FastMCP tests that reload the module would break super(FastMcpConfig, self) on a config built from the pre-reload class. The forwarding calls dataclasses.fields() only when an old name is actually set, so building a config with the new names costs nothing extra.

Tests, written first: for each of the nine renames, the old name sets the new field and warns at the caller, old plus new raises, and from_dict accepts the old key. There are also tests for from_object with both names and for replace() after an old name. The existing tests, benchmark suites and docs now use the new names. swagger_additional_params was never documented, so the Swagger section of configuration.md gains a line for it.

Verified: 451 tests pass at 100% coverage, just lint is clean, and the suite emits no lite-bootstrap DeprecationWarning.

@lesnik512
lesnik512 merged commit bdf98ad into main Oct 28, 2026
35 checks passed
@lesnik512
lesnik512 deleted the rename-config-fields branch October 28, 2026 14:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant