We ran into an issue with our library; we build a submodule named `math.so`, and have a test `math_test` which is ran in the same directory as this module (since this is how we've written it with Bazel's generated Python binaries):
https://github.com/RobotLocomotion/drake/issues/8041

This happens for us on HighSierra / Sierra MacOS (for *.py and *.so modules); Ubuntu Linux seems fine.

I have a reproduction script just for *.py files here:
https://github.com/EricCousineau-TRI/repro/blob/b08bc47/bug/mac_builtin_shadow/test.sh#L38
(attached this as `test.sh`)

The module is exposed on the path given that it neighbors the first execution of the `import_test.py` script. The second execution (where the `import_test.py` script is moved up one level) succeeds on Mac (s.t. the `math.py` is not in `sys.path`).

This behavior seems to violate the documentation:
https://docs.python.org/2/tutorial/modules.html#the-module-search-path

This is the expected behavior, fortunately or not. "math" is not builtin in the sense that is used in that paragraph.

Removing macOS since this isn't Mac specific.

This had me confused for a while.  But eric.smith's comment is the clue to what's going on here:

> This is the expected behavior, fortunately or not. "math" is not builtin in the sense that is used in that paragraph.

The difference in behavior that you are seeing seems to be due to the fact that the Debian/Ubuntu uses a non-standard build to build-in the standard lib "math" module, whereas the Mac version you are using undoubtedly does not.  You can see this behavior yourself if you build your own version of python (either 2.7 or 3.x) on your Ubuntu system.  You should now see the same behavior you see on the Mac.  For example:

# on a current Debian system
$ /usr/bin/python2.7 -c 'import sys,math;print(sys.modules["math"])'
<module 'math' (built-in)>

# on a current Mac system using the python.org 2.7.14
$ /usr/local/bin/python2.7 -c 'import sys,math;print(sys.modules["math"])'
<module 'math' from '/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload/math.so'>

So, I don't think this is an issue at all.  Please reopen if you think there is actually a problem here.

P.S. This issue points out once again why it is generally a bad idea to shadow or mix-and-match standard library module names.

> P.S. This issue points out once again why it is generally a bad idea to shadow or mix-and-match standard library module names.

Duly noted! And thank y'all for the explanations!

Can I ask if it's bad practice to use a standard library module name as a submodule, e.g. `example_module.math`?

TBH, this all arises because we use Bazel and wanted to modularize our tests - we place them under `test/{name}.py` neighboring the target (sub)module, and Bazel presently generates a wrapper script which is executed in the same directory as the (sub)module, which is why this (unintended) shadowing occurs.

I would like still like to have a submodule named `math`, so I can just teach our Bazel rules to not run the test in the same directory -- if having submodules named `math` is not frowned upon.

The example you gave caused problems because of the use of the ambiguous unqualified name "math".  If you are careful to use qualified names, and/or perhaps use alias names ("as") to increase readability, there shouldn't be any problems.

stage: resolved