Explain why we `flush_buffer()` for Python `print(...)` output (#18420)

Spawning from using this code elsewhere and not knowing why it's there.

Based on this article and @reivilibre's experience mentioning
`PYTHONUNBUFFERED=1`,

> #### programming languages where the default “print” statement buffers
> 
> Also, here are a few programming language where the default print
statement will buffer output when writing to a pipe, and some ways to
disable buffering if you want:
> 
> - Python (disable with `python -u`, or `PYTHONUNBUFFERED=1`, or
`sys.stdout.reconfigure(line_buffering=False)`, or `print(x,
flush=True)`)
> 
> _--
https://jvns.ca/blog/2024/11/29/why-pipes-get-stuck-buffering/#programming-languages-where-the-default-print-statement-buffers_

3 files changed, 11 insertions, 0 deletions

diff --git a/changelog.d/18420.misc b/changelog.d/18420.misc
new file mode 100644

index 0000000000..d52175af91
--- /dev/null
+++ b/changelog.d/18420.misc
@@ -0,0 +1 @@
+Explain why we `flush_buffer()` for Python `print(...)` output.
diff --git a/docker/configure_workers_and_start.py b/docker/configure_workers_and_start.py

index df34d51f77..102a88fad1 100755
--- a/docker/configure_workers_and_start.py
+++ b/docker/configure_workers_and_start.py
@@ -352,6 +352,11 @@ def error(txt: str) -> NoReturn:
 
 
 def flush_buffers() -> None:
+    """
+    Python's `print()` buffers output by default, typically waiting until ~8KB
+    accumulates. This method can be used to flush the buffers so we can see the output
+    of any print statements so far.
+    """
     sys.stdout.flush()
     sys.stderr.flush()
 
diff --git a/docker/start.py b/docker/start.py

index 818a5355ca..0be9976a0c 100755
--- a/docker/start.py
+++ b/docker/start.py
@@ -22,6 +22,11 @@ def error(txt: str) -> NoReturn:
 
 
 def flush_buffers() -> None:
+    """
+    Python's `print()` buffers output by default, typically waiting until ~8KB
+    accumulates. This method can be used to flush the buffers so we can see the output
+    of any print statements so far.
+    """
     sys.stdout.flush()
     sys.stderr.flush()