From d1ea9b351771a1cc4018708948765d3bfeb73286 Mon Sep 17 00:00:00 2001
From: AlKor13 <106060471+AlKor13@users.noreply.github.com>
Date: Sat, 3 Oct 2026 09:07:21 +0500
Subject: [PATCH] gh-158633: say that subprocess text mode guesses the child's
 encoding

Text mode documents which encoding is used and not that the value is a guess
about the child process, so a wrong guess reads as a bug in this module: the
output is either silently mojibake, or a UnicodeDecodeError raised while the
stream is read, reported from inside subprocess rather than from the call that
is missing encoding=.

The warning keeps to what was asked for on gh-105312: the default is a guess,
pass encoding= on every platform, and on Windows more than one default is in
force at once -- the ANSI code page and the console output code page -- so a
console child is read with the console page while a Python child can be told
what to write through PYTHONUTF8 / PYTHONIOENCODING.
---
 Doc/library/subprocess.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 2a31213560c92d3..5a8d0f40ed4b55b 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -308,6 +308,29 @@ default values. The arguments that are most commonly needed are:
    If text mode is not used, *stdin*, *stdout* and *stderr* will be opened as
    binary streams. No encoding or line ending conversion is performed.
 
+   .. warning::
+
+      In text mode, the encoding used when *encoding* is not given is a guess
+      about the child process rather than information about it.  If the guess is
+      wrong, the output is decoded incorrectly: either silently, producing
+      mojibake, or as a :exc:`UnicodeDecodeError` raised while the stream is
+      read, which is reported from inside this module rather than from the call
+      that is missing the argument.  Passing *encoding* explicitly, chosen for
+      the program being run, is recommended on every platform, and this stays
+      true where the default is UTF-8 (see :pep:`686`): what the child writes is
+      the child's choice, not the parent's.
+
+      A wrong guess is most likely on Windows, where more than one default is in
+      force at once -- the ANSI code page that
+      :func:`locale.getpreferredencoding` reports, and the console output code
+      page that console programs write in, reported by the Windows
+      ``GetConsoleOutputCP`` API.  These are commonly different values, so no
+      single encoding is correct for every child of one process: a console
+      program such as :program:`cmd` is read with the console output code page,
+      while a Python child can be told which encoding to write through the
+      :envvar:`PYTHONUTF8` and :envvar:`PYTHONIOENCODING` environment variables
+      in its *env*.
+
    .. versionchanged:: 3.6
       Added the *encoding* and *errors* parameters.