From 71193e2b2cbfffc46f925263eb8b80c61ef875a8 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Thu, 7 May 2026 13:21:35 -0500
Subject: [PATCH] [helpers] Document write_file's external consumer contract
 (esphome-device-builder) (#16290)

---
 esphome/helpers.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/esphome/helpers.py b/esphome/helpers.py
index bb1984e17c..9d341af146 100644
--- a/esphome/helpers.py
+++ b/esphome/helpers.py
@@ -465,6 +465,12 @@ def _write_file(
 
 
 def write_file(path: Path, text: str | bytes, private: bool = False) -> None:
+    """Atomically write text or bytes to path. Wraps OSError as EsphomeError.
+
+    Used by esphome-device-builder for in-place YAML rewrites; the
+    atomicity (sibling tempfile + shutil.move) and EsphomeError
+    wrapping are part of the public contract.
+    """
     try:
         _write_file(path, text, private=private)
     except OSError as err: