兄弟包导入

Question

我尝试阅读有关兄弟导入的问题，甚至 包文档，但我还没有找到答案。

结构如下：

├── LICENSE.md
├── README.md
├── api
│   ├── __init__.py
│   ├── api.py
│   └── api_key.py
├── examples
│   ├── __init__.py
│   ├── example_one.py
│   └── example_two.py
└── tests
│   ├── __init__.py
│   └── test_one.py

examples 和 tests 目录下的脚本如何从 api 模块并从命令行运行？

另外，我想避免对每个文件进行丑陋的 sys.path.insert hack。一定 这可以用 Python 完成，对吗？

Answer 1

厌倦了 sys.path 黑客攻击？

有很多可用的 sys.path.append -hacks，但我找到了解决当前问题的替代方法。

摘要

• 将代码打包到一个文件夹中（例如 packaged_stuff）
• 创建 pyproject.toml 文件来描述您的包（请参阅下面的最小 pyproject.toml）
• Pip使用 pip install -e 以可编辑状态安装软件包
• 使用 from packaged_stuff.modulename import function_name

---

设置

起点是您的文件结构已提供，包装在名为 myproject 的文件夹中。

.
└── myproject
    ├── api
    │   ├── api_key.py
    │   ├── api.py
    │   └── __init__.py
    ├── examples
    │   ├── example_one.py
    │   ├── example_two.py
    │   └── __init__.py
    ├── LICENCE.md
    ├── README.md
    └── tests
        ├── __init__.py
        └── test_one.py

我将 . 称为根文件夹，在我的示例中，它位于 C:\tmp\test_imports\。

api.py

作为测试用例，让我们使用以下 ./api/api.py

def function_from_api():
    return 'I am the return value from api.api!'

test_one.py

from api.api import function_from_api

def test_function():
    print(function_from_api())

if __name__ == '__main__':
    test_function()

尝试运行 test_one：

PS C:\tmp\test_imports> python .\myproject\tests\test_one.py
Traceback (most recent call last):
  File ".\myproject\tests\test_one.py", line 1, in <module>
    from api.api import function_from_api
ModuleNotFoundError: No module named 'api'

同时尝试相对导入也不起作用：

使用 from ..api.api import function_from_api将导致

PS C:\tmp\test_imports> python .\myproject\tests\test_one.py
Traceback (most recent call last):
  File ".\tests\test_one.py", line 1, in <module>
    from ..api.api import function_from_api
ValueError: attempted relative import beyond top-level package

---

步骤

1) 在根级别目录中创​​建一个 pyproject.toml 文件

（以前人们使用 setup.py 文件）

最小 pyproject.toml 的内容将是*

[project]
name = "myproject"
version = "0.1.0"
description = "My small project"

[build-system]
build-backend = "flit_core.buildapi"
requires = ["flit_core >=3.2,<4"]

---

2) 使用虚拟环境

如果您熟悉虚拟环境，请激活一个虚拟环境，然后跳到下一步。使用虚拟环境并不是绝对必需的，但它们会从长远来看，确实可以帮助您（当您有超过 1 个项目正在进行时......）。最基本的步骤是（在根文件夹中运行）

• 创建虚拟环境
  • python -m venv venv
• 激活虚拟环境
  • 源 ./venv/bin/activate（Linux、macOS）或 ./venv/Scripts/activate (Win)

要了解更多信息，只需 Google 出“python virtual env 教程”或类似内容。除了创建、激活和停用之外，您可能不需要任何其他命令。

创建并激活虚拟环境后，您的控制台应在括号中给出虚拟环境的名称

PS C:\tmp\test_imports> python -m venv venv
PS C:\tmp\test_imports> .\venv\Scripts\activate
(venv) PS C:\tmp\test_imports>

，您的文件夹树应如下所示**

.
├── myproject
│   ├── api
│   │   ├── api_key.py
│   │   ├── api.py
│   │   └── __init__.py
│   ├── examples
│   │   ├── example_one.py
│   │   ├── example_two.py
│   │   └── __init__.py
│   ├── LICENCE.md
│   ├── README.md
│   └── tests
│       ├── __init__.py
│       └── test_one.py
├── pyproject.toml
└── venv
    ├── Include
    ├── Lib
    ├── pyvenv.cfg
    └── Scripts [87 entries exceeds filelimit, not opening dir]

---

3) pip install your project in editable state

安装您的顶级包 myproject使用pip。诀窍是在安装时使用 -e 标志。这样它就会以可编辑状态安装，并且对 .py 文件所做的所有编辑都将自动包含在已安装的包中。 使用 pyproject.toml 和 -e 标志需要 pip >= 21.3

在根目录中，运行

pip install -e . （注意点，它代表“当前目录” ")

您还可以看到它是使用 pip freeze 安装的

Obtaining file:///home/user/projects/myproject
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Preparing editable metadata (pyproject.toml) ... done
Building wheels for collected packages: myproj
  Building editable for myproj (pyproject.toml) ... done
  Created wheel for myproj: filename=myproj-0.1.0-py2.py3-none-any.whl size=903 sha256=f19858b080d4e770c2a172b9a73afcad5f33f4c43c86e8eb9bdacbe50a627064
  Stored in directory: /tmp/pip-ephem-wheel-cache-qohzx1u0/wheels/55/5f/e4/507fdeb40cdef333e3e0a8c50c740a430b8ce84cbe17ae5875
Successfully built myproject
Installing collected packages: myproject
Successfully installed myproject-0.1.0
(venv) PS C:\tmp\test_imports> pip freeze
myproject==0.1.0

---

4) 将 myproject. 添加到您的导入中

请注意，您必须添加 myproject.代码>仅进入导入否则无法工作。无需 pyproject.toml & 即可导入pip install 仍然可以正常工作。请参阅下面的示例。

---

测试解决方案

现在，让我们使用上面定义的 api.py 和下面定义的 test_one.py 来测试该解决方案。

test_one.py

from myproject.api.api import function_from_api

def test_function():
    print(function_from_api())

if __name__ == '__main__':
    test_function()

在这里使用 flit 作为构建后端运行测试

(venv) PS C:\tmp\test_imports> python .\myproject\tests\test_one.py
I am the return value from api.api!

---

。还存在其他替代方案。

** 实际上，您可以将虚拟环境放置在硬盘上的任何位置。

Answer 2

自从我写下答案七年后

，修改 sys.path 仍然是一个快速而肮脏的技巧，对于私有脚本效果很好，但已经有了一些改进

• 安装包（无论是否在virtualenv中）都会给你你想要的，尽管我建议使用pip来完成它而不是直接使用setuptools（并且使用setup.cfg 来存储元数据）
• 使用 -m 标志 并且作为包运行也可以（但如果您想将工作目录转换为可安装包，则会有点尴尬）。
• 具体来说，对于测试， pytest 能够在这种情况下找到 api 包并处理 sys. path hacks for you

所以这实际上取决于你想做什么。不过，就您而言，由于您的目标似乎是在某个时候制作一个合适的软件包，因此通过 pip -e 安装可能是您最好的选择，即使它还不完美。

旧答案

正如其他地方已经指出的，可怕的事实是，您必须进行丑陋的黑客攻击才能允许从 __main__ 模块从兄弟模块或父包导入。 PEP 366 中详细介绍了该问题。 PEP 3122 试图以更合理的方式处理导入，但 Guido 拒绝了一个帐户

唯一的用例似乎是运行发生的脚本
位于模块的目录中，我一直将其视为
反模式。

（此处）

不过，我在定期使用

# Ugly hack to allow absolute import from the root folder
# whatever its name is. Please forgive the heresy.
if __name__ == "__main__" and __package__ is None:
    from sys import path
    from os.path import dirname as dir

    path.append(dir(path[0]))
    __package__ = "examples"

import api

这里 path[0] 是您正在运行的脚本的父文件夹，dir(path[0]) 是您的顶级文件夹。

不过，我仍然无法使用相对导入，但它确实允许从顶层（在您的示例 api 的父文件夹中）进行绝对导入。

Answer 3

这是我在 tests 文件夹中的 Python 文件顶部插入的另一个替代方案：

# Path hack.
import sys, os
sys.path.insert(0, os.path.abspath('..'))

Answer 4

您不需要也不应该破解 sys.path 除非有必要，但在本例中则不然。使用：

import api.api_key # in tests, examples

从项目目录运行：python -mtests.test_one。

您可能应该将 tests （如果它们是 api 的单元测试）移到 api 内并运行 python -m api.test 来运行所有测试（假设有是 __main__.py) 或 python -m api.test.test_one 来运行 test_one 。

您还可以从 examples （它不是 Python 包）中删除 __init__.py 并在安装了 api 的 virtualenv 中运行示例，例如如果您有正确的 setup.py，virtualenv 中的 pip install -e . 将安装就地 api 包。

Answer 5

对于 2023 年的读者：如果您对 pip install -e 没有信心：

TL;DR：脚本（通常是入口点）只能导入任何相同或低于其水平。

考虑这个层次结构，正如 Python 3 中的相对导入的答案所建议的那样：

MyProject
├── src
│   ├── bot
│   │   ├── __init__.py
│   │   ├── main.py
│   │   └── sib1.py
│   └── mod
│       ├── __init__.py
│       └── module1.py
└── main.py

从起点运行我们的程序 python main.py，我们在main.py中使用绝对导入（无前导点）：

from src.bot import main


if __name__ == '__main__':
    main.magic_tricks()

简单的命令 bot/main.py，它利用显式相对导入来显示我们正在导入的内容，如下所示：

from .sib1 import my_drink                # Both are explicit-relative-imports.
from ..mod.module1 import relative_magic

def magic_tricks():
    # Using sub-magic
    relative_magic(in=["newbie", "pain"], advice="cheer_up")
    
    my_drink()
    # Do your work
    ...

原因如下：

• 我们不想当我们想要运行我们的 Python 程序时，真诚地对“好吧，所以这是一个模块”感到害怕。
  • 因此我们使用绝对导入作为入口点main.py，这样我们就可以通过python main.py来运行我们的程序.
  • 在幕后，Python 将使用 sys.path 为我们解析包，但这也意味着我们想要导入的包可能会被任何其他包所取代由于 sys.path 中路径的顺序，名称相同，例如尝试 import test。
• 为了避免这些冲突，我们使用显式相对导入。
  • from ..mod 语法非常清楚地表明“我们正在导入我们自己的本地包”。
  • 但缺点是，当你想将模块作为脚本运行时，你需要再次考虑“好吧，所以这是一个模块”。
• 最后，from ..mod部分意味着它将上升一级到MyProject/src。

结论

1. 将您的 main.py 脚本放在所有包 MyProject/src 的根目录旁边，并在 python main 中使用绝对导入.py 导入任何内容。没有人会创建名为 src 的包。
2. 这些显式的相对导入将会起作用。
3. 要运行模块，请使用 python -m ... 。

附录：有关将 src/ 下的任何文件作为脚本运行的更多信息？

那么你应该使用语法 python -m 并看看我的另一篇文章： ModuleNotFoundError: No module named 'sib1'

Answer 6

我还没有对 Pythonology 的理解，无法了解在不相关的项目之间共享代码而无需兄弟/相对导入 hack 的预期方式。直到那一天，这就是我的解决方案。对于从 ..\api 导入内容的 examples 或 tests ，它看起来像：

import sys.path
import os.path
# Import from sibling directory ..\api
sys.path.append(os.path.dirname(os.path.abspath(__file__)) + "/..")
import api.api
import api.api_key

Answer 7

对于兄弟包导入，您可以使用 [sys.path][2] 模块的 insert 或 append 方法：

if __name__ == '__main__' and if __package__ is None:
    import sys
    from os import path
    sys.path.append( path.dirname( path.dirname( path.abspath(__file__) ) ) )
    import api

这将如果您按如下方式启动脚本，则可以工作：

python examples/example_one.py
python tests/test_one.py

另一方面，您也可以使用相对导入：

if __name__ == '__main__' and if __package__ is not None:
    import ..api.api

在这种情况下，您必须使用 '-m' 参数（请注意，在这种情况下，您不能给出 '.py' 扩展名）：

python -m packageName.examples.example_one
python -m packageName.tests.test_one

当然，您可以混合使用两者方法，以便您的脚本无论如何调用都可以工作：

if __name__ == '__main__':
    if __package__ is None:
        import sys
        from os import path
        sys.path.append( path.dirname( path.dirname( path.abspath(__file__) ) ) )
        import api
    else:
        import ..api.api

Answer 8

你需要看看相关代码中的导入语句是如何编写的。如果examples/example_one.py使用以下导入语句：

import api.api

...那么它期望项目的根目录位于系统路径中。

在没有任何黑客攻击的情况下支持这一点的最简单方法（如您所说）是从顶级目录运行示例，如下所示：

PYTHONPATH=$PYTHONPATH:. python examples/example_one.py 

Answer 9

以防万一有人在 Eclipse 上使用 Pydev 到这里：您可以使用 Project->Properties 并设置 将同级的父路径（以及调用模块的父路径）添加为外部库文件夹左侧菜单下的外部库Pydev-PYTHONPATH。然后你可以从你的同级导入，例如fromsibling import some_class。

Answer 10

我想对 np8 提供的 解决方案发表评论，但我没有足够的声誉所以我只想提一下，您可以完全按照他们的建议创建一个 setup.py 文件，然后从项目根目录执行 pipenv install --dev -e .将其变成可编辑的依赖项。然后你的绝对导入将起作用，例如 from api.api import foo 并且你不必搞乱系统范围的安装。

文档

Answer 11

如果您使用 pytest，则 pytest 文档 描述了如何从单独的测试包引用源包的方法。

建议的项目目录结构是：

setup.py
src/
    mypkg/
        __init__.py
        app.py
        view.py
tests/
    __init__.py
    foo/
        __init__.py
        test_view.py
    bar/
        __init__.py
        test_view.py

setup.py 文件的内容：

from setuptools import setup, find_packages

setup(name="PACKAGENAME", packages=find_packages())

以可编辑模式安装软件包：

pip install -e .

pytest 文章引用Ionel Cristian Mărieş 的这篇博文。

Answer 12

我制作了一个示例项目来演示我如何处理这个问题，这确实是另一个 sys.path hack，如上所述。 Python 同级导入示例，依赖于：

if __name__ == '__main__': import os import sys sys.path.append(os.getcwd())

只要您的工作目录保留在 Python 项目的根目录下，这似乎就非常有效。