Python中.cfg与.toml配置文件及命名空间问题咨询

一、.cfg（setup.cfg）与.toml（pyproject.toml）的作用 #

pyproject.toml #

这是PEP 621规定的现代Python项目标准配置入口，核心职责：

• 声明构建系统依赖（比如setuptools），告知pip/build工具用什么组件构建项目
• 定义项目核心元数据：名称、版本、作者、依赖等，这部分配置优先级最高，会覆盖setup.cfg里的重复项（比如你配置中的version）

setup.cfg #

这是setuptools的传统配置文件，用来补充细粒度的打包、安装规则，比如：

• 包目录映射（package-dir）
• 命名空间包声明（namespace_packages）
• 包搜索路径（options.packages.find）
• 脚本、数据文件打包规则等

PEP 621推行后，pyproject.toml成为元数据的权威来源，setup.cfg仅负责构建相关细节配置，一个项目只需一个setup.cfg统一管理所有打包规则，无需为每个包单独配置。

二、你的.cfg配置未生效、命名空间不识别的原因 #

1. .cfg里的version被覆盖 #

pyproject.toml的[project]块是元数据的官方定义，其中version = "4"的优先级高于setup.cfg的[metadata]version = 666，所以安装后项目版本显示为4，属于正常规则。

2. 命名空间配置完全不匹配 #

你的setup.cfg里写了namespace_packages = wow，但项目实际的顶层包是src/Whatever，配置的命名空间名称与实际目录名完全不一致，自然无法生效。

另外，Python命名空间包需要满足两种规范之一：

• 原生命名空间包：顶层命名空间目录（比如Whatever）下没有__init__.py文件
• pkg_resources风格命名空间包：在Whatever/__init__.py里添加代码：

  __import__('pkg_resources').declare_namespace(__name__)
  

如果你的Whatever目录只有普通的__init__.py，又未做上述声明，它只是一个普通包，而非命名空间包。

3. 包搜索路径配置错误 #

setup.cfg里的[options.packages.find]where = youwant是无效路径，应改为where = src，这样setuptools才会去src目录下搜索要打包的包。你能正常导入whatever.package1，是因为options.package-dir = = src已将src设为包根目录，setuptools默认会在包根目录下搜索，相当于忽略了错误的where配置。

三、为何同名包会覆盖官方库 #

Python的模块导入遵循sys.path搜索优先级：当执行import SQLAlchemy时，Python会依次检查sys.path列表里的目录，找到第一个名为SQLAlchemy的包/模块就会导入它。

如果你的项目里有一个SQLAlchemy包，且项目目录（或安装后的site-packages路径）在sys.path里的位置比官方SQLAlchemy库的路径靠前，Python就会优先导入你自己的包，从而覆盖官方库。这和Java类加载器的路径优先级逻辑类似，但Python默认没有Java那样的模块化隔离机制，除非手动调整sys.path或使用虚拟环境隔离项目依赖。

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