bug: `merge_init_into_class` renders inherited `__init__` source (leaks site-packages paths)

[cdwilson]

Description of the bug

With merge_init_into_class: true, the source block in
templates/material/_base/class.html.jinja unconditionally prefers
all_members["__init__"] over the class itself:

{% if config.merge_init_into_class %}
  {% if "__init__" in all_members and all_members["__init__"].source %}

all_members includes inherited members, so when a class does not
define __init__ itself (e.g. any pydantic BaseModel subclass, with
preload_modules: [pydantic] so griffe can resolve the base), the
rendered source block is pydantic.BaseModel.__init__ with a summary
like:

Source code in .venv/lib/python3.10/site-packages/pydantic/main.py

instead of the documented class's own file. Two problems:

1. The environment-specific .venv/... path leaks into published docs.
2. The source shown is the base class's __init__, which is not the
   documented object's code at all.

Additionally, when the merged __init__ has no source, the block
renders nothing rather than falling back to the class source.

To Reproduce

Verified with mkdocs 1.6.1, mkdocstrings 1.0.4, mkdocstrings-python
2.0.5, griffe 2.1.0, pydantic 2.13.4 on Python 3.10.

mkdir -p repro/src/pkg repro/docs && cd repro
python -m venv .venv && . .venv/bin/activate
pip install mkdocs mkdocs-material "mkdocstrings[python]" pydantic

src/pkg/__init__.py:

from pydantic import BaseModel


class Model(BaseModel):
    """A pydantic model without its own `__init__`."""

    x: int = 0

docs/index.md:

::: pkg.Model

mkdocs.yml:

site_name: repro
theme:
  name: material
plugins:
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            merge_init_into_class: true
            preload_modules: [pydantic]
            show_source: true

Build and inspect the rendered source block:

$ mkdocs build
$ grep -o "Source code in <code>[^<]*</code>" site/index.html
Source code in <code>.venv/lib/python3.10/site-packages/pydantic/main.py</code>

Expected: src/pkg/__init__.py.

The mechanism, shown at the griffe level (run from the same directory):

import sysconfig

import griffe

loader = griffe.GriffeLoader(
    search_paths=["src", sysconfig.get_paths()["purelib"]]
)
loader.load("pydantic")
pkg = loader.load("pkg")
loader.resolve_aliases()

cls = pkg["Model"]
init = cls.all_members["__init__"]
print(cls.relative_filepath)   # src/pkg/__init__.py
print(init.inherited)          # True
print(init.relative_filepath)  # .venv/lib/python3.10/site-packages/pydantic/main.py

Expected behavior

Only use __init__'s source when the class defines it itself
(griffe exposes inherited on the member); otherwise fall back to the
class's own source.

Environment information

python -m mkdocstrings_handlers.python._internal.debug  # | xclip -selection clipboard

• System: macOS-26.5.1-arm64-arm-64bit
• Python: cpython 3.10.20 (/.venv/bin/python3)
• Environment variables:
• Installed packages:
  • mkdocstrings-python v2.0.5

Additional context

I'm using a template override in
docs/templates/python/materialx/class.html.jinja, wired
up via the custom_templates option in mkdocs.yaml:

{% extends "_base/class.html.jinja" %}

{% block source %}
  {% import "language.html.jinja" as lang with context %}
  {% if config.show_source %}
    {% if config.merge_init_into_class
        and "__init__" in all_members
        and not all_members["__init__"].inherited
        and all_members["__init__"].source %}
      {% with init = all_members["__init__"] %}
        <details class="mkdocstrings-source">
          <summary>{{ lang.t("Source code in") }} <code>
            {%- if init.relative_filepath.is_absolute() -%}
              {{ init.relative_package_filepath }}
            {%- else -%}
              {{ init.relative_filepath }}
            {%- endif -%}
          </code></summary>
          {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
        </details>
      {% endwith %}
    {% elif class.source %}
      <details class="mkdocstrings-source">
        <summary>{{ lang.t("Source code in") }} <code>
          {%- if class.relative_filepath.is_absolute() -%}
            {{ class.relative_package_filepath }}
          {%- else -%}
            {{ class.relative_filepath }}
          {%- endif -%}
        </code></summary>
        {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
      </details>
    {% endif %}
  {% endif %}
{% endblock source %}

[pawamoy]

Thanks for the report @cdwilson. I'm afraid this is a case of user preference. Some users want to use the inherited __init__ method, others don't. This was requested here #106 (I'm the author but the feature was asked for while working on providing API docs in Python-Markdown). Even in cases where the inherited __init__ method comes from an external, uncontrolled package, it might be desirable to still merge its __init__ method docstring into the class' docstring, to properly document the parameters it accepts.

We could consider adding an option to include-list some packages from which we can use inherited __init__ methods, so that you would leave it empty, meaning "from self package only", implicitly excluding Pydantic. But this would be a new feature and mkdocstrings and its Python handler are in maintenance mode, which means no new features are added.

Since you found a workaround using templating, and since it's also possible to set merge_init_into_class: false for the relevant classes (your subclasses of pydantic.BaseModel), I'm gonna close this issue invoking maintenance mode 🙂 Regarding the leaked venv path, it's also possible to set show_source: false on the class symbol.

Always happy to hear your thoughts on this of course.

[cdwilson]

@pawamoy couple questions before I submit a PR from our discussion in tinydantic/tinydantic#131:

1. Do you want to re-open this issue so the PR can close it out? Or do you just want me to submit the PR independent of this issue?

2. You had mentioned that you're OK with "Fall back to the class source when the merged init has no source, instead of rendering nothing". However, as I was thinking about this a bit more, I wanted to double check if this is actually a good change.

   When merge_init_into_class: false and show_source: true, the docs show both the source for the entire class and the source for the __init__ methods (which makes sense since they are displayed in separate sections). Currently, when merge_init_into_class: true, we are effectively saying "skip showing the class source and show the __init__ source instead". If we change the current behavior to fall back to showing the class source, then we have a mishmash of full class and __init__ sources depending on whether __init__ source is available, which might be surprising and arguably incongruous behavior depending on how you look at it.

   What do you think? Claude had suggested this change in the draft it wrote up, but I'm on the fence about which is the correct behavior.

3. Your suggestion "site-packages" in init.relative_filepath raises at render time, because relative_filepath is a pathlib.Path, which Jinja's in cannot iterate. Claude suggested "site-packages" in init.relative_filepath.parts an exact path-segment match, which also avoids matching directory names that merely contain the substring. LMK if this is OK or if you want something else.

   {%- if init.relative_filepath.is_absolute() or "site-packages" in init.relative_filepath.parts -%}
   

[pawamoy]

2. Right, good point. I think currently it displays a "Source code" admonition, but empty, so the fix would rather be to not render the admonition at all (instead of adding the class source). I checked and in fact nothing is rendered if there's no __init__ source, so nothing to fix here.
3. "site-packages" in init.relative_filepath.parts sounds good!