fix: venv site packages with pkgutil packages (#3268)

Currently, an error occurs if one packages files are intended to go into
a
sub-directory of another package's directory. This can happen when
pkgutil-style
namespace packages are used, which results in multiple distributions
wanting
to install the same files (pkgutil `__init__.py` files) into the same
top-level
directories. This eventually results in a Bazel error because Bazel
detects that
the one output is the prefix of another.

To fix, detect when distributions overlap in their paths and merge their
files
manually. Internally, entries are sorted from shorted venv path to
longest,
however, that's just an implementation detail.

Along the way, give agents better advice for bzl_library targets.

Fixes https://github.com/bazel-contrib/rules_python/issues/3204

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>