mangle_docstrings triggers RemovedInSphinx11Warning via deprecated mapping interface

[gaborbernat]

Description

mangle_docstrings at numpydoc.py:191 calls cfg.update(options or {}) where options is a _AutoDocumenterOptions instance passed by Sphinx's autodoc-process-docstring event.

Since Sphinx 10, _AutoDocumenterOptions emits RemovedInSphinx11Warning when its mapping interface (__iter__, __getitem__, etc.) is used. dict.update() triggers __iter__ on the options object, producing:

The mapping interface for autodoc options objects is deprecated,
and will be removed in Sphinx 11. Use attribute access instead.

Suggested fix

Replace the try/except block:

# current
try:
    cfg.update(options or {})
except TypeError:
    cfg.update(options.__dict__ or {})

with:

if options is not None:
    cfg.update(vars(options))

vars(options) returns the instance __dict__ directly, avoiding the deprecated mapping interface entirely. This works because _AutoDocumenterOptions.__init__ stores all attributes via vars(self).update(kwargs).

Related

• Custom configuration classes break numpydoc sphinx-doc/sphinx#13942 (the original breakage that led to the current try/except workaround)
• https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/_directive_options.py (where the deprecation warnings are emitted)

[hiSandog]

vars(options) avoids the deprecated mapping protocol, but it may expose private implementation attributes if Sphinx adds them later. Filtering to the option names numpydoc actually consumes would make the boundary more robust; at minimum, tests against Sphinx 10 with deprecations treated as errors and the Sphinx 11 prerelease would validate the transition. A plain dict fixture should remain covered if that older event shape is still supported.