diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05e4e3ed..127f5295 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+## [1.16.1](https://github.com/mkdocstrings/python/releases/tag/1.16.1) - 2025-02-18
+
+[Compare with 1.16.0](https://github.com/mkdocstrings/python/compare/1.16.0...1.16.1)
+
+### Bug Fixes
+
+- Give precedence to user-provided paths when they are already listed in `sys.path` ([0f497d1](https://github.com/mkdocstrings/python/commit/0f497d185ba1860c61555803bfc4b311a410bd39) by Timothée Mazzucotelli). [Issue-248](https://github.com/mkdocstrings/python/discussions/248)
+
## [1.16.0](https://github.com/mkdocstrings/python/releases/tag/1.16.0) - 2025-02-17
[Compare with 1.15.1](https://github.com/mkdocstrings/python/compare/1.15.1...1.16.0)
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
index 30cd2058..0051be0f 100644
--- a/src/mkdocstrings_handlers/python/handler.py
+++ b/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()
diff --git a/tests/test_handler.py b/tests/test_handler.py
index 365b5f23..7cf8dc54 100644
--- a/tests/test_handler.py
+++ b/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