You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
TRACKING: Problems in the new implementation of autodoc #14089
The next version of Sphinx contains a substantially rewritten (#13751) implementation of the sphinx.ext.autodoc extension.
This issue tracks regressions and missing features in the new implementation, with the view that we will eventually deprecate and remove the legacy class-based implementation.
To use the old (Sphinx 8.2 and earlier, class-based) implementation, set autodoc_use_legacy_class_based = True in your conf.py.
Please add a comment on this issue if you need to enable autodoc_use_legacy_class_based = True, ideally with a link to your project/the code that interacts with sphinx.ext.autodoc.
changed the title [-]Tracking issue for missing features in the new implementation of autodoc[/-][+]Tracking issue for problems in the new implementation of autodoc[/+]on Nov 25, 2025
changed the title [-]Tracking issue for problems in the new implementation of autodoc[/-][+]TRACKING: Problems in the new implementation of autodoc[/+]on Nov 25, 2025
Hi, not sure if this is the right place to ask help on new implementation, but given that what I'm facing is actually a problem with it... 😉
In a couple of projects, where I'm still using Sphinx v7, I was able to override the default AttributeDocumenter with a custom one, that recognizes class attributes initialized with a SQL literals (more specifically, psycopg2 SQL instances), that it renders as a .. code-block:: postgresql:
fromsphinx.extimportautodocclassAttributeDocumenter(autodoc.AttributeDocumenter):
"""Customized AttributeDocumenter that knows about ``SQL`` literals."""defadd_directive_header(self, sig):
"""Omit the raw value in case of SQL instances."""ifnotisinstance(self.object, Psycopg2SQL.Composable):
autodoc.AttributeDocumenter.add_directive_header(self, sig)
else:
autodoc.ClassLevelDocumenter.add_directive_header(self, sig)
defadd_content(self, more_content):
"""Prettify SQL statements."""autodoc.AttributeDocumenter.add_content(self, more_content)
ifisinstance(self.object, Psycopg2SQL.Composable):
sql=self.object.as_string(None)
self.add_line('', '')
self.add_line('.. code-block:: postgresql', '')
self.add_line('', '')
forlineinsql.splitlines():
self.add_line(' '+line, '')
defsetup(app):
"""Setup the Sphinx environment."""fromdocutils.parsers.rstimportdirectivesapp.add_autodocumenter(AttributeDocumenter)
I tried to follow the new implementation, but I failed to see a way to do something like that (didn't try setting the use legacy classes option yet, but OTOH I'm looking forward...).
Hi! The issue said to leave a comment here if we had to use autodoc_use_legacy_class_based = True so here I am 😄
The regression appears to be that the new implementation assumes everything can be weak-referenced, but that's not always the case. In our case, when using zope.deprecation or zope.deferredimport, sys.modules will contain ModuleProxy objects that cannot be weak referenced. This results in a TypeError (full report attached):
File "///lib/python3.13/site-packages/sphinx/ext/autodoc/_dynamic/_type_comments.py", line 53, in _ensure_annotations_from_type_comments
_objects_with_type_comment_annotations.add(obj)
File "/opt/local/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/_weakrefset.py", line 88, in add
self.data.add(ref(item, self._remove))
TypeError: cannot create weak reference to 'ModuleProxy' object
Setting autodoc_use_legacy_class_based = True solves the issue.
I'm attaching an archive of a simple project that demonstrates the issue. You'll need to have zope.interface and zope.deferredimport installed. (I run sphinx-build -vv -b html -d docs/_build/html docs docs/_build/html from the extracted directory to produce the error.)
It took me a while to narrow this down to a simple reproducer.
We're documenting one module in index.rst:
Test documentation
==================
.. automodule:: module
(I have autodoc_default_options set with 'members': None but I assume setting it directly on the directive works as well)
Contents of module.py:
fromzope.interfaceimportInterfacefrom_moduleimportBaseclassIWithTypes(Interface):
"This class must be documented."defmethod(thing:str):
# This method doesn't have to be documented.passclassFoo(Base):
"Must be documented"# This doesn't have to be documented.CLEANUP_IFACE=IWithTypes
where _module.py is:
classBase:
# Doesn't have to be documented.passfromzopeimportdeferredimportdeferredimport.initialize()
deferredimport.deprecatedFrom(
"Import from elsewhere",
"module.to.import",
"name_in_module",
)
The keys to reproduce are:
Foo needs to have a base class;
That base class needs to be in a module that is replaced with a non-weak-referencable object (done here with zope.deferredimport which uses a ModuleProxy object that isn't weak-referencable: It extends zope.proxy.ProxyBase, a C extension, and specifies __slots__);
Foo needs to have an object that is documented and contains a method with type annotations. A plain class doesn't trigger the error, but interface classes do, and I would imagine other classes that play tricks with metatypes could as well.
I was using sphinx.ext.autodoc.logger in my zopeext.autointerface module. This is breaks interactions with Sphinx 9 sphinx-contrib/zopeext#17. Probably an easy fix, but reporting here for coverage.
Yes, looks very much like the same issue. I have also included more info in #14337 what causes this (looks like autodoc reinjects __annotations__ after pydantic deletes them).
It's not my project, but I found myself having to set autodoc_use_legacy_class_based = True in invocations to get things working with current Sphinx versions: pyinvoke/invocations#47
Our project also needs autodoc_use_legacy_class_based = True for Sphinx to run. It's a Django app. Somehow I only ran into this issue in GitLab CI. On my laptop everything built fine without.
Traceback
=========
File "/builds/heliport/heliport/.cache/poetry/virtualenvs/heliport-c9km1fGm-py3.11/lib/python3.11/site-packages/sphinx/util/inspect.py", line 549, in object_description
raise ValueError from exc
ValueError
Our project also needs the legacy interface since it uses the sphinx-interrogatedb extension which subclasses the regular Documenter classes to source the members, docstrings, signatures etc. from a separate database file, which is generated by our Python binding generation tool, interrogate.
This matters because the documented objects are compiled C++ extension modules: the live Python wrappers have no introspectable signatures or type information, so the interrogate database is the only source of truth. It's what lets our documentation (example page) provide a high-quality API reference for those modules, including overloads and C++ type info.
From a cursory look, the new event-based hooks lack a way to completely override member enumeration for a given type, supplying the signature from an external source, or a way to choose the emitted directive/domain per object (we generate both Python and C++ versions of the API reference), among possibly other limitations, so the legacy class-based API is currently the only way for us to do this.
My python code has:
from PIL.Image import core as image_core
type PixelAccess = image_core.PixelAccess
autodoc stops with:
AttributeError: module 'PIL._imaging' has no attribute 'PixelAccess'
Normal running of the program and using mypy give no problems.
Adding autodoc_use_legacy_class_based = True to my conf.py stops the problem but I would like to have type info
inside my sphinx output.
I could also protect this type alias with if TYPE_CHECKING but that is not ideal...
When using sphinx.ext.autodoc to document SQLAlchemy ORM models defined in separate files, Sphinx fails to import the second module and raises an AttributeError: type object 'ORM2' has no attribute '__table_args__'.
Note: Sphinx does not report the error under either of the following conditions: when both ORM classes are defined in the same file, or when autodoc_use_legacy_class_based = True is set.
Running Sphinx v9.1.0
loading translations [en]... done
making output directory... done
loading intersphinx inventory 'sqlalchemy' from https://docs.sqlalchemy.org/objects.inv ...
intersphinx inventory has moved: https://docs.sqlalchemy.org/objects.inv -> https://docs.sqlalchemy.org/en/20/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import 'orm2' from module 'autodoc_sqlalchemy'; the following exception was raised:
Traceback (most recent call last):
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sphinx\ext\autodoc\_dynamic\_importer.py", line 221, in _import_module
module = importlib.import_module(modname)
File "C:\Users\vivodi\AppData\Roaming\uv\python\cpython-3.14-windows-x86_64-none\Lib\importlib\__init__.py", line 88, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "<frozen importlib._bootstrap>", line 1398, in _gcd_import
File "<frozen importlib._bootstrap>", line 1371, in _find_and_load
File "<frozen importlib._bootstrap>", line 1342, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 938, in _load_unlocked
File "<frozen importlib._bootstrap_external>", line 762, in exec_module
File "<frozen importlib._bootstrap>", line 491, in _call_with_frames_removed
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\autodoc_sqlalchemy\orm2.py", line 6, in <module>
class ORM2(Base):
__tablename__ = "orm2"
id: Mapped[int] = mapped_column(primary_key=True)
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sqlalchemy\orm\decl_api.py", line 849, in __init_subclass__
_as_declarative(cls._sa_registry, cls, cls.__dict__)
~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sqlalchemy\orm\decl_base.py", line 245, in _as_declarative
return _MapperConfig.setup_mapping(registry, cls, dict_, None, {})
~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sqlalchemy\orm\decl_base.py", line 326, in setup_mapping
return _ClassScanMapperConfig(
registry, cls_, dict_, table, mapper_kw
)
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sqlalchemy\orm\decl_base.py", line 562, in __init__
self._scan_attributes()
~~~~~~~~~~~~~~~~~~~~~^^
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sqlalchemy\orm\decl_base.py", line 866, in _scan_attributes
table_args = cls_as_Decl.__table_args__
^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: type object 'ORM2' has no attribute '__table_args__'. Did you mean: '__tablename__'?
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sphinx\ext\autodoc\_dynamic\_importer.py", line 131, in _import_from_module_and_path
module = _import_module(module_name, try_reload=True)
File "C:\Users\vivodi\Projects\autodoc_sqlalchemy\.venv\Lib\site-packages\sphinx\ext\autodoc\_dynamic\_importer.py", line 233, in _import_module
raise ImportError(exc, traceback.format_exc()) from exc
ImportError: (AttributeError("type object 'ORM2' has no attribute '__table_args__'"), 'Traceback (most recent call last):\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\.venv\\Lib\\site-packages\\sphinx\\ext\\autodoc\\_dynamic\\_importer.py", line 221, in _import_module\n module = importlib.import_module(modname)\n File "C:\\Users\\vivodi\\AppData\\Roaming\\uv\\python\\cpython-3.14-windows-x86_64-none\\Lib\\importlib\\__init__.py", line 88, in import_module\n return _bootstrap._gcd_import(name[level:], package, level)\n ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File "<frozen importlib._bootstrap>", line 1398, in _gcd_import\n File "<frozen importlib._bootstrap>", line 1371, in _find_and_load\n File "<frozen importlib._bootstrap>", line 1342, in _find_and_load_unlocked\n File "<frozen importlib._bootstrap>", line 938, in _load_unlocked\n File "<frozen importlib._bootstrap_external>", line 762, in exec_module\n File "<frozen importlib._bootstrap>", line 491, in _call_with_frames_removed\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\autodoc_sqlalchemy\\orm2.py", line 6, in <module>\n class ORM2(Base):\n __tablename__ = "orm2"\n id: Mapped[int] = mapped_column(primary_key=True)\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\.venv\\Lib\\site-packages\\sqlalchemy\\orm\\decl_api.py", line 849, in __init_subclass__\n _as_declarative(cls._sa_registry, cls, cls.__dict__)\n ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\.venv\\Lib\\site-packages\\sqlalchemy\\orm\\decl_base.py", line 245, in _as_declarative\n return _MapperConfig.setup_mapping(registry, cls, dict_, None, {})\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\.venv\\Lib\\site-packages\\sqlalchemy\\orm\\decl_base.py", line 326, in setup_mapping\n return _ClassScanMapperConfig(\n registry, cls_, dict_, table, mapper_kw\n )\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\.venv\\Lib\\site-packages\\sqlalchemy\\orm\\decl_base.py", line 562, in __init__\n self._scan_attributes()\n ~~~~~~~~~~~~~~~~~~~~~^^\n File "C:\\Users\\vivodi\\Projects\\autodoc_sqlalchemy\\.venv\\Lib\\site-packages\\sqlalchemy\\orm\\decl_base.py", line 866, in _scan_attributes\n table_args = cls_as_Decl.__table_args__\n ^^^^^^^^^^^^^^^^^^^^^^^^^^\nAttributeError: type object \'ORM2\' has no attribute \'__table_args__\'. Did you mean: \'__tablename__\'?\n')
[autodoc.import_object]
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to C:\Users\vivodi\Projects\autodoc_sqlalchemy\docs\_build\html\_static\basic.css
Writing evaluated template result to C:\Users\vivodi\Projects\autodoc_sqlalchemy\docs\_build\html\_static\documentation_options.js
Writing evaluated template result to C:\Users\vivodi\Projects\autodoc_sqlalchemy\docs\_build\html\_static\language_data.js
Writing evaluated template result to C:\Users\vivodi\Projects\autodoc_sqlalchemy\docs\_build\html\_static\alabaster.css
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] index
generating indices... genindex py-modindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in _build\html.
git clone https://github.com/vivodi/autodoc-sqlalchemy-demo.git
cd autodoc-sqlalchemy-demo
uv run sphinx-build -M html docs docs/_build
_extract_signature_from_object() fails (no Python source), leaving signatures = []
numpydoc's mangle_signature hook returns a valid signature via autodoc-process-signature
Sphinx tries signatures[0] = ... on an empty list, causing IndexError
Setting autodoc_use_legacy_class_based = True only partially helps. Warnings drop from 586 to 451, but 224 remain because autosummary imports directly from _dynamic/_loader.py, bypassing the legacy flag.
Activity
[-]Tracking issue for missing features in the new implementation of autodoc[/-][+]Tracking issue for problems in the new implementation of autodoc[/+][-]Tracking issue for problems in the new implementation of autodoc[/-][+]TRACKING: Problems in the new implementation of autodoc[/+]AA-Turner commentedon Dec 1, 2025
lelit commentedon Dec 10, 2025
Hi, not sure if this is the right place to ask help on new implementation, but given that what I'm facing is actually a problem with it... 😉
In a couple of projects, where I'm still using Sphinx v7, I was able to override the default
AttributeDocumenterwith a custom one, that recognizes class attributes initialized with aSQLliterals (more specifically, psycopg2 SQL instances), that it renders as a.. code-block:: postgresql:I tried to follow the new implementation, but I failed to see a way to do something like that (didn't try setting the use legacy classes option yet, but OTOH I'm looking forward...).
Thanks in advance for any hint!
jamadden commentedon Dec 22, 2025
Hi! The issue said to leave a comment here if we had to use
autodoc_use_legacy_class_based = Trueso here I am 😄The regression appears to be that the new implementation assumes everything can be weak-referenced, but that's not always the case. In our case, when using
zope.deprecationorzope.deferredimport,sys.moduleswill containModuleProxyobjects that cannot be weak referenced. This results in aTypeError(full report attached):Setting
autodoc_use_legacy_class_based = Truesolves the issue.I'm attaching an archive of a simple project that demonstrates the issue. You'll need to have
zope.interfaceandzope.deferredimportinstalled. (I runsphinx-build -vv -b html -d docs/_build/html docs docs/_build/htmlfrom the extracted directory to produce the error.)It took me a while to narrow this down to a simple reproducer.
We're documenting one module in
index.rst:(I have
autodoc_default_optionsset with'members': Nonebut I assume setting it directly on the directive works as well)Contents of
module.py:where
_module.pyis:The keys to reproduce are:
Fooneeds to have a base class;zope.deferredimportwhich uses aModuleProxyobject that isn't weak-referencable: It extendszope.proxy.ProxyBase, a C extension, and specifies__slots__);Fooneeds to have an object that is documented and contains a method with type annotations. A plain class doesn't trigger the error, but interface classes do, and I would imagine other classes that play tricks with metatypes could as well.sphinx_err.zip
(This exact error report is from a slightly earlier iteration of the reproducer).
sphinx-err.txt
AA-Turner commentedon Dec 22, 2025
The weakrefs code was introduced to improve support for type comments (#13935, cc @jbms). See
sphinx.ext.autodoc._dynamic._type_comments.Perhaps we should gate this logic behind
autodoc_use_type_comments = True?A
mforbes commentedon Dec 23, 2025
I was using
sphinx.ext.autodoc.loggerin myzopeext.autointerfacemodule. This is breaks interactions with Sphinx 9 sphinx-contrib/zopeext#17. Probably an easy fix, but reporting here for coverage.13 remaining items
dcermak commentedon Mar 10, 2026
Yes, looks very much like the same issue. I have also included more info in #14337 what causes this (looks like autodoc reinjects
__annotations__after pydantic deletes them).use workaround to support sphinx9
use workaround to support sphinx9 (#9)
cjwatson commentedon May 21, 2026
It's not my project, but I found myself having to set
autodoc_use_legacy_class_based = Trueininvocationsto get things working with current Sphinx versions: pyinvoke/invocations#47zyzzyxdonta commentedon Jun 2, 2026
Our project also needs
autodoc_use_legacy_class_based = Truefor Sphinx to run. It's a Django app. Somehow I only ran into this issue in GitLab CI. On my laptop everything built fine without.Repository: https://codebase.helmholtz.cloud/heliport/heliport
Failed CI job: https://codebase.helmholtz.cloud/heliport/heliport/-/jobs/3094512
Sphinx error log:
sphinx-err-nttbit3t.log.txt
Seems to be the same issue that @vincentschut has.
rdb commentedon Jun 2, 2026
Our project also needs the legacy interface since it uses the sphinx-interrogatedb extension which subclasses the regular Documenter classes to source the members, docstrings, signatures etc. from a separate database file, which is generated by our Python binding generation tool, interrogate.
This matters because the documented objects are compiled C++ extension modules: the live Python wrappers have no introspectable signatures or type information, so the interrogate database is the only source of truth. It's what lets our documentation (example page) provide a high-quality API reference for those modules, including overloads and C++ type info.
From a cursory look, the new event-based hooks lack a way to completely override member enumeration for a given type, supplying the signature from an external source, or a way to choose the emitted directive/domain per object (we generate both Python and C++ versions of the API reference), among possibly other limitations, so the legacy class-based API is currently the only way for us to do this.
Add explicit py:method stubs for missing scree plot methods in BaseSi…
Fix inherited method autodoc and cross-reference warnings
Fix inherited method autodoc and cross-reference warnings
Fix inherited method autodoc and cross-reference warnings
docs: use legacy autodoc to fix Sphinx 9 build warnings
build(deps-dev): update qiskit-sphinx-theme requirement from ~=2.0.0 …
lourensm commentedon Aug 21, 2026
My python code has:
from PIL.Image import core as image_core
type PixelAccess = image_core.PixelAccess
autodoc stops with:
Normal running of the program and using mypy give no problems.
Adding
autodoc_use_legacy_class_based = Trueto my conf.py stops the problem but I would like to have type infoinside my sphinx output.
I could also protect this type alias with
if TYPE_CHECKINGbut that is not ideal...vivodi commentedon Aug 22, 2026
Describe the bug
When using
sphinx.ext.autodocto document SQLAlchemy ORM models defined in separate files, Sphinx fails to import the second module and raises anAttributeError: type object 'ORM2' has no attribute '__table_args__'.Note: Sphinx does not report the error under either of the following conditions: when both ORM classes are defined in the same file, or when
autodoc_use_legacy_class_based = Trueis set.How to Reproduce
Project Structure:
autodoc_sqlalchemy/__init__.pyautodoc_sqlalchemy/orm1.pyautodoc_sqlalchemy/orm2.pydocs/index.rstgit clonemethod to reproduce:git clone https://github.com/vivodi/autodoc-sqlalchemy-demo.git cd autodoc-sqlalchemy-demo uv run sphinx-build -M html docs docs/_buildEnvironment Information
Sphinx extensions
Additional context
Setting
autodoc_use_legacy_class_based = Truesolves the issue.I have also created a separate issue for this: #14618
AbhiRKeesara commentedon Sep 25, 2026
Hi,
I'm hitting a regression when building NumPy docs with Sphinx 9.1.0 and numpydoc 1.11.0.
About 357 warnings appear for NumPy ufuncs (C extension types):
The bug is in
sphinx/ext/autodoc/_dynamic/_signatures.pyline 128. The_format_signatures()function assumessignatureshas at least one element:For C extension types like ufuncs:
_extract_signature_from_object()fails (no Python source), leavingsignatures = []mangle_signaturehook returns a valid signature viaautodoc-process-signaturesignatures[0] = ...on an empty list, causing IndexErrorSetting
autodoc_use_legacy_class_based = Trueonly partially helps. Warnings drop from 586 to 451, but 224 remain becauseautosummaryimports directly from_dynamic/_loader.py, bypassing the legacy flag.To reproduce:
python -m spin docsSuggested fix:
Could either the
signatures[0]assumption be fixed, orautosummarybe made to respectautodoc_use_legacy_class_based?Thanks!