Skip to content

Type on_version_apply as a keyword-only Protocol - #1886

Closed
anish-yen wants to merge 4 commits into
sqlalchemy:mainfrom
anish-yen:fix-on-version-apply-kwargs
Closed

anish-yen wants to merge 4 commits into
sqlalchemy:mainfrom
anish-yen:fix-on-version-apply-kwargs

Conversation

@anish-yen

Copy link
Copy Markdown

Fixes: #1883

Summary

EnvironmentContext.configure(on_version_apply=...) is documented and invoked as a keyword-only callback (callback(ctx=..., step=..., heads=..., run_args=...) in alembic/runtime/migration.py), but OnVersionApplyFn was typed as a positional Callable. Type checkers therefore rejected valid keyword-only callbacks and accepted callbacks whose parameter names would fail at runtime.

Changes

  • alembic/runtime/environment.py: OnVersionApplyFn is now a typing.Protocol with keyword-only parameters ctx, step, heads, run_args, matching the documented contract.
  • alembic/context.pyi: regenerated with tools/write_pyi.py (Python 3.14).
  • tools/write_pyi.py: added alembic.runtime.environment. to TRIM_MODULE so the stub renders the bare name, consistent with the other module prefixes.
  • docs/build/unreleased/1883.rst: changelog entry.

Validation

  • mypy sample matrix (base vs. this branch): a keyword-only callback fails on base and passes here; a callback with mismatched parameter names passes on base (the bug) and is correctly rejected here; a conventional callback with matching names passes both.
  • tests/test_stubs.py passes under Python 3.14 (stub regeneration is byte-identical).
  • tests/test_script_consumption.py + tests/test_environment.py: 92 passed (sqlite), including the existing CallbackEnvironmentTest that asserts the keyword-argument invocation.
  • mypy ./alembic/ --exclude alembic/templates: no new errors (the 6 pre-existing noxfile.py untyped-decorator notes are identical on base).
  • black, zimports, flake8 clean on all changed files.

This contribution was prepared with AI assistance (Instinct agent on behalf of @anish-yen), including local test and type-check validation.

@sqla-tester

Copy link
Copy Markdown
Collaborator

Hi, and thanks for the pull request!

This project accepts pull requests only for issues that a maintainer has already marked with the open for pull requests label. That way we can settle on an approach before anyone spends time writing code.

This pull request references issue #1883, which hasn't been marked open for pull requests, so the change isn't authorized yet and I'm closing it automatically. Once a maintainer adds the label to #1883, reopen this pull request and it will stay open. If #1883 needs more detail before that can happen, a complete runnable example is usually the missing piece, and adding one to the issue is the fastest way to get there.

This is automatic and procedural. It isn't a judgment on your change, and nothing you've written here is lost.

Thanks for your interest in the project!

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.

on_version_apply is typed as a positional callable, but alembic calls it with keyword arguments

2 participants