Python 3中的相对导入

技术背景

在Python编程中，导入模块是常见的操作。相对导入允许在包内部的模块之间进行导入，这在处理复杂的项目结构时非常有用。然而，Python的模块系统对相对导入有一定的要求，若不按其规则运行代码，即使代码本身正确，相对导入也可能失败，这往往是由于运行时上下文问题导致的。

实现步骤

明确概念

• 模块：只有当一个文件被另一个文件导入时，它才被视为Python模块。例如，运行python mod.py时，mod.py不是模块，因为它未被导入。
• 包：包是包含Python模块的文件夹。从Python 3.3开始，__init__.py文件不是必需的，只要有文件被导入，该文件夹就可视为包。

相对导入规则

只能在属于同一包的模块内进行相对导入。

解决相对导入问题的常见方法

方法一：使用-m命令行选项

当模块需要使用相对导入且要作为脚本运行时，可使用-m选项。该选项会在sys.path中搜索指定模块，并将其内容作为__main__模块执行。例如：

python3 -i -m package.standalone

方法二：手动设置__package__

在某些情况下，可手动设置__package__来使相对导入工作。但这通常需要导入模块层次结构中至少N个前面的包，其中N是相对于脚本目录的父目录数量，这些父目录将用于搜索要导入的模块。示例代码如下：

import sys
from pathlib import Path

if __name__ == '__main__' and __package__ is None:
    file = Path(__file__).resolve()
    parent, top = file.parent, file.parents[3]

    sys.path.append(str(top))
    try:
        sys.path.remove(str(parent))
    except ValueError:
        pass

    import package.subpackage.subsubpackage
    __package__ = 'package.subpackage.subsubpackage'

from ... import module

方法三：使用绝对导入和setuptools

步骤如下：

1. 将显式相对导入替换为等效的绝对导入。
2. 安装包，使其可被导入。例如，在setup.py文件中使用setuptools进行包的安装：

from setuptools import setup, find_packages
setup(
    name='your_package_name',
    packages=find_packages(),
)

然后在终端中运行：

python3 setup.py install --user

方法四：使用绝对导入和样板代码

在脚本中添加一些样板代码，使绝对导入能够工作。例如：

import sys
from pathlib import Path
file = Path(__file__).resolve()
parent, root = file.parent, file.parents[1]
sys.path.append(str(root))
try:
    sys.path.remove(str(parent))
except ValueError:
    pass

from package import module

核心代码

示例项目结构

.
├── main.py
├── mypackage
│   ├── __init__.py
│   ├── mymodule.py
│   └── myothermodule.py

mymodule.py代码

#!/usr/bin/env python3

# Exported function
def as_int(a):
    return int(a)

# Test function for module
def _test():
    assert as_int('1') == 1

if __name__ == '__main__':
    _test()

myothermodule.py代码

#!/usr/bin/env python3

if __name__ == '__main__':
    from mymodule import as_int
else:
    from .mymodule import as_int

# Exported function
def add(a, b):
    return as_int(a) + as_int(b)

# Test function for module
def _test():
    assert add('1', '1') == 2

if __name__ == '__main__':
    _test()

main.py代码

#!/usr/bin/env python3

from mypackage.myothermodule import add

def main():
    print(add('1', '1'))

if __name__ == '__main__':
    main()

最佳实践

• 遵循PEP 8建议：PEP 8推荐使用绝对导入，因为它们通常更易读且表现更好。但在处理复杂的包布局时，显式相对导入也是可接受的替代方案。
• 使用虚拟环境：在使用setuptools安装包时，建议使用虚拟环境来隔离包的安装，避免不同项目之间的包冲突。
• 避免复杂的相对导入：如果项目结构复杂，尽量减少使用深层级的相对导入，可考虑使用绝对导入或重构项目结构。

常见问题

错误：ImportError: attempted relative import with no known parent package

这通常是因为模块没有在正确的包上下文中运行。解决方法可以是使用-m选项运行模块，或者手动设置__package__。

错误：SystemError: Parent module '' not loaded, cannot perform relative import

当__name__为'__main__'时，__name__.rpartition('.')[0]返回空字符串，导致父模块未加载。解决方法是确保父模块在进行相对导入之前已被显式绝对导入。

PyCharm解析错误

PyCharm可能会不准确地报告无法找到模块，添加.符号虽可消除解析错误，但可能导致ImportError。此时应忽略PyCharm的解析器，代码可能仍能正常运行。