Sphinx autodoc不会显示所有类型或循环导入错误

Question

我正在尝试使用狮身人面像autodoc，napoleon和autodoc_typehints自动文档类型，但是我遇到了问题，因为它不适用于我的大多数类型。我正在使用deap软件包执行一些遗传优化算法，这使我有一些非常具体的类型，我猜sphinx无法处理。

我的conf.py文件看起来像这样：

import os
import sys
sys.path.insert(0, os.path.abspath('../python'))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx_autodoc_typehints'
]


set_type_checking_flag = False
always_document_param_types = False

我有一个Algo.rst文件，带有：

.. automodule:: python.algo.algo
     :members: crossover_worker,
               test

而且我的python.algo.algo模块看起来像这样（我添加了一个虚拟测试函数来显示它在没有指定特殊类型的情况下都可以工作）：

# Type hinting imports
from config.config import Config
from typing import List, Set, Dict, NamedTuple, Union, Tuple
from types import ModuleType
from numpy import ndarray
from numpy import float64
from multiprocessing.pool import MapResult
from deap.tools.support import Logbook, ParetoFront
from deap.base import Toolbox
from pandas.core.frame import DataFrame
from deap import creator

...

def crossover_worker(sindices: List[creator.Individual, creator.Individual]) -> Tuple[creator.Individual, creator.Individual]:
    """
    Uniform crossover using fixed threshold

    Args:
        sindices: list of two individuals on which we want to perform crossover

    Returns:
        tuple of the two individuals with crossover applied
    """
    ind1, ind2 = sindices
    size = len(ind1)
    for i in range(size):
        if random.random() < 0.4:
            ind1[i], ind2[i] = ind2[i], ind1[i]
    return ind1, ind2


def test(a: DataFrame, b: List[int]) -> float:
    """
    test funcition

    Args:
        a: something
        b: something

    Returns:
        something
    """
    return b

当conf.py中的设置如上时我没有错误，test函数的类型正确，但是crossover_worker函数的类型丢失：

但是，当我将set_type_checking_flag= True设置为强制使用所有类型时，出现循环导入错误：

reading sources... [100%] index
WARNING: autodoc: failed to import module 'algo' from module 'python.algo'; the following exception was raised:
cannot import name 'ArrayLike' from partially initialized module 'pandas._typing' (most likely due to a circular import) (/usr/local/lib/python3.8/site-packages/pandas/_typing.py)
looking for now-outdated files... none found

而且我从不导入ArrayLike，所以我无法从其来源或解决方法中获取它？还是如何强制也导入出现在我的代码中各处的creator.Individual类型？

我的狮身人面像版本：

sphinx==3.0.1
sphinx-autodoc-typehints==1.10.3

Answer 1

经过一些搜索之后，我的方法存在一些缺陷：

• 首先，“列表是包含一种类型值的同构结构。因此，List仅采用单一类型，并且该列表中的每个元素都必须具有该类型。 （source）。因此，我无法执行类似List[creator.Individual, creator.Individual]的操作，但应将其转换为List[creator.Individual]，或者如果列表中有多个类型，则应使用并运算符，例如List[Union[int,float]]
• 第二，狮身人面像无法将类型creator.Individual识别为有效类型。相反，我应该使用TypeVar这样定义它：

from typing import TypeVar, List
CreatorIndividual = TypeVar("CreatorIndividual", bound=List[int])

因此，通过将我的crossover_worker函数转换为此函数，它全部起作用：

def crossover_worker(sindices: List[CreatorIndividual]) -> Tuple[CreatorIndividual, CreatorIndividual]:

注意： ]，Tuple[int,int,int]和Tuple[str,int]都是不同的类型，通过产品中的类型数量和它们出现的顺序来区分。“（[Tuple[int,str]）