Replace the mypy ban with a strong-typing policy - #245
Merged
Conversation
The objective is strong-typed, deterministic code. Make pyright strict on first-party code the required baseline (Pylance embeds pyright, so editor and CLI/CI run the same engine and stay consistent), relaxing third-party strictness only where a dependency has no usable types. Delete the CODESTYLE mypy ban - it contradicted AGENTS.md and the catalog VS Code snippet, which already ship the mypy extension - and allow mypy as an additional checker, required for a Home Assistant integration (platinum strict-typing) and useful for a pydantic library (the pydantic.mypy plugin). Multiple tools serving distinct purposes is normal, like CSharpier + dotnet format on the .NET side. Record the default vs HA Python profiles in spec/project-types.json (HA standalone configs are exempt, not drift; mypy --strict expected). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reconciles the repo's Python typing/tooling guidance by removing the implied mypy ban and formalizing a "strong typing" policy that treats pyright strict as the baseline, with mypy permitted (and required for Home Assistant integrations).
Changes:
- Updates
CODESTYLE.mdPython guidance to define a strong-typing baseline (pyright strict) and allow mypy as an additional checker (and HA requirement). - Updates
spec/project-types.jsonto reflect the new typing policy and Home Assistant exemptions/conventions. - Adds
pydantictocspell.jsonto avoid false positives introduced by the updated documentation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| spec/project-types.json | Aligns the audit/spec checks with the new pyright/mypy policy and HA conventions/exemptions. |
| cspell.json | Adds terminology used by the updated typing policy text. |
| CODESTYLE.md | Replaces the mypy-ban language with a strong-typing policy and documents when mypy is appropriate/required. |
Adopt the more natural adjective form per review. The pyright strict = ["src"] example is correct as written - pyright's strict config key is an array of path globs (in production in aiopurpleair's [tool.pyright], and already documented at CODESTYLE.md:423); the boolean strict is mypy's. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move [mypy-link] into its alphabetical slot (after latest-link, before pep-0257-link) in the external reference block. Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Keep python.config.placement a single-form letter check (pyproject canonical) and delegate the Home Assistant standalone-config exception to ha.python.conventions, rather than listing two acceptable forms in one letter check. Qualify the mypy toolchain-table config cell so it does not hard-code pyproject for HA repos. Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The clean-compile now names the repo's mypy command (e.g. uv run mypy src) where mypy is used, matching the Type checking policy that says mypy joins the clean-compile. Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 6, 2026
Merged
ptr727
added a commit
that referenced
this pull request
Jul 7, 2026
Two-phase promotion of the accumulated governance work on `develop` to `main`. Carries #244-#251: - #244 Foundational Principles (the model's governing *why*) - #245 Replace the mypy ban with a strong-typing policy - #246 aiopurpleair + homeassistant-purpleair audit reports - #247 Catalog the 14 backlog repos; add the `eda` type and `releaseTrigger: none` - #248 Branch-conditional Docker platforms (multi-arch main, amd64 elsewhere) - #249 Retire the both-branch matrix for symmetric single-branch self-release - #250 Declare workflow YAML as LF and validate line endings in CI - #251 Extend line-ending governance to pattern files and catalog snippets All commits were reviewed and CI-green on their individual develop PRs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves the mypy spec question raised by the aiopurpleair / homeassistant-purpleair audits, and fixes an internal hub contradiction.
The contradiction: CODESTYLE.md banned mypy ("not used here - don-t introduce it"), while AGENTS.md:247 and catalog/snippets/vscode/python.jsonc both ship the mypy VS Code extension. The ban also entered undocumented - carried from the PyPiLibrary sample during the CODESTYLE consolidation (f526b55), with no recorded rationale.
The policy (CODESTYLE.md):
Spec (spec/project-types.json): default vs HA Python profiles - HA standalone .ruff.toml/pyrightconfig.json is exempt (not drift), mypy --strict expected for HA.
AGENTS.md:247 and the catalog snippet already include mypy, so deleting the ban reconciles all three. Fuller homeassistant-type checks (manifest/hacs/quality_scale, the test-matrix tracker) remain follow-up per the audits.