Skip to content

feat: warn on deprecated aliases ahead of their removal in 2.0 - #350

Merged
lesnik512 merged 1 commit into
mainfrom
deprecate-aliases
Oct 28, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
deprecate-aliases

Conversation

@lesnik512

Copy link
Copy Markdown
Member

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

Every old name still resolves to the same object, but accessing it now emits a DeprecationWarning that names the replacement and says 2.0 removes it:

Old name Where it warns Use instead
OpentelemetryConfig opentelemetry_instrument OpenTelemetryConfig
FreeBootstrapperConfig free_bootstrapper and lite_bootstrap FreeConfig
IGNORED_STRUCTLOG_ATTRIBUTES sentry_instrument logging_factory.STRUCTLOG_META_KEYS
AddressProtocol, RequestProtocol, ScopeType logging_factory and logging_instrument nothing
not_ready_message, check_dependencies on an instrument subclass at class creation not_configured_reason, dependencies_installed

How it works:

  • helpers.warn.deprecated_module_getattr builds each module's __getattr__. It goes through warn_at_caller, so the warning points at the user's import line rather than at lite-bootstrap.
  • Each alias keeps a typing.TYPE_CHECKING definition. Without it, a type checker would see only the module __getattr__ and lose the alias's type, which would be a typing regression in a minor release. I checked that ty still resolves every old name.
  • FreeBootstrapperConfig is gone from lite_bootstrap.__all__, and the protocols from logging_instrument.__all__, so from ... import * stays silent. A test covers that.
  • In logging_factory the protocols now live under private names, so they warn there as well and not only through the logging_instrument re-export.
  • BaseInstrument.__init_subclass__ warns only when it actually forwards a legacy name. With @dataclass(slots=True) the class gets created twice. By the second time the current name is already in the class dict, so the warning fires once.

tests/conftest.py: emulate_package_missing_with_module_reload wiped and restored only non-dunder globals. After a reload it put back the original OpenTelemetryConfig but kept the reloaded module's __getattr__, which still held the reloaded class, so the alias stopped being identical to its target. The helper now treats __getattr__ as module state.

Not in this PR: the AGENTS.md rule "a public rename ships a silent alias" is now out of date, and its worked example (OpentelemetryConfig) no longer matches. #323 owns that text.

Verified: 422 tests pass at 100% coverage, just lint is clean, and a script outside the package gets each warning on its own import line. No new warnings appear in the suite; the remaining 16 come from Litestar and FastAPI.

@lesnik512
lesnik512 merged commit d80ebc2 into main Oct 28, 2026
35 checks passed
@lesnik512
lesnik512 deleted the deprecate-aliases branch October 28, 2026 14:22
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