[python] Implicit import paths can shadow explicit import paths?

[EricCousineau-TRI]

Description of the bug:

In RobotLocomotion/drake-ros#253, I am observing the shadowing of explicitly specified py_library(*, imports) by implicitly created imports, which seems defective, regardless of whether implicit __init__.py files are created or not?

What's the simplest, easiest way to reproduce this bug? Please provide a minimal example if possible.

Reduced min repro:
https://github.com/EricCousineau-TRI/repro/blob/7860b324b5864ff0268e9a8d0ea991e9792b9fd1/bazel/bazel_issue_17691/self_contained_repro.sh

#!/bin/bash
set -eux

bazel version

rm -rf build
mkdir build && cd build

# Create external repository.
mkdir repo && pushd repo
cat > WORKSPACE <<EOF
workspace(name = "repo")
EOF
cat > BUILD <<EOF
py_library(
    name = "repo_py",
    deps = ["//repo"],
    visibility = ["//visibility:public"],
)
EOF
# Simulate nested Python package with same name as parent.
mkdir repo && cd repo
cat > BUILD <<EOF
py_library(
    name = "repo",
    srcs = ["__init__.py"],
    imports = [".."],
    visibility = ["//:__pkg__"],
)
EOF
cat > __init__.py <<EOF
my_special_symbol = 1
EOF
popd

mkdir example && pushd example
cat > WORKSPACE <<EOF
workspace(name = "example")

local_repository(
    name = "repo",
    path = "../repo",
)
EOF
cat > BUILD <<EOF
py_binary(
    name = "example_consuming_repo",
    srcs = ["example_consuming_repo.py"],
    deps = ["@repo//:repo_py"],
)
EOF
cat > print_paths.py <<EOF

EOF
cat > example_consuming_repo.py <<EOF
# print paths
import os, re, sys

def reformat(x):
    source = os.path.dirname(os.path.realpath(__file__))
    x = x.replace(source, "{source}")
    x = re.sub(r"^/.*?\.runfiles", "{runfiles}", x)
    return x

print("\n".join(reformat(x) for x in sys.path))

# try import
from repo import my_special_symbol
EOF

echo "---"
bazel run -s //:example_consuming_repo

Output:

{source}
{runfiles}
{runfiles}/repo
{runfiles}/bazel_tools
{runfiles}/example
/usr/lib/python310.zip
/usr/lib/python3.10
/usr/lib/python3.10/lib-dynload
/usr/local/lib/python3.10/dist-packages
/usr/lib/python3/dist-packages
/usr/lib/python3.10/dist-packages
...
ImportError: cannot import name 'my_special_symbol' from 'repo' (.../example_consuming_repo.runfiles/repo/__init__.py)

At present, there's a heavy repro as indicated in the issue.

Which operating system are you running Bazel on?

Ubuntu 22.04

What is the output of bazel info release?

release 5.3.1

If bazel info release returns development version or (@non-git), tell us how you built Bazel.

No response

What's the output of git remote get-url origin; git rev-parse master; git rev-parse HEAD ?

$ git remote get-url origin; git rev-parse main; git rev-parse HEAD
git@github.com:EricCousineau-TRI/drake-ros.git
8b765affaa5b963601020df1851a59a036c68ee4
7a36ec32fc38c2328ec6aaadd9e83e8a956a99f5

Have you found anything relevant by searching the web?

Relates #7386

Any other information, logs, or outputs that you want to share?

No response