Improve -x option documentation

[serhiy-storchaka]

BPO	32122
Nosy	@pfmoore, @vstinner, @tjguk, @zware, @serhiy-storchaka, @zooba

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-11-24.06:26:47.980>
labels = ['easy', 'type-feature', '3.10', 'OS-windows', 'docs']
title = 'Improve -x option documentation'
updated_at = <Date 2020-10-27.03:10:18.473>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2020-10-27.03:10:18.473>
actor = 'vstinner'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Windows']
creation = <Date 2017-11-24.06:26:47.980>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 32122
keywords = ['newcomer friendly']
message_count = 5.0
messages = ['306878', '307190', '307203', '307212', '379721']
nosy_count = 7.0
nosy_names = ['paul.moore', 'vstinner', 'tim.golden', 'docs@python', 'zach.ware', 'serhiy.storchaka', 'steve.dower']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32122'
versions = ['Python 3.10']

Linked PRs

• gh-76303: Improve -x option documentation #144857
• gh-76303: Improve documentation of the -x command line option #155559
• [3.15] gh-76303: Improve documentation of the -x command line option (GH-155559) #155565
• [3.14] gh-76303: Improve documentation of the -x command line option (GH-155559) #155566
• [3.13] gh-76303: Improve documentation of the -x command line option (GH-155559) #155567

[serhiy-storchaka]

The documentation of the -x option is virtually not existing. The current short line of the description was enough to me for understanding what is the purpose of this option and how it can be used (I didn't use Windows for more than 10 years). But I was surprised not founding more detailed information about this feature in the documentation. Definitely it should be better documented. Most of users will have no ideas about this feature.

The purpose of this option is turning Python scripts into Windows batch files which can be ran as other executables. Similarly as adding she-bang and setting the executable bit allows to run them on Unix. The extension of the Python script should be changed to ".bat", and the following line should be added at the start of the script:

@path\to\python -x %0 %* & exit /b

Or

@py -3 -x %0 %* & exit /b

Unlike a she-bang line which is a Python comment, this line is not valid Python syntax, and the -x option is used for skipping it.

[vstinner]

I don't know if "@path\to\python -x %0 %* & exit /b" and "@py -3 -x %0 %* & exit /b" are correct and well supported on all recent Windows versions.

Apart of that, I like your new documentation :-)

[zooba]

Those examples look fine to me

[serhiy-storchaka]

AFAIK this should work in Windows XP. And maybe even in Windows 2000.

[vstinner]

The -x command line option is now stored as PyConfig.skip_source_first_line, documented as:
"Skip the first line of the source?"
https://docs.python.org/dev/c-api/init_config.html#c.PyConfig.skip_source_first_line

Include/cpython/initconfig.h contains a longer comment:

/* Skip the first line of the source ('run_filename' parameter),
   allowing use of non-Unix forms of "#!cmd".
   This is intended for a DOS specific hack only.

       Set by the -x command line option. */
    int skip_source_first_line;