refactor(core/query): type forwarded query constructor kwargs

Merged
OG
4mo ago
+56-47

Note, the end goal would be to remove Query.query_init instead, this is just improvements along the way to reduce typing ignores.

Why

**kwargs: dict[str, Any] does not mean "kwargs is an arbitrary mapping". It declares that every keyword value is itself a dict[str, Any]. The twelve query constructors in core/query/resource_manager.py that forward to the base query constructor therefore looked like they were passing a dict to each of its typed parameters (branch, at, limit, offset, order_by, branch_agnostic, user_id).

The consequences were a # type: ignore[arg-type] on every single forwarding call, and 84 suppressed ty invalid-argument-type diagnostics in that one file (one per base parameter per call site). That is 20% of all suppressed ty debt in backend/infrahub/core/, from one bad idiom in one file. It also meant callers of those query classes were entirely unchecked.

Goal: correct the annotation so the forwarded kwargs are verified, and permanently enforce invalid-argument-type for the rest of core/query/.

Non-goals: the same idiom appears at ~150 further sites (query_init overrides, graphene __init_subclass_with_meta__, migration init). None of those produce diagnostics today, and they are a separate mechanical sweep.

What changed

  • Added a QueryInitKwargs TypedDict next to the base query constructor and declared the twelve forwarding constructors as **kwargs: Unpack[QueryInitKwargs].
  • Deleted the twelve now-unnecessary # type: ignore[arg-type] comments.
  • Aligned the query_init overrides in the same file with the base signature (**kwargs: Any); they were drifted copies of a base that was already correct.
  • Narrowed the ty invalid-argument-type override from the coarse backend/infrahub/core/query/** glob to the five files that still trip it (__init__.py, diff.py, node.py, relationship.py, subquery.py). Every other file in the package, including resource_manager.py, is now permanently enforced for that rule.
  • Dropped seven stale mypy disable_error_code entries for infrahub.core.query* that no longer match any reported error: attr-defined (on query and query.ipam), annotation-unchecked (query.node), and call-overload / index / misc / var-annotated (query.relationship). These were already stale before this change; measuring the modules with all their overrides stripped surfaced them.

What stayed the same: no runtime behaviour. Every top-level definition in resource_manager.py is byte-identical after stripping annotations; the only other edits to that file are two added imports. **kwargs annotations are never evaluated at runtime here (from __future__ import annotations), and removing a # type: ignore comment has no runtime effect.

This is not a suppression swap. The kwargs are genuinely checked now, where before anything was accepted:

$ uv run mypy <probe with a deliberately wrong call>
error: Argument "limit" to "IPAddressPoolGetIdentifiers" has incompatible type "str"; expected "int | None"  [arg-type]
error: Unexpected keyword argument "bogus" for "IPAddressPoolGetIdentifiers"  [call-arg]

On ty versions

ty 0.0.32 (pinned here) accepts Unpack[TypedDict] on **kwargs and stops emitting the 84 diagnostics, but does not yet enforce the TypedDict contents, so today's enforcement comes from mypy. ty 0.0.66 does enforce it, so a later ty upgrade tightens this change rather than breaking it. No upgrade is required for this PR.

How to review

Start with backend/infrahub/core/query/__init__.py (the new TypedDict, 12 lines), then the pyproject.toml diff (both the ty glob narrowing and the stale mypy entries). resource_manager.py is 36 mechanical, uniform edits: 12 **kwargs annotations, 12 removed type-ignores, 12 query_init signatures.

The QueryInitKwargs fields must stay in sync with the base constructor's signature by hand. That is the one thing worth a careful look, and the reason it lives directly above class Query.

How to test

uv run invoke backend.mypy      # Success: no issues found in 1601 source files
uv run ty check .               # All checks passed!
uv run invoke backend.ruff
uv run invoke backend.test-unit # 2166 passed

Note: 4 tests in backend/tests/unit/services/adapters/workflow/test_local_stamping.py fail locally without a Prefect API on localhost:4200. They fail identically on a clean tree and are unrelated to this change. The touched code is covered by component and functional tests, which need the testcontainers stack, so CI is the gate for those.

Measured effect on suppressed debt in backend/infrahub/core/, checking with the debt overrides stripped: 423 -> 339 ty diagnostics, and resource_manager.py goes from 84 to 0.

Impact & rollout

  • Backward compatibility: no API or behaviour change; annotations only.
  • Performance: none.
  • Config/env changes: none.
  • Deployment notes: safe to deploy.

Follow-ups found while doing this

  • QueryResult.__init__ annotates data as list[Neo4jNode | Neo4jRelationship | list[Neo4jNode]], but is passed a neo4j Record (query/__init__.py:660). No runtime bug, since a Record accepts string keys, but the wrong annotation is why relationship.py:1546 still carries a bare # type: ignore for row.data["uuid"]. Correcting it on a class used throughout the query layer looks like the next root-cause fix.
  • The remaining ~150 **kwargs: dict[str, Any] sites, none of which produce diagnostics today.

Checklist

  • Tests added/updated
  • Changelog entry added
  • External docs updated (if user-facing or ops-facing change)
  • Internal .md docs updated (internal knowledge and AI code tools knowledge)
  • I have reviewed AI generated content