Improve warnings in editable install

CHANGES.rst

@@ -8,7 +8,7 @@ Changes
 
 Documentation changes
 ^^^^^^^^^^^^^^^^^^^^^
-* #3554: Changed requires to requests in the pyproject.toml example in the :ref:`Dependency management section of the Quickstart guide <userguide/quickstart:dependency-management>` -- by :user:`mfbutner`
+* #3554: Changed requires to requests in the pyproject.toml example in the :doc:`Dependency management section of the Quickstart guide <userguide/quickstart>` -- by :user:`mfbutner`
 
 Misc
 ^^^^
@@ -44,7 +44,7 @@ Changes
 
 Documentation changes
 ^^^^^^^^^^^^^^^^^^^^^
-* #3538: Corrected documentation on how to use the `legacy-editable` mode.
+* #3538: Corrected documentation on how to use the ``legacy-editable`` mode.
 
 
 v65.0.2

changelog.d/3569.misc.rst

@@ -0,0 +1,2 @@
+Improved information about conflicting entries in the current working directory
+and editable install (in documentation and as an informational warning).

docs/userguide/development_mode.rst

@@ -155,6 +155,10 @@ Limitations
   projects structured using :ref:`flat-layout` is still **experimental**.
   If you experience problems, you can try converting your package structure
   to the :ref:`src-layout`.
+- File system entries in the current working directory
+  whose names coincidentally match installed packages
+  may take precedence in :doc:`Python's import system <python:reference/import>`.
+  Users are encouraged to avoid such scenarios [#cwd]_.
 
 .. attention::
    Editable installs are **not a perfect replacement for regular installs**
@@ -240,6 +244,13 @@ More information is available on the text of :pep:`PEP 660 <660#what-to-put-in-t
    packages created with ``pkgutil`` or ``pkg_namespaces``, however this is not
    officially supported.
 
+.. [#cwd]
+   Techniques like the :ref:`src-layout` or tooling-specific options like
+   `tox's changedir <https://tox.wiki/en/stable/config.html#conf-changedir>`_
+   can be used to prevent such kinds of situations (chekout `this blog post
+   <https://blog.ganssle.io/articles/2019/08/test-as-installed.html>`_ for more
+   insights).
+
 .. [#installer]
    For this workaround to work, the installer tool needs to support legacy
    editable installations. (Future versions of ``pip``, for example, may drop

setuptools/build_meta.py

@@ -437,9 +437,10 @@ def build_editable(
             info_dir = self._get_dist_info_dir(metadata_directory)
             opts = ["--dist-info-dir", info_dir] if info_dir else []
             cmd = ["editable_wheel", *opts, *self._editable_args(config_settings)]
-            return self._build_with_temp_dir(
-                cmd, ".whl", wheel_directory, config_settings
-            )
+            with suppress_known_deprecation():
+                return self._build_with_temp_dir(
+                    cmd, ".whl", wheel_directory, config_settings
+                )
 
         def get_requires_for_build_editable(self, config_settings=None):
             return self.get_requires_for_build_wheel(config_settings)

setuptools/command/editable_wheel.py

@@ -393,7 +393,7 @@ def __call__(self, wheel: "WheelFile", files: List[str], mapping: Dict[str, str]
     def __enter__(self):
         msg = f"""
         Editable install will be performed using .pth file to extend `sys.path` with:
-        {self.path_entries!r}
+        {list(map(os.fspath, self.path_entries))!r}
         """
         _logger.warning(msg + _LENIENT_WARNING)
         return self
@@ -503,7 +503,11 @@ def __enter__(self):
         return self
 
     def __exit__(self, _exc_type, _exc_value, _traceback):
-        ...
+        msg = """\n
+        Please be careful with folders in your working directory with the same
+        name as your package as they may take precedence during imports.
+        """
+        warnings.warn(msg, InformationOnly)
 
 
 def _can_symlink_files(base_dir: Path) -> bool: