PyCharm跨子包导入时docstring不显示的配置问题咨询

问题复现结构 #

为便于排查，先给出最小可复现的项目结构：

C:.
├───.idea
│   └─── PyCharm相关配置文件
└───src
    │   main.py
    │
    ├───folder
    │   │   script.py
    │   │   __init__.py
    │
    └───folder2
        │   script2.py
        │   __init__.py

使用场景为将src作为PyCharm项目根目录打开，入口文件main.py代码如下，运行无异常，自动补全、docstring悬停提示功能均正常：

from folder.script import my_function_script

if __name__ == '__main__':
    my_function_script()

正常提示效果：鼠标悬停在导入的函数名上可正常展示对应docstring，代码编辑时自动补全能正常触发。

子包folder下的script.py代码如下：

from folder2.script2 import my_function_script_2

def my_function_script() -> None:
    """
    This is a docstring
    :return: None
    """
    my_function_script_2()

故障表现 #

PyCharm误将导入语句中的folder2识别为folder包下的子模块，导致该文件内自动补全、docstring提示、类型检查功能全部失效。由于项目统一从main.py启动，导入根路径固定为src目录，无法将导入语句改为相对导入写法——修改后从main.py启动时Python会直接抛出模块找不到的错误。

配置步骤 #

按以下操作标记源码根目录即可解决问题：

• 按快捷键Ctrl+Alt+Shift+S直接打开项目结构配置页，也可以通过菜单栏File > Project Structure进入
• 在左侧配置分类中选择Sources，在右侧目录树中选中src目录，点击上方工具栏的Sources标记按钮（蓝色文件夹图标），将src设置为项目源码根目录
• 检查folder、folder2目录，确保二者没有被误标记为源码根目录，仅保留src的Sources标记即可
• 点击Apply保存配置，等待PyCharm完成项目重索引

若配置完成后提示仍未恢复，选择菜单栏File > Invalidate Caches...，勾选清除文件系统缓存和索引，重启IDE等待重建索引即可完全恢复正常。

内容的提问来源于stack exchange，提问作者FluidMechanics Potential Flows