Skip to content

fix: support PEP 585 binding annotations - #378

Open
Varad Meru (vrdmr) wants to merge 4 commits into
devfrom
vrdmr-pep-585-binding-support
Open

Varad Meru (vrdmr) wants to merge 4 commits into
devfrom
vrdmr-pep-585-binding-support

Conversation

@vrdmr

@vrdmr Varad Meru (vrdmr) commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Replace the vendored azure.functions._thirdparty.typing_inspect with the standard library's typing.get_origin/typing.get_args in meta.is_iterable_type_annotation. The vendored module was imported in 2019 when Python 2.7 still had to be supported, and it recognized only typing._GenericAlias, so list[X] was rejected. This library requires Python 3.13+, where the standard library handles PEP 585 builtin generics natively, including nested aliases such as dict[str, list[int]]. The previous tuple exclusion is kept explicitly so tuple annotations are still rejected.
  • Delete the azure.functions._thirdparty package and remove its flake8, coverage, and mypy configuration entries. Nothing else in the library imports it.
  • Add a shared class guard (meta.is_class_type) before converter issubclass checks. It explicitly excludes types.GenericAlias, which matters on Python 3.9/3.10. On 3.13+, isinstance(list[X], type) is already False, so the guard's practical effect here is that non-class annotations return False instead of raising.
  • Preserve existing element-type and cardinality restrictions. Event Hub, Service Bus, and Kafka accept matching builtin list annotations but reject list[str] inputs. Single-event and specialized collection bindings are unchanged. The parameterized List[...] is removed from Event Grid's scalar subclass targets, since iterable validation already handles it.
  • Cover builtin lists alongside existing typing.List tests, plus collections.abc generics, nested and mismatched aliases, rejected special forms (tuple, Callable, Optional/Union, ClassVar), Out[list[str]], and empty and nonempty list output serialization. Update the annotation documentation and the MCP invalid-annotation expectations.

Scope

The issubclass() arg 1 must be a class TypeError in Azure/azure-functions-python-worker#1034 only happens on Python 3.9/3.10, where isinstance(list[X], type) is True. This PR targets the 2.x line (requires-python >=3.13). There, it fixes list[X] annotations being rejected. Python 3.10ΓÇô3.12 workers pin the 1.x line (azure-functions==1.27.0b1), so this PR does not fix the 3.10 crash.

Behavior parity

I compared the old vendored-helper implementation against the standard-library implementation on Python 3.13 and 3.14 across 177 annotation/element-type combinations. They covered typing and builtin lists, sets, deques, tuples, dicts, Optional/Union, Annotated, Callable, ClassVar, Generator, user Generic classes, string forward references, and TypeVars. The results were identical. Without the explicit tuple exclusion, 14 tuple combinations would go from rejected to accepted. The new tuple test fails in that case: 8 subtests failed when I removed the exclusion.

Conversion-path review

No annotation normalization shim or encode/decode changes are needed in this library. Decoders select the payload shape from datum/cardinality metadata, encoders inspect runtime values, and the existing standard-library typing.get_origin checks already recognize builtin aliases. Kafka's output encoding is still unsupported, as before; only its annotation checks gain parity.

Validation

Python 3.13:

  • .venv/bin/python -m pytest -q --disable-warnings -ra: 1131 passed, 2 skipped, 259 subtests passed. Skips: optional mypy is not installed; one HTTP test is excluded on Python 3.8+.
  • .venv/bin/python -m flake8 --config .flake8 --extend-ignore=D: passed.
  • .venv/bin/python -m flake8 --config .flake8 azure/functions/decorators/function_app.py --select=D: passed.
  • git diff --check: passed.
  • The built wheel no longer contains azure/functions/_thirdparty.

The reported reproduction now returns True for both typing.List[func.EventHubEvent] and list[func.EventHubEvent]. It returns False for list[str] and tuple[func.EventHubEvent, ...].

Related work

Relates to Azure/azure-functions-python-worker#1034.

The companion worker and runtimes v1/v2 change is tracked in Azure/azure-functions-python-worker#1952 (draft). It replaces vendored annotation inspection in registration, preserves full aliases for SDK validation, and covers explicit output returns. Core Tools validation passed 16/16 scenarios using Python 3.13 and the V2 runtime with this SDK fix: actual queue output delivery, EventHub indexing only, and negative annotation validation. The draft tracks the outstanding compatible SDK release/dependency rollout.

No pull request template was present in this repository or the Azure organization's default community files.

Recognize builtin generic aliases during annotation inspection and guard converter subclass checks without broadening accepted binding element types.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The library requires Python 3.13+, where typing.get_origin/get_args
natively handle PEP 585 builtin generics. Use them in
is_iterable_type_annotation, keep the previous tuple exclusion, and
delete the vendored azure.functions._thirdparty package and its
flake8, coverage, and mypy configuration entries.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The new is_class_type guard rejects previously supported iterable union annotations, requiring a compatibility fix and regression tests for both helper branches.

1 open issue
What changed in this PR

This PR adds PEP 585 builtin-generic support to Azure Functions binding annotation checks while preserving existing cardinality and element-type restrictions. Worker-side annotation support remains separate.

Changes:

  • Replace vendored typing inspection with standard-library helpers and guard converter subclass checks.
  • Expand regression coverage for builtin generics, rejected annotations, and list serialization.
  • Document annotation support and remove obsolete third-party configuration.
File Description
tests/​test_servicebus.py Test builtin lists and mismatched message types.
tests/​test_queue.py Cover accepted output lists and rejected inputs.
tests/​test_meta.py Add shared annotation and serialization regression tests.
tests/​test_mcp.py Expect invalid annotations to return False.
tests/​test_kafka.py Verify builtin-list annotation parity.
tests/​test_eventhub.py Verify builtin-list annotation parity.
tests/​test_eventgrid.py Cover list outputs and invalid annotations.
tests/​test_connector.py Test builtin and collection-interface generics.
setup.cfg Remove vendored-module mypy exemption.
README.md Document annotation support and worker dependency.
azure/​functions/​warmup.py Guard input subclass checks.
azure/​functions/​timer.py Guard input subclass checks.
azure/​functions/​sql.py Guard input and output subclass checks.
azure/​functions/​servicebus.py Use shared class guards.
azure/​functions/​queue.py Use shared class guards.
azure/​functions/​mysql.py Guard input and output subclass checks.
azure/​functions/​meta.py Use standard typing helpers and shared class validation.
azure/​functions/​mcp.py Guard MCP trigger annotation checks.
azure/​functions/​kafka.py Use shared class guards.
azure/​functions/​http.py Guard request and response annotation checks.
azure/​functions/​eventhub.py Use shared class guards.
azure/​functions/​eventgrid.py Guard checks and remove parameterized scalar target.
azure/​functions/​durable_functions.py Guard Durable Functions annotation checks.
azure/​functions/​decorators/​function_app.py Update connector annotation docstring examples.
azure/​functions/​cosmosdb.py Guard specialized document-type checks.
azure/​functions/​connectors.py Use shared class guard.
azure/​functions/​blob.py Guard input and output annotation checks.
azure/​functions/​_thirdparty/​typing_inspect.py Delete vendored typing inspection implementation.
azure/​functions/​_thirdparty/​__init__.py Remove obsolete package initializer.
.flake8 Remove vendored-package exclusion.
.coveragerc Remove vendored-package coverage omission.

Review effort: Balanced

Comment thread azure/functions/meta.py Resolved
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.

3 participants