[3.14] gh-76303: Improve documentation of the -x command line option (GH-155559) (GH-155566)

https://github.com/python/cpython/commit/f3648f48df41e51ad47e9ef2666998feedce73a5
commit: f3648f48df41e51ad47e9ef2666998feedce73a5
branch: 3.14
author: Miss Islington (bot) <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-08-11T15:53:04Z
summary:

[3.14] gh-76303: Improve documentation of the -x command line option (GH-155559) (GH-155566)

Expand the documentation for the -x command-line option to explain its
purpose and usage for turning Python scripts into Windows batch files,
with examples of batch file header lines.
(cherry picked from commit 4b04d5abcd8476af4c4a67fcf2263c856fdabb47)

Co-authored-by: Serhiy Storchaka <[email protected]>
Co-authored-by: Rory Glenn <[email protected]>
Co-authored-by: Brian Schubert <[email protected]>

files:
M Doc/using/cmdline.rst

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 0c947de005b58ea..a33747830f893c2 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -501,7 +501,25 @@ Miscellaneous options
 .. option:: -x
 
    Skip the first line of the source, allowing use of non-Unix forms of
-   ``#!cmd``.  This is intended for a DOS specific hack only.
+   ``#!cmd``.
+
+   This can be used to turn a Python script into a Windows batch file.
+   Similarly to adding a shebang line and setting the executable bit on Unix,
+   the extension of the Python script can be changed to ``.bat`` and the
+   following line can be added at the start of the script:
+
+   .. code-block:: batch
+
+      @py -x "%~f0" %* & exit /b
+
+   Or, to specify the path to the Python interpreter explicitly:
+
+   .. code-block:: batch
+
+      @"C:\Path\to\python.exe" -x "%~f0" %* & exit /b
+
+   Unlike a shebang line which is a Python comment, this line is not valid
+   Python syntax, and the :option:`-x` option is needed to skip it.
 
 
 .. option:: -X

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]