Skip to content

fix: support builtin generic binding annotations in worker runtimes - #1952

Draft
hallvictoria wants to merge 4 commits into
devfrom
hallvictoria/pep585-binding-annotations
Draft

hallvictoria wants to merge 4 commits into
devfrom
hallvictoria/pep585-binding-annotations

Conversation

@hallvictoria

@hallvictoria hallvictoria commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Description

Companion worker/runtime change for Azure/azure-functions-python-library#378.

The SDK can validate PEP 585 binding annotations, but registration currently rejects builtin aliases such as list[EventHubEvent] and the inner list[str] in Out[list[str]] before reaching the SDK converter. Explicit output return annotations have a separate class-only gate.

Changes

  • Use standard-library typing.get_origin() / typing.get_args() in the legacy worker and both runtime libraries.
  • Preserve complete aliases, including element and union-element annotations, when delegating to SDK converters and storing ParamTypeInfo.
  • Remove obsolete nested-annotation tuple reconstruction.
  • Apply the same class/alias admission rule to explicit output return annotations; reject bare/parameterized Out as return annotations.
  • Continue rejecting raw top-level tuple, union, Callable, ClassVar, Annotated, Literal, and unresolved non-type annotations at the registry boundary. The normal loader may resolve forward references or strip Annotated before this boundary.
  • Preserve output-direction and malformed-Out checks.
  • Guard generic fallback and HTTP type checks against unsupported aliases, and include full generic annotations in load errors.
  • Add 157 regression cases per implementation (471 when exercising all three), with converter spies isolating worker delegation from the installed SDK version. Generic fallback and HTTP guard tests use the real implementation.
  • Include the shared runtime regression tests in the existing Python 3.13/3.14 proxy CI invocation; older Python jobs already collect the legacy-worker test directory.

Release dependency / why draft

SDK dependency rollout is outstanding. End-to-end tests used the SDK wheel built from PR378 commit 10b47abe2b4ebd3ba7d607ecb5b5f2e59a89d26a. This PR does not invent an unreleased SDK version or change dependency pins prematurely. Full builtin-alias support requires a compatible SDK release and subsequent dependency updates. Supporting the older Python worker routes also needs the corresponding SDK 1.x changes/release. The three unused vendored typing-inspection modules and their dedicated tests have been removed, along with the empty legacy helper package and stale lint/type-check/coverage exclusions. Frozen dependency-isolation SDK fixtures retain their own required helper copies.

Validation

New regression tests

Python 3.13.17, Windows:

  • 471 passed across legacy worker, runtime v1, and runtime v2 using AZURE_FUNCTIONS_TEST_LEGACY_REGISTRY=1.
  • 314 passed with the default Python 3.13 selection (runtime v1/v2).
  • The 471-case matrix also passed with the pre-PR378 SDK wheel installed, confirming the unit tests do not require the unreleased SDK behavior.
  • Changed Python files pass flake8 E/F/W checks, using repository exclusions and line length. git diff --check passes. This is not a claim that the repository's existing docstring-plugin diagnostics are clean.

Core Tools: V2 only, Python 3.13.17

Core Tools 4.16.0, host 4.1054.250.26428, packaged candidate V2 runtime wheel 1.3.0, fixed SDK wheel from PR378, local Azurite. Neither the installed Core Tools worker files nor runtime modules were patched in place.

16/16 scenarios passed:

Scenarios Validation
EventHub List[EventHubEvent], list[EventHubEvent], collections.abc.Sequence[EventHubEvent], list with union element Successful worker indexing. Trigger disabled; no EventHub delivery test.
Queue Out with typing List, builtin list, ABC Sequence, union elements, optional elements HTTP invocation plus actual Azurite queue contents: ['first', 'second']; empty batch produces no messages.
Queue explicit returns with typing List and builtin list HTTP invocation plus the same actual nonempty/empty queue assertions.
EventHub wrong element type, tuple, top-level union; queue Out[list[int]]; HTTP list[str] Expected FunctionLoadError during indexing, not leaked TypeError/AttributeError.

Every case verifies the actual imported runtime/SDK file paths and SHA-256 hashes against the built wheels; runtime files are also checked against source. This prevents accidentally validating Core Tools' bundled runtime or a different SDK. Negative cases persist import provenance before indexing fails. Each host process is stopped after its case; the owned Azurite process was stopped afterward.

A/B comparison against unchanged worker commit 678215635302fae450917562f3442b9c65678627, with the same fixed SDK:

  • Existing typing-list EventHub input and queue Out both pass.
  • Builtin-list EventHub input, queue Out, and explicit queue return fail with the baseline runtime.
  • All pass with the candidate runtime.

Vendored-helper cleanup validation (141bea8)

  • Re-ran all 471 registration tests after removing the helpers: passed.
  • Built clean source copies of all three packages (legacy worker and runtimes v1/v2); inspected their fresh wheels and confirmed no vendored typing-inspection module is included.
  • Both historical SDK dependency-isolation fixtures still import their own helpers successfully and remain unchanged.
  • Re-ran the complete 16/16 V2 Core Tools matrix on Python 3.13.17 using the freshly built cleanup wheel, with imported-file provenance checks: passed. EventHub coverage remains indexing-only; queue cases exercise actual local delivery through Azurite.
  • The first attempt's four EventHub cases stopped at the emulator readiness check, before launching any host. After Azurite was listening, the full rerun passed. The owned emulator and all case hosts were stopped afterward.
  • No remaining live source/config references to the deleted helpers; git diff --check passes.

Existing V2 unit suite limitations

The available existing V2 unit suite produced 184 passed, 2 skipped, 16 subtests passed, and 8 failed, identically on baseline and candidate. Exact failing test sets were compared and match:

  • Three environment-reload tests in TestHandleEvent.
  • TestLogging.test_format_exception (Windows path expectation).
  • Four environment-reload tests in TestGRPC (time.tzset unavailable on Windows).

The optional deferred-binding test module could not be collected because the configured package proxy returned 404 for azurefunctions-extensions-bindings-eventhub==1.0.0b1; direct PyPI download also failed TLS negotiation. It was excluded from the comparable existing-suite runs. The existing code-quality test was checked separately as noted above. This is not a full green unit-suite claim. No Azure resources were deployed.


Pull Request Checklist

Host-Worker Contract

  • Does this PR impact the host-worker contract (e.g., gRPC messages, shared interfaces)?
    • No. No gRPC messages, capabilities, payload formats, or host interfaces change; the change is Python annotation registration and validation.
    • If yes, have the changes been applied to:
      • azure_functions_worker (Python <= 3.12)
      • proxy_worker (Python 3.13-3.14)
      • r2p2 (Python >= 3.15)

Worker Execution Logic

  • Does this PR affect worker execution logic (e.g., function invocation, bindings, lifecycle)?

Python Version Coverage

  • Does this change apply to all supported worker models?
  • If yes, have the changes been made to:
    • azure_functions_worker (Python <= 3.12)
    • proxy_worker (Python 3.13-3.14): consumes the updated runtime libraries; no proxy transport edit needed.
    • r2p2 (Python >= 3.15): consumes the updated runtime libraries; no bridge/transport edit needed.
    • runtimes/v1 / runtimes/v2 (Python >= 3.13)
  • Local validation scope: Python 3.13 only. Legacy worker and v1 registration have unit coverage on that interpreter; Core Tools end-to-end testing covers V2 only. No claim of Python 3.10-3.12, 3.14, 3.15, or R2P2 end-to-end validation.

Programming Model Compatibility (proxy_worker and r2p2)

  • Does this change apply to both:
    • V1 programming model (runtimes/v1)?
    • V2 programming model (runtimes/v2)?

This branch has not been deployed

No deployments
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