Sphinx 显示带有类型提示的本地 python 路径

Question

我使用 html 格式的 sphinx-quickstart 使用 Sphinx 自动生成文档。结果似乎错误地解析了 json.

的类型提示

假设我有以下带有类型提示的 Python 函数：

import json
def some_function(param1: str, param2: json) -> list:
    pass

此函数生成以下 html 输出：

 some_function(param1: str, param2: <module 'json' from 'path_to_conda/miniconda3/envs/ienw/lib/json/__init__.py'>) → list

我们现在看到 param2 的类型提示非常奇怪，我不希望文档中有我的本地 Python 路径。

关于 conf.py 的一些细节（它主要遵循 sphinx-quickstart 的默认配置）：

extensions = [
    "rinoh.frontend.sphinx",
    "sphinx.ext.autosummary",
]
html_theme = "alabaster"

有谁知道为什么会发生这种情况以及我们如何从文档中隐藏我的本地路径？

Answer 1

我会这样说

import json
def some_function(param1: str, param2: json) -> list:
    pass

确实违反了 PEP 484

Type hints may be built-in classes (including those defined in standard library or third-party extension modules), abstract base classes, types available in the types module, and user-defined classes (including those defined in the standard library or third-party modules).

as json after import json is not class 可以证明如下：

import inspect
import json
print(inspect.isclass(json))  # False

您可能会选择使用 PEP 3107 代替，因为您可能会使用 Annotation 来传达用户期望的信息，简单示例是：

def speed(distance: "meters", duration: "seconds") -> "m/s":
    return distance/duration

Answer 2

如果你想提示一个参数应该是一个 JSON 字符串，那么不要使用 json 模块 作为提示，只是因为它被命名为“json”。您不会将 json 模块 作为参数传递给函数，因此无论如何类型检查都是无用的。

JSON 是具有特定格式的字符串。因此，类型提示必须是 str，但您可以使用 type alias or NewType:

来表达所需的逻辑

from typing import NewType

JSON = str
# or:
JSON = NewType('JSON', str)

def some_function(param1: str, param2: JSON) -> list:
    ...

Sphinx 显示带有类型提示的本地 python 路径

Sphinx shows local python path with type hinting

python

python-sphinx

python-typing