docs: expand Python typing guide with real-world protocol examples

[iddocohen]

Summary

Enrich the Python SDK "Strict Typing in Python" guide. The page already documents the protocols mechanics; this adds the real-world usage and the "keep protocols in sync" framing that were missing.

Key changes

• Overview: rewrote the opener as a capability lead (removed "This guide explains…").
• New subsection — "Using protocols in generators and transforms": a multi-kind example (client.filters(kind=NetworkDevice, …) with a list[NetworkDevice] type hint) showing where protocols matter most.
• New subsection — "Keep protocols in sync with your schema": the generated file is a build artifact; regenerate on schema change; the type checker surfaces drift at development time.

What needs reviewer attention

• The two new subsections in docs/docs/python-sdk/guides/python-typing.mdx (all other lines unchanged). New prose only; the example uses documented SDK APIs.

What didn't change

• All existing content preserved; no factual claims altered.
• The infrahubctl protocols reference page is auto-generated — untouched.

Out of scope (deferred)

• Voice cleanup of the "Generating Pydantic models from GraphQL queries" section (stacked-benefit bullets + "excellent type safety") — pre-existing prose, not in a section this PR touches. Fix in a follow-up if desired.

Test plan

• cd docs && npm run build succeeds
• Vale: 0 errors/warnings on the changed file

---

Summary by cubic

Expand the Python SDK typing guide with real-world Protocol usage to catch schema mismatches before runtime, add a generator/transform example using client.filters(kind=NetworkDevice, ...) that infers list[NetworkDevice] (no redundant annotation), document regenerating protocols with infrahubctl protocols, and update the overview to lead with capability.

^{Written for commit 581d30e. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	581d30e
Status:	✅  Deploy successful!
Preview URL:	https://98ff6dfe.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://docs-python-typing-real-worl.infrahub-sdk-python.pages.dev

View logs

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}

[ogenstad]

If this works as it should I'd expect this line to be:

leaf_switches = await client.filters(

However I think we have a problem with all of the overloads on .filter and other functions in the sense that the unknown keyword arguments screw up the typing?

[iddocohen]

Fixed by dropping the annotation to leaf_switches = await client.filters(...), since passing the class as kind is what produces the typed result. On the overloads, reveal_type confirms list[NetworkDevice] under both mypy and ty even with the filter kwargs present, so **kwargs: Any absorbs them without breaking resolution.