Python自制模块导入后无法找到类？问题排查与解决

按照Python官方打包教程搭建Windows环境下的Python类模块，项目结构如下：

projfolder/
    mymodule/
        mymodule.py
        __init__.py
        __main__.py
    tests/
    LICENSE
    MANIFEST.in
    README.md
    pyproject.toml

pyproject.toml配置内容：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mymodule"
version = "1.0"
authors = [
    {name="author", email="author@gmail.com"}
]
description = "description"
readme = "README.md"
license = {file="LICENSE"}
requires-python = ">=3.6"
classifiers = [
     'Development Status :: status',
     'Intended Audience :: for Author',
     'Operating System :: OS Independent',
     'Programming Language :: Python3',
     'Topic :: topic :: topic',
]

执行以下命令无报错或警告：

py -m pip install --upgrade build
py -m build
pip install ./dist/mymodule-1.0.tar.gz

执行pip show mymodule可正常查到模块，对应路径也存在相关文件，但运行以下代码时提示无法找到myclass：

import mymodule
mymodule.myclass

可能原因及解决方法 #

原因1：myclass未暴露到包顶层命名空间 #

myclass定义在mymodule/mymodule.py子文件中，但顶层mymodule包默认不会自动导入子文件内容，导致直接通过mymodule.myclass无法访问。

解决方法：

• 方案一：修改顶层__init__.py，将myclass导入到包命名空间：

  # mymodule/__init__.py
  from .mymodule import myclass
  

• 方案二：导入时指定子模块：

  import mymodule.mymodule
  mymodule.mymodule.myclass
  # 或更简洁写法
  from mymodule.mymodule import myclass
  

原因2：MANIFEST.in配置遗漏，mymodule.py未被打包 #

如果MANIFEST.in未正确包含模块文件，打包过程会漏掉mymodule.py，安装后自然找不到类定义。

解决方法：
检查MANIFEST.in，确保包含模块目录下所有.py文件：

include mymodule/*.py

然后重新打包并强制覆盖安装：

py -m build
pip install --force-reinstall ./dist/mymodule-1.0.tar.gz

原因3：环境路径冲突，导入了旧版本或同名模块 #

多Python环境共存时，可能出现pip安装的模块与当前Python解释器使用的模块路径不匹配，或者存在旧版本同名模块，导致导入的不是刚安装的版本。

解决方法：

• 查看模块实际安装路径，确认文件完整性：

  pip show mymodule
  

  进入输出的Location路径，检查mymodule目录下是否存在mymodule.py且包含myclass定义。
• 强制覆盖安装，确保替换旧版本：

  pip install --force-reinstall ./dist/mymodule-1.0.tar.gz
  

• 明确指定Python环境，避免混淆：比如用py -3.x -m pip install ...指定具体版本的Python和pip。

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