warn users if both dir and module exist with the same name, refs #233

Author: mhils

CHANGELOG.md

@@ -4,6 +4,8 @@
 
  - Private function decorators (those starting with "\_")
    are now hidden by default. (@zmoon)
+ - If pdoc is invoked with a name that is both an installed Python module 
+   and a local directory, notify the user that the installed module will be documented.
 
 # 2021-03-10: pdoc 6.4.0
 

pdoc/extract.py

@@ -159,11 +159,36 @@ def parse_spec(spec: Union[Path, str]) -> str:
     *This function has side-effects:* `sys.path` will be amended if the specification is a path.
     If this side-effect is undesired, pass a module name instead.
     """
-    # isinstance check is required as Path is not iterable.
-    if not isinstance(spec, Path) and (
+    pspec = Path(spec)
+    if isinstance(spec, str) and (
         os.sep in spec or (os.altsep and os.altsep in spec)
     ):
-        spec = Path(spec)
+        # We have a path separator, so it's definitely a filepath.
+        spec = pspec
+
+    if isinstance(spec, str) and (pspec.is_file() or (pspec / "__init__.py").is_file()):
+        # We have a local file with this name, but is there also a module with the same name?
+        try:
+            with mock_some_common_side_effects():
+                modspec = importlib.util.find_spec(spec)
+                if modspec is None:
+                    raise ModuleNotFoundError
+        except AnyException:
+            # Module does not exist, use local file.
+            spec = pspec
+        else:
+            # Module does exist. We now check if the local file/directory is the same (e.g. after pip install -e),
+            # and emit a warning if that's not the case.
+            origin = Path(modspec.origin).absolute() if modspec.origin else Path("unknown")
+            local_dir = Path(spec).absolute()
+            if local_dir not in (origin, origin.parent):
+                print(
+                    f"Warning: {spec!r} may refer to either the installed Python module or the local file/directory "
+                    f"with the same name. pdoc will document the installed module, prepend './' to force "
+                    f"documentation of the local file/directory.\n"
+                    f" - Module location: {origin}\n"
+                    f" - Local file/directory: {local_dir}"
+                )
 
     if isinstance(spec, Path):
         if (spec.parent / "__init__.py").exists():
@@ -191,7 +216,8 @@ def module_mtime(modulename: str) -> Optional[float]:
     """Returns the time the specified module file was last modified, or `None` if this cannot be determined.
     The primary use of this is live-reloading modules on modification."""
     try:
-        spec = importlib.util.find_spec(modulename)
+        with mock_some_common_side_effects():
+            spec = importlib.util.find_spec(modulename)
     except AnyException:
         pass
     else:

test/test_extract.py

@@ -44,6 +44,24 @@ def test_parse_spec():
     sys.path = p
 
 
+def test_parse_spec_mod_and_dir(capsys, tmp_path, monkeypatch):
+    """Test that we display a warning when both a module and a local directory exist with the provided name."""
+    (tmp_path / "dataclasses").mkdir()
+    (tmp_path / "dataclasses" / "__init__.py").touch()
+    monkeypatch.chdir(tmp_path)
+
+    assert parse_spec("dataclasses") == "dataclasses"
+    captured = capsys.readouterr()
+    assert captured.out.startswith(
+        "Warning: 'dataclasses' may refer to either the installed Python module or the local file/directory"
+    )
+
+    monkeypatch.chdir(here / "testdata")
+    assert parse_spec("demo.py") == "demo"
+    captured = capsys.readouterr()
+    assert not captured.out
+
+
 def test_module_mtime():
     assert module_mtime("dataclasses")
     assert module_mtime("unknown") is None