readthedocs / readthedocs/sphinx-autoapi

Wrong namespace resolution for base clases when using star import

Open
#404 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

The issue 🐞

Consider the following project:

.
β”œβ”€β”€ package/
β”‚   β”œβ”€β”€__init__.py
β”‚   β”œβ”€β”€ module_A.py
β”‚   └── module_B.py
β”œβ”€β”€ conf.py
└── index.rst

The content of each file:

module_A.py module_B.py index.rst conf.py
from enum import IntEnum

from .module_B import *

__all__ = ["FooA"]

class FooA(IntEnum):
    ITEM_0 = 0
    ITEM_1 = 1
    ITEM_2 = 2
from enum import IntEnum

__all__ = ["FooB"]

class FooB(IntEnum):
    ITEM_0 = 0
    ITEM_1 = 1
    ITEM_2 = 2

Package docs
============
   
.. toctree::

   autoapi/index

Contents:

.. toctree::
   :maxdepth: 2
templates_path = ["_templates"]
source_suffix = ".rst"
master_doc = "index"
project = "package"
copyright = "2015, readthedocs"
author = "readthedocs"
version = "0.1"
release = "0.1"
language = "en"
exclude_patterns = ["_build"]
pygments_style = "sphinx"
todo_include_todos = False
html_theme = "alabaster"
htmlhelp_basename = "Package"
extensions = ["autoapi.extension"]
autoapi_dirs = ["package"]
autoapi_file_pattern = "*.py"

The result is:

Class A Class B
Investigations πŸ”Ž

It looks like the import matters:

This fails This works This works too
from enum import IntEnum  

from .module_B import *          
from .module_B import *   

from enum import IntEnum  
from enum import IntEnum  

from .module_B import FooB

I am a bit surprised that this behavior applies even if __all__ is used in both modules.

Origin of the problem
It looks like the function resolve_qualname is the one causing the issue.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up β€” it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the package example with module_A.py, module_B.py, conf.py, and index.rst, comparing the failing star import with the working explicit import. Start with resolve_qualname in autoapi/mappers/python/astroid_utils.py, which the report identifies as the likely source. Done means generated documentation resolves the base class correctly when using the star import and preserves the working cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.