Mark Home Assistant PEP-561 compatible

[frenck]

Proposed change

Mark the homeassistant package as PEP-561 compatible. This allows custom integrations to run mypy checks on references to homeassistant core components.

This allows custom integrations to add more quality insurance to their integrations.

Also attempted in #28866, but back in 2019, we weren't that greatly typed yet; now we are.

There is one catch, as the PEP dictates:

if a top-level package includes it, all its sub-packages MUST support type checking as well.

This is not the case, as many integrations have been excluded from typing. However, in reality, that isn't a practical issue for mypy or pyright. Additionally, those untyped integrations, are not part of stuff other integrations build upon. Therefore, I think the gain is still relevant for upstream custom integrators.

As an alternative to this PR, a type stub/shed could be created.

Ref: https://www.python.org/dev/peps/pep-0561/

To-do

Ensure our entity components are strictly typed:

• date (Mark date entity component as strictly typed #106716)
• datetime (Mark datetime entity component as strictly typed #106717)
• humidifier (Mark humidifier entity component as strictly typed #106721)
• siren (Mark siren entity component as strictly typed #106719)
• stt (Mark stt entity component as strictly typed #106723)
• time (Mark time entity component as strictly typed #106720)
• todo (Mark todo entity component as strictly typed #106718)
• wake_word (Mark wake_word entity component as strictly typed #106724)

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.
• Untested files have been added to .coveragerc.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[frenck]

I would like some feedback/agreement/disagreement from multiple core members before we merge this one.

/CC @cdce8p as our typing guru

[MartinHjelmare]

I think we should type the following entity components strict first:

• date
• datetime
• humidifier
• siren
• stt
• time
• todo
• wake_word

Otherwise it sounds ok and all the common parts that are used seem to be strictly typed.

[frenck]

Ok, so started doing these entity components, and this was pretty helpful. However, while doing this, I noticed how many core parts aren't typed actually.

For example, many helpers don't pass strict typing, same for util, backports, data entry flows, config entries, and more...

I'm going to close this for now and going to consider a typeshed route instead.

../Frenck

[cdce8p]

Hmm, usually I'm all for adding it. Even considered it myself a while ago. However, I'm not sure the project is well suited for it.

As you already noticed, it's quite difficult for us to fully / strictly type everything nevertheless just the important stuff. My go to example is the config flow. Dynamically calling methods (async_step_user, ...) based on string concatenation works fine in Python, but we can't really make it completely type safe.

That's not to say that py.typed wouldn't improve some stuff. It's just that, for my experience, the most type issues are actually found within an integration itself (when strict typing is activated) or if the dependency adds py.typed. The interface with the core is usually fine, maybe 90% / 10%.

Where does that leave us? You mentioned stub packages. That's certainly an option, although keep in mind that it needs to keep pace with the core development which might prove difficult. We could also consider adding py.typed just to the individual integration folders instead of the toplevel one. That's just difficult for core.py 🤔 Another thing to consider would be how that would interact with autocompletions, especially Pylance. At the moment these work quite well, but what happens if an outdated stub package is installed. Stub packages usually have priority over the actual code. Something to check.

My personal recommendations for custom integration developer would be to

• Enable strict typing with mypy.
• Make sure dependencies are typed AND ship with py.typed (or install the corresponding stub package).
• Use a linter (ruff, pylint) to make sure all import symbols actually exist.
• (Optional) Use an editor with good autocompletions. For Pylance it might even help to set python.analysis.typeCheckingMode to "strict", although you kind of have to know what errors are important and which to ignore.

Just some of my thoughts.

--

For example, many helpers don't pass strict typing, same for util, backports, data entry flows, config entries, and more...

Do you have any particular examples? I might be able to take a look.