upstream(mkdocstrings-python): merge_init_into_class labels inherited __init__ with a .venv path #131

Tracking issue for upstream friction in mkdocstrings/python. Nothing here is posted upstream without explicit approval.

Status

How tinydantic is affected today

Not affected. mkdocs.yaml sets merge_init_into_class: false, and the bug only fires when that option is true.

The history is worth recording, because it is the reason the option is off:

• 2c13cbd (2026-07-06) turned the option on and added a custom class.html.jinja template override, wired via custom_templates, to correct the source label.
• cea64e4 (2026-07-09) reverted that. There is no template override in the tree now (docs/templates/ does not exist), and the option stays false.

So the live cost is only that merge_init_into_class is unavailable to this project — it would document the parameters a model accepts, which is the behavior we actually want — until the upstream label bug is fixed. Turning it on again reintroduces the leak.

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 — any pydantic BaseModel subclass, with preload_modules: [pydantic] so griffe can resolve the base — the rendered block is pydantic.BaseModel.__init__, summarized as:

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

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.

Expected behavior

Use __init__'s source only when the class defines it itself (griffe exposes inherited on the member); otherwise fall back to the class's own source, as the non-merged branch does.

Reproduction

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 at the griffe level, 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

Draft collateral — DO NOT POST WITHOUT APPROVAL

Draft reply to the close comment on #333

Thanks @pawamoy — completely agree that merging the inherited __init__ docstring/signature is a matter of preference, and it's actually the behavior I want (it documents the parameters the class accepts). I should have separated the two concerns better in the report.

The part I'd argue isn't preference is the label on the source block. The template already goes out of its way to never show environment paths: when relative_filepath is absolute, it falls back to relative_package_filepath. An in-project virtualenv (.venv/…, the default layout for uv and python -m venv users) just slips past that check because the path happens to be relative to the CWD. So, with maintenance mode in mind, would you consider this narrow change a bugfix rather than a feature?

{%- if init.inherited or init.relative_filepath.is_absolute() -%}
  {{ init.relative_package_filepath }}

i.e. keep rendering the inherited __init__ source exactly as today, just label it pydantic/main.py (as the absolute-path fallback already would) instead of .venv/lib/python3.10/site-packages/pydantic/main.py. One caveat I've verified: for an __init__ inherited from a base in the same package, the label changes from src/pkg/base.py to pkg/base.py.

Happy to send a PR covering both the material and readthedocs templates if you're open to it. (On a related note: when the merged __init__ has no source, the block currently renders nothing rather than falling back to the class source — I could include that fallback in the same PR or leave it as is, your call.)

Draft PR

Both changes verified in a standalone repro against mkdocstrings-python 2.0.5: inherited-from-pydantic renders pydantic/main.py; same-package inherited renders pkg/__init__.py (was src/pkg/__init__.py).

Commit 1 — the label fix (bugfix-scoped). In src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja, and the identical line in readthedocs/_base/class.html.jinja:

                 {% with init = all_members["__init__"] %}
                   <details class="mkdocstrings-source">
                     <summary>{{ lang.t("Source code in") }} <code>
-                      {%- if init.relative_filepath.is_absolute() -%}
+                      {%- if init.inherited or init.relative_filepath.is_absolute() -%}
                         {{ init.relative_package_filepath }}
                       {%- else -%}
                         {{ init.relative_filepath }}

Commit 2 (optional — offer it in the reply first). Fall back to the class source when the merged __init__ has no source, instead of rendering nothing:

           {% if config.show_source %}
-            {% if config.merge_init_into_class %}
-              {% if "__init__" in all_members and all_members["__init__"].source %}
-                {% with init = all_members["__init__"] %}
-                  ...
-                {% endwith %}
-              {% endif %}
+            {% if config.merge_init_into_class
+                and "__init__" in all_members
+                and all_members["__init__"].source %}
+              {% with init = all_members["__init__"] %}
+                ...
+              {% endwith %}
             {% elif class.source %}

Note for the PR: check mkdocstrings-python's rendering snapshot tests — the label change requires regenerating snapshots for any fixture class with an inherited __init__.

If this is closed without an upstream fix

Then merge_init_into_class stays false permanently, and that should be stated as a decision — a one-line comment in mkdocs.yaml saying why, so the next person does not turn it on and reintroduce the leak.

Migrated on 2026-08-12 from untracked/upstream/mkdocstrings-python-merged-init-source-path.md (drafted 2026-07-09), under the AGENTS.md rule that upstream work is tracked as an issue here rather than as a markdown file.

Assisted-by: Claude:claude-opus-5