Can I prefer my own code when there are duplicated module names?

[jwarwick-delfi]

First, I'm a big fan of this plugin, thank you to the author and contributors.

Here's my question: when searching for a module, if there are multiple modules on the path with the same name, can I configure the plugin to prefer my source code over modules installed in site-packages?

I've got a project set up as follows:

my_module/
    __init__.py
    ...
    docs/
        tests.md
tests/
    __init__.py
    ...
mkdocs.yml
pyproject.toml

I'm trying to collect documentation from my tests root. tests.md looks like this:

# Testing
::: tests

I believe mkdocs.yml is correctly configured:

plugins:
 - mkdocstrings:
      handlers:
          python:
            paths: [.]

When I render these docs, other python source is correctly collected/rendered, but "tests" is not.
From the logs, it seems like "tests" is actually being loaded from site-packges:

  mkdocstrings: Matched '::: tests'
│    ▹ DEBUG   -  griffe: Searching path(s) for tests
│    ▹ DEBUG   -  griffe: Found tests: loading
│    ▹ DEBUG   -  griffe: Loading path (omitted)/.venv/lib/python3.12/site-packages/tests/__init__.py

From manually looking at this path, it seems like this originates from one of my 3rd party dependencies, a bibtex parser package. I'm hoping there is an easy way to configure the plugin to prioritize my modules.

(edit) I've also tried setting "paths" to paths: [my_module, tests], and got the same result.

Thanks in advance for any help!

[pawamoy]

Hi @jwarwick-delfi thank you for the kind words! ❤️

From looking at your config it should pick up the tests module in the current folder 🤔 paths: [.] is the correct (and default) thing to do (paths: [my_module, tests] would not be correct, paths must be search paths, not paths to packages, and I know it's not super clear so I'll probably rename it search_paths in the future 😅).

Do you have a public repository I can try things on?

[jwarwick-delfi]

Thanks for the confirmation, here's an example repo - please let me know if you're able to reproduce the behavior

https://github.com/jwarwick-delfi/mkdspy-example-tests-issue

[pawamoy]

Thanks! Found the issue. We build the list of search paths by concatenating the user provided paths to sys.path. But when inserting in the final list, we check if the path is not already present, and in this case, it's already present, but in last position. In the end site-packages had precedence over the current folder. Will push a fix to mkdocstrings-python right now 🙂

[pawamoy]

Fixed in v1.16.1 🙂

[jwarwick-delfi]

Confirmed, your update works for me - thank you so much, especially for the quick response and turnaround!

[pawamoy]

Thanks for confirming 🎉!