The doc for -m command doesn't completely state how the code is looked up #129851
Description
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.