ITADN

bug: `docstring_style: sphinx` + any explicit `docstring_options` crashes: `parse_sphinx() got an unexpected keyword argument 'warn_missing_types'`

#337Openselbs 创建于 23 天前
bug
S
selbscommented
## Description With mkdocstrings-python 2.0.5 on griffelib 2.1.0, any configuration that uses `docstring_style: sphinx` **and sets at least one key under `docstring_options`** crashes on the first rendered docstring: ``` TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types' ``` Configurations with no `docstring_options` at all build cleanly, which makes this easy to miss in minimal testing: the empty case short-circuits before the bad kwarg is ever produced. ## Mechanism - `SphinxStyleOptions` still declares `warn_missing_types: bool = True` as a defaulted field (`mkdocstrings_handlers/python/_internal/config.py:252`, class at `:240`). - `PythonHandler.render` builds the parser options via `parser_options = options.docstring_options and asdict(options.docstring_options)` (`handler.py:198`). `asdict()` materializes **every** field of the dataclass — defaults included — so `warn_missing_types=True` is emitted as soon as `docstring_options` is non-empty. - The dict is assigned to `doc_object.docstring.parser_options` (`handler.py:246`) and forwarded by griffe (`griffe/_internal/models.py:183`: `parse(self, parser or self.parser, **(options or self.parser_options))`). - griffelib 2.1.0's `parse_sphinx` signature is `parse_sphinx(docstring, *, warn_unknown_params=True, warnings=True)` (`griffe/_internal/docstrings/sphinx.py:98`) — it no longer accepts `warn_missing_types`, so the call raises `TypeError`. Note the asymmetry: `parse_google` (`google.py:881`) **still accepts** `warn_missing_types`, so google-style configs are unaffected. Only the sphinx parser dropped the parameter, while `SphinxStyleOptions` still declares it. (griffelib's internal `_read_return` helper in `sphinx.py` still implements the `warn_missing_types` behavior — the kwarg was dropped from the public parser signature only.) ## Minimal reproducer (no mkdocs needed) ```python # venv: griffelib==2.1.0 from griffe import Docstring, Parser d = Docstring( ":param x: foo", parser=Parser.sphinx, parser_options={"warn_unknown_params": False, "warn_missing_types": True, "warnings": True}, ) d.parsed # TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types' ``` That `parser_options` dict is byte-for-byte what mkdocstrings-python 2.0.5 produces from the mkdocs config below. The same `Docstring` with `parser_options={}` parses fine — the false-negative path. ## mkdocs config that triggers it ```yaml plugins: - mkdocstrings: handlers: python: options: docstring_style: sphinx docstring_options: warn_unknown_params: false # any single key here is enough ``` ## Full-build traceback (excerpt) ``` TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types' ... mkdocstrings/_internal/extension.py:194, in _process_block rendered = render(data, options) mkdocstrings_handlers/python/_internal/handler.py:264, in render return template.render( ...templates/material/_base/module.html.jinja:94, in block 'docstring' griffe/_internal/models.py:163, in parsed return self.parse() griffe/_internal/models.py:183, in parse return parse(self, parser or self.parser, **(options or self.parser_options)) griffe/_internal/docstrings/parsers.py:53, in parse return parsers(docstring, **options) ``` The failure is content-independent — it fires on the first docstring rendered, regardless of what the docstring contains, and regardless of any griffe extensions in use. ## Environment - mkdocstrings-python 2.0.5 - griffelib 2.1.0 (sole provider of the `griffe` import; the legacy `griffe` 1.x distribution is **not** installed) - mkdocstrings 1.0.6 - Python 3.12.13 ## Suggested fix directions Any of: 1. Drop `warn_missing_types` from `SphinxStyleOptions` in mkdocstrings-python (align the options schema with `parse_sphinx`'s actual signature), or 2. Filter forwarded kwargs per parser signature before assigning `parser_options`, or 3. Re-accept `warn_missing_types` in griffelib's `parse_sphinx` and thread it through — the internal `_read_return` helper still implements it, so this restores documented behavior rather than adding new surface. Thank you.
1 条评论