Python has a -x option documented as a "DOS specific hack only":
https://docs.python.org/dev/using/cmdline.html#cmdoption-x

Python doesn't support MS-DOS since Python 2.1:
https://www.python.org/dev/peps/pep-0011/#no-longer-supported-platforms

I propose to deprecate the option in Python 3.7: using it emits a DeprecationWarning, option deprecated in the documentation; and remove the option in Python 3.8.

The note in the documentation is wrong: the line number is correct when using the -x option, even if the first line is skipped.

Example with Python 2.7:
---
$ cat x.py 
print(1)
print(2)
x

$ python2 x.py 
1
2
Traceback (most recent call last):
  File "x.py", line 3, in <module>
    x
NameError: name 'x' is not defined

$ python2 -x x.py 
2
Traceback (most recent call last):
  File "x.py", line 3, in <module>
    x
NameError: name 'x' is not defined
---

Attached PR 4423 fixes Python 2.7 documentation.

Python still supports Windows.

> Python still supports Windows.

What is the use case for this option on Windows?

On Unix, the first line is usually used for the shebang, a line like:

   #!/usr/bin/env python3

But this shebang is seen as a comment in Python and Python simply ignore the shebang, seen as a comment.

The same as on DOS.

Change the extension of the Python script from .py to .bat, and insert the following first line:

@path\to\python -x %0 %1 %2 %3 %4 %5 %6 %7 %8 %9

Now you can run it as a bat-file. The command in the first line will run Python, passing the name of this file and up to 9 arguments (you can make it passing more than 9 arguments, but I don't remember the syntax). "@" disables printing this command itself. The first line is not valid Python syntax, but due to the -x option it will be skipped.

> @path\to\python -x %0 %1 %2 %3 %4 %5 %6 %7 %8 %9

Oh wow, I never saw that before.

There is now a "py" launcher on Windows, do we still need such "hack"?

Yes, of course. The py launcher is not an alternative to this "hack". It just allows you to specify just "py" (with possible options -2, -3, -3.6) instead of hardcoding the full name to the Python binary or add the path to directory containing the Python binary to your PATH.

So the hack is not specific to DOS but is still needed for Windows .bat files. They run in Command Prompt, which was once called the DOS box.  (I don't know if they work unaltered in PowerShell.)  It seems that the doc should be updated.

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.

It seems to me that the best way is to add the following line at the start of the script:

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

Or

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

Ok, I will update the doc instead of deprecating the option.

New changeset 733b5f3f2f2425fa939d71bc317f2e0f1968c2a0 by Victor Stinner in branch '2.7':
bpo-32050: Fix -x option documentation (#4423)
https://github.com/python/cpython/commit/733b5f3f2f2425fa939d71bc317f2e0f1968c2a0

New changeset c5a2071586f735d2a61d1756e7011cfbb6ce86c9 by Victor Stinner in branch 'master':
bpo-32050: Fix -x option documentation (#4475)
https://github.com/python/cpython/commit/c5a2071586f735d2a61d1756e7011cfbb6ce86c9

New changeset 60a376cf0023d1070329d0e861a5596637ff3275 by Victor Stinner (Miss Islington (bot)) in branch '3.6':
bpo-32050: Fix -x option documentation (GH-4475) (#4477)
https://github.com/python/cpython/commit/60a376cf0023d1070329d0e861a5596637ff3275

I removed the note from the documentation since it was outdated.

Serhiy, Terry: Do you want to work on a patch to rephrase the "DOS specific hack only" sentence?

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

I'm not a BATCH expert, so I don't know if this command works on all Windows version, or even on MS-DOS. So I'm not confident to propose such doc change myself, sorry.

I don't know either.  Once of the Windows experts should review and revise.

The initial proposition was to *deprecate* the option.

In the meanwhile, I removed an outdated note.

While the documentation is not perfect, I don't feel confortable to fix it, so I left it unchanged.

I close this PR. Please open a new issue (with a PR if possible ;-)) if you want to enhance -x option documentation.