The doc for `-m` command doesn't completely state how the code is looked up

[d-s-dc]

The current python doc for -m option of python command states this

Search sys.path for the named module and execute its contents as the main module.

and this

As with the -c option, the current directory will be added to the start of sys.path.

This would mean a file with any name, even if it matches with a builtin command would be run as long as we run the python -m command from the directory of the file. This is not completely true.

If you name a file os.py (although no one would in reality, but the point is to just correct the doc) and run python -m os from the same directory, the custom file isn't run. It is because os is already imported when python is setting up, it is there in sys.modules even before the code is looked up. And the standard import process first looks at sys.modules and stops there.

So, the standard import process is used for looking up the code and not just the sys.path. It is clearly stated in the docs for runpy.run_module which provides the same functionality as -m

The module’s code is first located using the standard import mechanism ...

So, the doc for -m should state the same.

Linked PRs

• gh-129851: Fix the documentation for -m command #129861
• gh-129851: Fix the documentation for -m command #129862
• [3.15] gh-129851: Fix the documentation for -m command (GH-129862) #150614
• [3.14] gh-129851: Fix the documentation for -m command (GH-129862) #150619
• [3.13] gh-129851: Fix the documentation for -m command (GH-129862) (GH-150619) #150620

[d-s-dc]

If allowed, I would like to contribute for the same.

[StanFromIreland]

You are, everyone is allowed to contribute. :-)

Advice for contributing to Python (and most of it applies to all opensource projects) can be found in the devguide.

[d-s-dc]

I had some issue signing the CLA because of my email. I closed the first pr and have raised a new one. Only consider the second pr for the fix.

[d-s-dc]

Hey @StanFromIreland, there has been no update on this. What should I do?