From 489cf483d0f7edd2373ada70efa284dc58e182ce Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 25 May 2026 20:55:35 -0500
Subject: [PATCH] [core] Enable ruff PYI (flake8-pyi) lint family (#16654)

---
 esphome/cpp_generator.py      | 22 ++++++++++++----------
 esphome/mqtt.py               |  2 +-
 esphome/yaml_util.py          |  2 +-
 pyproject.toml                |  1 +
 tests/unit_tests/test_main.py |  6 +++---
 5 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/esphome/cpp_generator.py b/esphome/cpp_generator.py
index c5e398b2d7..151018baa4 100644
--- a/esphome/cpp_generator.py
+++ b/esphome/cpp_generator.py
@@ -1077,43 +1077,45 @@ class MockObj(Expression):
         op = BinOpExpression(other, "|", self)
         return MockObj(op)
 
-    def __iadd__(self, other: SafeExpType) -> "MockObj":
+    # MockObj operator overloads build a new C++ expression rather than mutating self,
+    # so the PYI034 "augmented assignment returns self" assumption does not apply.
+    def __iadd__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "+=", other)
         return MockObj(op)
 
-    def __isub__(self, other: SafeExpType) -> "MockObj":
+    def __isub__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "-=", other)
         return MockObj(op)
 
-    def __imul__(self, other: SafeExpType) -> "MockObj":
+    def __imul__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "*=", other)
         return MockObj(op)
 
-    def __itruediv__(self, other: SafeExpType) -> "MockObj":
+    def __itruediv__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "/=", other)
         return MockObj(op)
 
-    def __imod__(self, other: SafeExpType) -> "MockObj":
+    def __imod__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "%=", other)
         return MockObj(op)
 
-    def __ilshift__(self, other: SafeExpType) -> "MockObj":
+    def __ilshift__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "<<=", other)
         return MockObj(op)
 
-    def __irshift__(self, other: SafeExpType) -> "MockObj":
+    def __irshift__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, ">>=", other)
         return MockObj(op)
 
-    def __iand__(self, other: SafeExpType) -> "MockObj":
+    def __iand__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "&=", other)
         return MockObj(op)
 
-    def __ixor__(self, other: SafeExpType) -> "MockObj":
+    def __ixor__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "^=", other)
         return MockObj(op)
 
-    def __ior__(self, other: SafeExpType) -> "MockObj":
+    def __ior__(self, other: SafeExpType) -> "MockObj":  # noqa: PYI034
         op = BinOpExpression(self, "|=", other)
         return MockObj(op)
 
diff --git a/esphome/mqtt.py b/esphome/mqtt.py
index ccacbaea54..098292f599 100644
--- a/esphome/mqtt.py
+++ b/esphome/mqtt.py
@@ -159,7 +159,7 @@ def get_esphome_device_ip(
     username: str | None = None,
     password: str | None = None,
     client_id: str | None = None,
-    timeout: int | float = 25,
+    timeout: float = 25,
 ) -> list[str]:
     if CONF_MQTT not in config:
         raise EsphomeError(
diff --git a/esphome/yaml_util.py b/esphome/yaml_util.py
index 9a36ad089c..28f72ab831 100644
--- a/esphome/yaml_util.py
+++ b/esphome/yaml_util.py
@@ -763,7 +763,7 @@ def parse_yaml(file_name: Path, file_handle: TextIOWrapper, yaml_loader=None) ->
 
 
 def _load_yaml_internal_with_type(
-    loader_type: type[ESPHomeLoader] | type[ESPHomePurePythonLoader],
+    loader_type: type[ESPHomeLoader | ESPHomePurePythonLoader],
     fname: Path,
     content: TextIOWrapper,
     yaml_loader: Callable[[Path], dict[str, Any]],
diff --git a/pyproject.toml b/pyproject.toml
index c8f4d88351..a094b05efe 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -126,6 +126,7 @@ select = [
   "NPY",  # numpy-specific rules
   "PERF", # performance
   "PL",   # pylint
+  "PYI",  # flake8-pyi
   "Q",    # flake8-quotes
   "RSE",  # flake8-raise
   "SIM",  # flake8-simplify
diff --git a/tests/unit_tests/test_main.py b/tests/unit_tests/test_main.py
index 6ec0069b3a..f6b6d0b05f 100644
--- a/tests/unit_tests/test_main.py
+++ b/tests/unit_tests/test_main.py
@@ -11,7 +11,7 @@ from pathlib import Path
 import re
 import sys
 import time
-from typing import Any
+from typing import Any, Self
 from unittest.mock import AsyncMock, MagicMock, Mock, patch
 
 import pytest
@@ -5110,11 +5110,11 @@ class MockSerial:
         self.timeout = 0.1
         self._is_open = False
 
-    def __enter__(self) -> MockSerial:
+    def __enter__(self) -> Self:
         self._is_open = True
         return self
 
-    def __exit__(self, *args: Any) -> None:
+    def __exit__(self, *args: object) -> None:
         self._is_open = False
 
     @property