fix: Give precedence to user-provided paths when they are already listed in sys.path

Issue-248: #248

Author: pawamoy

src/mkdocstrings_handlers/python/handler.py

@@ -128,9 +128,11 @@ def __init__(self, config: PythonConfig, base_dir: Path, **kwargs: Any) -> None:
             # If it's not absolute, make path relative to the config file path, then make it absolute.
             if not os.path.isabs(path):
                 path = os.path.abspath(base_dir / path)  # noqa: PLW2901
-            # Don't add duplicates.
-            if path not in search_paths:
-                search_paths.insert(0, path)
+            # Remove pre-listed paths.
+            if path in search_paths:
+                search_paths.remove(path)
+            # Give precedence to user-provided paths.
+            search_paths.insert(0, path)
 
         self._paths = search_paths
         self._modules_collection: ModulesCollection = ModulesCollection()

tests/test_handler.py

@@ -3,19 +3,19 @@
 from __future__ import annotations
 
 import os
+import sys
 from glob import glob
+from pathlib import Path
 from textwrap import dedent
 from typing import TYPE_CHECKING
 
 import pytest
 from griffe import DocstringSectionExamples, DocstringSectionKind, temporary_visited_module
 
-from mkdocstrings_handlers.python.config import PythonOptions
+from mkdocstrings_handlers.python.config import PythonConfig, PythonOptions
 from mkdocstrings_handlers.python.handler import CollectionError, PythonHandler
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from mkdocstrings.plugin import MkdocstringsPlugin
 
 
@@ -167,3 +167,15 @@ def function(self):
         module["Class.function"].lineno = None
         module["attribute"].lineno = None
         assert handler.render(module, PythonOptions(show_source=True))
+
+
+def test_give_precedence_to_user_paths() -> None:
+    """Assert user paths take precedence over default paths."""
+    last_sys_path = sys.path[-1]
+    handler = PythonHandler(
+        base_dir=Path("."),
+        config=PythonConfig.from_data(paths=[last_sys_path]),
+        mdx=[],
+        mdx_config={},
+    )
+    assert handler._paths[0] == last_sys_path