Skip to content

TRACKING: Problems in the new implementation of autodoc #14089

Open

Description

@AA-Turner

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.

A

Activity

  1. pinned this issue on Nov 25, 2025
  2. 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
  3. 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
  4. added this to the 9.0.0 milestone on Nov 25, 2025
  5. modified the milestones: 9.0.0, 9.0.x, 9.x on Dec 1, 2025
  6. lelit commented on Dec 10, 2025

    @lelit
    Contributor

    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:

        from sphinx.ext import autodoc
    
        class AttributeDocumenter(autodoc.AttributeDocumenter):
            """Customized AttributeDocumenter that knows about ``SQL`` literals."""
    
            def add_directive_header(self, sig):
                """Omit the raw value in case of SQL instances."""
                if not isinstance(self.object, Psycopg2SQL.Composable):
                    autodoc.AttributeDocumenter.add_directive_header(self, sig)
                else:
                    autodoc.ClassLevelDocumenter.add_directive_header(self, sig)
    
            def add_content(self, more_content):
                """Prettify SQL statements."""
                autodoc.AttributeDocumenter.add_content(self, more_content)
                if isinstance(self.object, Psycopg2SQL.Composable):
                    sql = self.object.as_string(None)
                    self.add_line('', '')
                    self.add_line('.. code-block:: postgresql', '')
                    self.add_line('', '')
                    for line in sql.splitlines():
                        self.add_line('   ' + line, '')
    
        def setup(app):
            """Setup the Sphinx environment."""
            from docutils.parsers.rst import directives
    
            app.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...).

    Thanks in advance for any hint!

  7. jamadden commented on Dec 22, 2025

    @jamadden

    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:

    from zope.interface import Interface
    from _module import Base
    
    class IWithTypes(Interface):
        "This class must be documented."
    
        def method(thing:str):
            # This method doesn't have to be documented.
            pass
    
    class Foo(Base):
        "Must be documented"
    
        # This doesn't have to be documented.
        CLEANUP_IFACE = IWithTypes

    where _module.py is:

    class Base:
        # Doesn't have to be documented.
        pass
    
    from zope import deferredimport
    
    deferredimport.initialize()
    
    deferredimport.deprecatedFrom(
        "Import from elsewhere",
        "module.to.import",
        "name_in_module",
    )

    The keys to reproduce are:

    1. Foo needs to have a base class;
    2. 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__);
    3. 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.

    sphinx_err.zip

    (This exact error report is from a slightly earlier iteration of the reproducer).

    sphinx-err.txt

  8. AA-Turner commented on Dec 22, 2025

    @AA-Turner
    MemberAuthor

    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

  9. mforbes commented on Dec 23, 2025

    @mforbes

    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.

  10. 13 remaining items

  11. dcermak commented on Mar 10, 2026

    @dcermak

    @dcermak I think this is the same bug as in my comment above.

    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).

  12. cjwatson commented on May 21, 2026

    @cjwatson
    Contributor

    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

  13. zyzzyxdonta commented on Jun 2, 2026

    @zyzzyxdonta

    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.

    Repository: https://codebase.helmholtz.cloud/heliport/heliport

    Failed CI job: https://codebase.helmholtz.cloud/heliport/heliport/-/jobs/3094512

    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
    

    Sphinx error log:

    sphinx-err-nttbit3t.log.txt

    Seems to be the same issue that @vincentschut has.

  14. rdb commented on Jun 2, 2026

    @rdb
    Contributor

    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.

  15. lourensm commented on Aug 21, 2026

    @lourensm

    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...

  16. vivodi commented on Aug 22, 2026

    @vivodi

    Describe the bug

    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.
    

    How to Reproduce

    Project Structure:

    autodoc_sqlalchemy/
    ├── __init__.py
    ├── orm1.py
    └── orm2.py
    

    autodoc_sqlalchemy/__init__.py

    from sqlalchemy.orm import DeclarativeBase
    
    class Base(DeclarativeBase):
        pass

    autodoc_sqlalchemy/orm1.py

    from sqlalchemy.orm import Mapped, mapped_column
    from autodoc_sqlalchemy import Base
    
    class ORM1(Base):
        __tablename__ = "orm1"
        id: Mapped[int] = mapped_column(primary_key=True)

    autodoc_sqlalchemy/orm2.py

    from sqlalchemy.orm import Mapped, mapped_column
    from autodoc_sqlalchemy.orm1 import Base
    
    class ORM2(Base):
        __tablename__ = "orm2"
        id: Mapped[int] = mapped_column(primary_key=True)

    docs/index.rst

    .. automodule:: autodoc_sqlalchemy.orm1
       :members:
       :private-members:
       :show-inheritance:
       :undoc-members:
    
    .. automodule:: autodoc_sqlalchemy.orm2
       :members:
       :private-members:
       :show-inheritance:
       :undoc-members:

    git clone method to reproduce:

    git clone https://github.com/vivodi/autodoc-sqlalchemy-demo.git
    cd autodoc-sqlalchemy-demo
    uv run sphinx-build -M html docs docs/_build

    Environment Information

    Python version: 3.14
    sqlalchemy version: 2.0.52
    Sphinx version: 9.1.0
    

    Sphinx extensions

    ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]

    Additional context

    Setting autodoc_use_legacy_class_based = True solves the issue.

    I have also created a separate issue for this: #14618

  17. AbhiRKeesara commented on Sep 25, 2026

    @AbhiRKeesara

    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):

    WARNING: error while formatting signature for numpy.add: list assignment index out of range [autodoc]
    

    The bug is in sphinx/ext/autodoc/_dynamic/_signatures.py line 128. The _format_signatures() function assumes signatures has at least one element:

    signatures[0] = (args, retann if isinstance(retann, str) else '')

    For C extension types like ufuncs:

    1. _extract_signature_from_object() fails (no Python source), leaving signatures = []
    2. numpydoc's mangle_signature hook returns a valid signature via autodoc-process-signature
    3. 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.

    To reproduce:

    1. Clone NumPy
    2. Install sphinx==9.1.0, numpydoc==1.11.0
    3. Run python -m spin docs

    Suggested fix:

    if signatures:
        signatures[0] = (args, retann if isinstance(retann, str) else '')
    else:
        signatures.append((args, retann if isinstance(retann, str) else ''))

    Could either the signatures[0] assumption be fixed, or autosummary be made to respect autodoc_use_legacy_class_based?

    Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions