Azure / Azure/azure-sdk-for-python
SearchFieldDataType.Collection not visible to static type checkers (requires # type: ignore at every call site)
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 193
Description
**Library:** `azure-search-documents`
**Version:** `12.1.0b1` (observed after upgrading from `11.7.0b2`)
**Python:** 3.13
### What we ran into
After upgrading `azure-search-documents` to `12.1.0b1`, our static type checker started flagging every use of `SearchFieldDataType.Collection(...)` as a call on a non-callable. We build vector/collection fields the way the SDK docstrings recommend, e.g.:
```python
SearchField(
name="embedding",
type=SearchFieldDataType.Collection(SearchFieldDataType.Single),
...
)
```
To keep our type-check gate green we had to add a suppression at **every** call site (8 across our codebase). Since `Collection(Edm.Single)` is the standard way to declare vector fields, this affects essentially anyone doing vector search, so we wanted to raise it rather than just silently suppress.
### Why it seems to happen
`SearchFieldDataType` is defined in `_enums.py` as a plain enum with no `Collection` member. `Collection` is instead added at runtime in `models/_patch.py`:
```python
SearchFieldDataType.Collection = staticmethod(_collection_helper) # type: ignore[attr-defined]
```
Because the attribute only exists at runtime, static analyzers (we hit this with `ty`, but I'd expect mypy/pyright to behave the same since the symbol isn't present at type-check time) can't see it as callable — they model `SearchFieldDataType.Collection` as an enum member and report the call as `call-non-callable` / not-callable. The SDK already suppresses the same underlying issue internally on the monkey-patch line.
### Possible directions (deferring to your judgment)
I'm not sure what the intended pattern is here, so a few options that would each remove the need for downstream suppressions — whichever fits your codegen/`_patch` conventions best:
- There's already a module-level `def Collection(typ: Any) -> str` in `_patch.py` that isn't in `__all__`. Exporting it would let callers use a fully-typed `Collection(...)` helper.
- Or add a typed `@staticmethod` declaration for `Collection` on the enum class so the runtime patch is visible to type checkers.
- Or document the officially-supported, type-safe way to construct a collection field type, if one already exists that we've missed.
Happy to provide a minimal repro or test a proposed fix.
Contributor guide
Assessment
This issue has not been assessed yet.