Add mypy strict + tighten get_job() to JobInfo | None + py.typed marker

[heikkih]

Summary

Adds mypy --strict as a CI step, fixes the type-soundness issues it surfaces, and addresses two correctness gaps caught in review.

The library declared correct TypedDict return types on its public methods, but the implementations all returned Any (the result of response.json()). Mypy is lenient with Any → TypedDict so the leak was invisible, but Any → list[Storage] (added in 2.2.0) is strict — that's how the issue surfaced when wiring up the new get_storage() method downstream in Home Assistant core. Every other GET method had the same latent flaw.

Why now

We discovered this while writing the storage-sensors integration in HA. Without fixing it at the source, every downstream consumer would have to cast() results back into the declared types — type debt distributed across consumers. Cleaner to fix once at the boundary.

get_job() signature change (review feedback)

The original code did cast(JobInfo, {}) on the 204 branch, which lies to the type checker — an empty dict does not satisfy JobInfo's required keys. Changed to JobInfo | None, returning None on 204. This matches the existing get_transfer() -> Transfer | None pattern.

This is a minor breaking change at the type level. Runtime impact for sane consumers is nil — anyone reading job["progress"] on the empty-dict return was already crashing today; the new contract just makes the no-job state explicit. HA-side will need a one-line data is not None guard in its base entity's available check; that change rides along with the eventual 2.2.1 bump there.

py.typed marker (review feedback)

Adding pyprusalink/py.typed (PEP 561) so downstream type checkers actually see the TypedDicts. Without it, the strict-typing work in this PR is invisible to consumers — installed distributions would be treated as untyped. Includes:

• empty pyprusalink/py.typed (full typing marker)
• [tool.setuptools.package-data] pyprusalink = ["py.typed"] to ensure inclusion in the wheel
• zip-safe = false per setuptools/mypy guidance for typed packages

Why cast() (and not pydantic / msgspec / TypeGuards)

cast() at each return site is the pragmatic choice for a thin API wrapper:

Approach	Decision
cast()	✅ Chosen. Dominant HA-ecosystem pattern, zero runtime cost, minimal change.
pydantic / msgspec	❌ Overkill for a thin wrapper. Pulls in a ~50KB+ C extension and requires refactoring the public types.
Custom TypeGuards	❌ Maintenance burden, easy to drift from the TypedDict definitions.
Suppress with # type: ignore	❌ Defers the debt without solving anything.

Trade-off accepted: cast() does not validate at runtime. If the Prusa API ever changes shape, errors surface as KeyError/AttributeError in consumer code rather than at the library boundary. For a stable upstream API this is acceptable; runtime validation can be layered on later without changing the public types.

Why strict from the start

--strict rather than gradual tightening: with only 10 errors on a small codebase, fixing them in one pass is cheaper than introducing a slow ratchet. Strict mode then prevents future contributions from quietly weakening typing — any new method that leaks Any will fail CI.

Changes

• pyproject.toml: mypy==2.0.0 in lint extras; [tool.mypy] strict = true; package-data for py.typed; zip-safe = false
• .github/workflows/test.yml: new mypy step
• pyprusalink/py.typed: PEP 561 marker (new, empty)
• pyprusalink/__init__.py: cast(...) at each response.json() return; get_job() -> JobInfo | None returning None on 204
• pyprusalink/types.py: dict | None → dict[str, Any] | None on JobFilePrint.meta
• pyprusalink/client.py: same dict[str, Any] fix on request(..., json_data=...)
• tests/: updated get_job no-job assertion from == {} to is None

Suggested release

Suggesting 2.2.1 as a patch release once this lands. Runtime is fully backward compatible for sane consumers; the typing contract becomes more honest. HA core will bump to 2.2.1 in a follow-up PR that also adds the small data is not None guard.

Test plan

• mypy — Success: no issues found in 4 source files
• pytest tests/ — 22 passed
• flake8 / black / isort all clean
• Wheel build verified to include pyprusalink/py.typed

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR introduces strict static type checking to the project’s CI via mypy --strict and addresses the resulting type-soundness gaps by tightening API response typing (primarily around response.json() returning Any).

Changes:

• Add mypy --strict configuration and run it in GitHub Actions CI.
• Use typing.cast(...) at response.json() call sites to prevent Any from leaking into declared TypedDict return types.
• Refine a few overly-broad dict annotations to dict[str, Any] for better strict-mode compatibility.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pyproject.toml	Adds mypy to lint extras and enables strict mypy configuration.
.github/workflows/test.yml	Runs mypy as part of CI alongside existing linters/tests.
pyprusalink/__init__.py	Adds cast(...) to typed API wrapper return paths to avoid Any leakage.
pyprusalink/types.py	Tightens JobFilePrint.meta typing to `dict[str, Any]
pyprusalink/client.py	Tightens request JSON payload typing to `dict[str, Any]

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[agners]

So with returning None now we essentially change the APU. According to semantic versioning this would mean the next release needs to be a major version bump. I am fine with it, just saying... If we have other breaking API changes in mind, let's introduce them now too.

[heikkih]

So with returning None now we essentially change the APU. According to semantic versioning this would mean the next release needs to be a major version bump. I am fine with it, just saying... If we have other breaking API changes in mind, let's introduce them now too.

Thanks. Agree we should do a major-bump. I did a thorough check if there is anything else that could be in a bump.

Already in this PR (the actual driver for 3.0.0):

• mypy --strict in CI + cast() at JSON boundaries
• get_job() -> JobInfo | None returning None on 204
• py.typed marker so downstream type checkers see the TypedDicts

Worth considering:

PrinterInfo: migrate T | None → NotRequired[T] to match VersionInfo. The API actually omits absent fields rather than returning None, so the current typing is dishonest. HA-side already accesses PrinterInfo defensively via .get() in most places — the migration makes the contract match reality without forcing real changes downstream. Twelve fields, but straightforward.

Potential, want your take:

jobId → job_id rename on the four job-control methods, for PEP 8 and consistency with cancel_transfer(transfer_id). HA-core calls them positionally so HA doesn't benefit, but the inconsistency is a wart. Cheap to fold in if you'd like it cleaned up; otherwise happy to leave it.

Otherwise no other breaking changes on my roadmap right now.

#155 should warrant a new major version in the future, but not ready for that.

Lean: ship 3.0.0 with what's in this PR + the PrinterInfo migration, and add the jobId rename if you want it.

[agners]

Lean: ship 3.0.0 with what's in this PR + the PrinterInfo migration, and add the jobId rename if you want it.

Yeah let's do PrinterInfo and jobId rename as well.

[heikkih]

Lean: ship 3.0.0 with what's in this PR + the PrinterInfo migration, and add the jobId rename if you want it.

Yeah let's do PrinterInfo and jobId rename as well.

Great. I've added #169 and #170 now 👍