Python导入错误解决：Pylint合规性与运行时执行的冲突

项目结构 #

├── docs
├── setup.py
├── python_package_
│   ├── __init__.py
│   ├── __main__.py
│   ├── __version__.py
│   ├── arg_parser.py
│   ├── classes
│   │   ├── __init__.py
│   │   └── file_generator.py
│   ├── settings.py
│   ├── python_package.py
│   └── utils
│       ├── __init__.py
│       └── cli.py
├── README.md    
├── requirements.txt
└── tests

原__main__.py代码 #

# -*- coding: utf-8 -*-
"""Main module for the program."""

from arg_parser import parse_arguments
from utils import cli
from python_package import package
import settings


def main():
    """Main"""
    args = parse_arguments()
    cli.print_argument_summary(args)
    package(args)

if __name__ == "__main__":
    main()

问题现象 #

1. 直接运行正常：执行python3 python_package/__main__.py ...时程序能正常运行
2. Pylint检查报错：

************* Module python_package.__main__
__main__.py:4:0: E0401: Unable to import 'arg_parser' (import-error)
__main__.py:5:0: E0401: Unable to import 'utils' (import-error)
__main__.py:7:0: E0401: Unable to import 'settings' (import-error)

------------------------------------------------------------------
Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)

3. 改用相对导入后：
   修改后的导入代码：

from .arg_parser import parse_arguments
from .utils import cli
from .python_package import python_package
from . import settings

• Pylint评分达到10.00/10，但运行时报错：

ImportError: attempted relative import with no known parent package

疑问 #

请问我哪里操作有误？解决该问题的最佳方式是什么？

问题根源 #

两种导入方式的冲突核心是Python运行脚本的上下文不同：

• 直接运行python3 python_package/__main__.py时，脚本被当作顶层脚本，python_package_/目录被自动加入sys.path，所以同目录模块能直接导入；但Pylint是从项目根目录分析，把它当作python_package_.__main__模块，自然找不到arg_parser这类无包前缀的模块，因此报错。
• 用相对导入时，Pylint能识别它是包内模块，但直接运行脚本时，Python不把python_package_当作父包，相对导入失去上下文，所以运行报错。

最佳解决方法 #

方法1：保留直接导入+配置Pylint

保持原导入语句不变，给Pylint指定项目根目录，让它能正确识别包结构：
在项目根目录执行Pylint时，添加参数：

pylint --init-hook='import sys; sys.path.insert(0, ".")' python_package_

或者创建.pylintrc配置文件，在[MASTER]段添加：

init-hook='import sys; sys.path.insert(0, ".")'

之后直接运行pylint python_package_即可正常检查。

方法2：用包模式运行脚本（推荐）

保留相对导入的代码，然后在项目根目录用包运行方式启动程序：

python3 -m python_package_ ...

这种方式下Python会把python_package_当作正式包加载，相对导入能正常工作，同时Pylint无需额外配置就能识别模块结构，完全符合Python包规范。

方法3：改用基于包的绝对导入

把导入语句改成从包名开始的绝对路径：

from python_package_.arg_parser import parse_arguments
from python_package_.utils import cli
from python_package_.python_package import package
from python_package_ import settings

这种方式不管是直接运行脚本（需确保项目根目录在sys.path）还是Pylint检查都能生效，但更建议结合方法2的-m运行方式，避免手动处理sys.path的麻烦。

优先推荐 #

最规范且无额外配置的方案是方法2：用相对导入+python3 -m python_package_运行程序，既解决了运行问题，也让Pylint能正常评分。

内容的提问来源于stack exchange，提问作者Will