Python包cfkit安装后文件未存入site-packages子目录的问题解决

目录结构 #

cfkit/
│
├── README.md
├── setup.py
├── .gitignore
├── LICENSE.txt
├── src/
│   ├── problem.py
│   ├── contest.py
│   ├── __init__.py
│   ├── cmd/
│   │   ├── __init__.py
│   │   ├── cli.py
│   ├── client/
│   │   ├── __init__.py
│   │   ├── login.py
│   │   ├── submit.py
│   │   ├── fetch.py
│   ├── config/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── implementation.py
│   ├── dependencies/
│   │   ├── memory_time_usage.go
│   │   ├── memory_time_usage.exe
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── common.py
│   │   ├── constants.py
│   │   ├── variables.py
│   ├── json/
│   │   ├── file1.json
│   │   ├── file2.json
│
├── examples/
│   ├── example1.gif
├── Docs/
│   ├── how_to_use.md

当前setup.py内容 #

from shutil import copy
from pathlib import Path
from platform import uname
from setuptools import setup, find_packages

with open("README.md", 'r', encoding="UTF-8") as file:
    long_description = file.read()

package_data = {
    "src/json": ["json/*.json"],
    "docs": ["docs/*.md"],
    "examples": ["examples/*.gif"],
    '': ["README.md", "LICENSE.txt"],
}

... Some other code

setup(
    name='cfkit',
    version='0.0.1',
    author='Yassine Ghoudi',
    author_email='ghoudi.dev@gmail.com',
    description='A simple Python CLI tool example',
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/ghoudiy/cfkit",
    license="MIT",
    packages=find_packages(where="src"),
    package_data=package_data,
    include_package_data=True,
    python_requires=">=3.8",
    install_requires=[
        'requests',
        'MechanicalSoup',
        'beautifulsoup4',
        'prompt_toolkit'
    ],
    entry_points={
        'console_scripts': [
            'cf = cfkit.cmd.cli:main',
        ],
    },
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
    keywords="CLI, Tool, Python"
)

问题现象 #

1. 运行pip install .后，模块直接安装到site-packages根目录（如site-packages/utils、site-packages/client），而非预期的site-packages/cfkit目录。
2. 无法通过import cfkit导入包，也不能使用from cfkit.utils.variables import ...这类路径导入。
3. 安装时出现元数据生成错误：

Preparing metadata (setup.py) ... error
error: subprocess-exited-with-error

× python setup.py egg_info did not run successfully.
│ exit code: 1
╰─> [9 lines of output]
    running egg_info
    creating /tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info
    writing /tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info/PKG-INFO
    writing dependency_links to /tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info/dependency_links.txt
    writing entry points to /tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info/entry_points.txt
    writing requirements to /tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info/requires.txt
    writing top-level names to /tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info/top_level.txt
    writing manifest file '/tmp/pip-pip-egg-info-2l3_y70l/cfkit.egg-info/SOURCES.txt'
    error: package directory 'utils' does not exist
    [end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

1. 调整目录结构，建立顶层包目录 #

当前src目录下直接存放子模块，缺少顶层cfkit包目录。将src下所有文件和子目录移动到src/cfkit/中，调整后目录结构如下：

cfkit/
│
├── README.md
├── setup.py
├── .gitignore
├── LICENSE.txt
├── src/
│   ├── cfkit/
│   │   ├── __init__.py
│   │   ├── problem.py
│   │   ├── contest.py
│   │   ├── cmd/
│   │   │   ├── __init__.py
│   │   │   ├── cli.py
│   │   ├── client/
│   │   │   ├── __init__.py
│   │   │   ├── login.py
│   │   │   ├── submit.py
│   │   │   ├── fetch.py
│   │   ├── config/
│   │   │   ├── __init__.py
│   │   │   ├── config.py
│   │   │   ├── implementation.py
│   │   ├── dependencies/
│   │   │   ├── memory_time_usage.go
│   │   │   ├── memory_time_usage.exe
│   │   ├── utils/
│   │   │   ├── __init__.py
│   │   │   ├── common.py
│   │   │   ├── constants.py
│   │   │   ├── variables.py
│   │   ├── json/
│   │   │   ├── file1.json
│   │   │   ├── file2.json
│
├── examples/
│   ├── example1.gif
├── Docs/
│   ├── how_to_use.md

2. 修改setup.py配置 #

修正包路径与资源文件配置 #

• package_data仅用于包内资源，需以顶层包名cfkit作为键，指定包内的json、依赖文件路径。
• 非包内的文件（如docs、examples）需用data_files参数处理，避免混淆包资源与外部资源。
• 添加package_dir={"": "src"}，明确告诉setuptools包的根目录是src。

修改后的核心代码片段：

package_data = {
    "cfkit": [
        "json/*.json",
        "dependencies/*"
    ],
}

data_files = [
    ("docs", ["Docs/how_to_use.md"]),
    ("examples", ["examples/example1.gif"]),
    ("", ["README.md", "LICENSE.txt"])
]

setup(
    # 保留原有其他参数
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    package_data=package_data,
    data_files=data_files,
    # 保留原有其他参数
)

3. 验证修复步骤 #

1. 卸载错误安装版本：pip uninstall cfkit
2. 重新安装包：pip install .
3. 验证导入：打开Python交互环境，测试import cfkit和from cfkit.utils.variables import ...是否正常运行。
4. 检查site-packages目录，确认cfkit文件夹存在，所有子模块均在该目录下。

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