PyPI/pip安装与本地运行兼容的Python包结构配置问题

1. 修正核心命名问题 #

Python模块/包名不允许包含连字符（-），你当前的my-package.py文件名会导致导入语法错误，必须先调整：

• 将包目录名从my-package改为my_package（pip安装时包名仍可叫my-package，二者不冲突）
• 将my-package/my-package.py改名为my_package/core.py（或main.py，避免与包名重复引发混淆）

调整后的最终文件结构：

LICENSE
pyproject.toml
README.md
my_package/
    __init__.py
    core.py   # 原my-package.py
    utils.py
tests/

2. 内部导入规则 #

包内文件间的相互引用，统一使用以下两种方式之一，即可兼顾安装后和本地运行场景：

方式1：相对导入（推荐） #

在core.py中导入utils.py的函数：

from .utils import util_function

若utils.py需要导入core.py的函数：

from .core import my_function

方式2：绝对导入 #

在core.py中：

from my_package.utils import util_function

3. 对外导入简化（可选） #

如果希望用户安装后可以直接通过from my_package import my_function导入，而不用写from my_package.core import my_function，在my_package/__init__.py中添加导出语句：

# 导出core模块的函数
from .core import my_function
# 可选：直接导出utils模块的函数
from .utils import util_function

这样用户安装后就能满足你的需求：

• from my_package import my_function
• from my_package.utils import util_function

4. 本地运行正确姿势 #

不能直接执行python my_package/core.py（会导致Python无法识别包结构），必须从项目根目录运行：

python -m my_package.core

这种方式会让Python把当前目录加入sys.path，将my_package识别为合法包，相对/绝对导入都能正常工作。

进阶：开发模式安装 #

如果需要频繁测试，可先安装开发版包：

pip install -e .

安装后不仅能正常导入，还可以通过配置pyproject.toml的入口点，直接用命令运行脚本：
在pyproject.toml中添加：

[project.scripts]
my-package-cli = "my_package.core:main"

假设core.py中有main()函数作为入口，之后就能直接运行：

my-package-cli

5. pyproject.toml关键配置示例 #

确保pyproject.toml的包配置正确，示例如下：

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

[project]
name = "my-package"  # PyPI上显示的包名，可保留连字符
version = "0.1.0"
description = "你的包描述"
readme = "README.md"
license = { file="LICENSE" }
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

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