Azure / Azure/azure-sdk-for-python

SearchFieldDataType.Collection not visible to static type checkers (requires # type: ignore at every call site)

Open
#47,929 1 comment 1 reaction 1 assignee Claimed by @hizixin View on GitHub
Search Service Attention
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.