1. 项目概述这不是“打个压缩包”而是构建可复用、可分发、可验证的软件交付单元“Creating a package”——光看这个标题很多人第一反应是“不就是把几个文件打包成.zip或.tar.gz吗”我刚入行那会儿也这么想直到在客户现场连续三天排查一个“明明本地跑得好好的部署到服务器就报错ModuleNotFoundError”的问题最后发现根源是我们团队写的那个“工具包”压根没遵循任何语言生态的包管理规范只是靠手动复制.py文件和requirements.txt文本连版本号都写死在注释里。所谓“创建一个包”本质是在特定编程语言生态中定义一个有明确边界、有版本契约、有依赖声明、有安装入口、有元数据描述的最小可交付单元。它不是技术动作而是工程契约。你创建的不是一个文件夹而是一份承诺只要用户执行pip install mytoolPython、npm install mytoolJavaScript或cargo install mytoolRust就能获得一组行为确定、接口稳定、环境隔离的功能集合。这个动作背后牵扯的是模块化设计能力、语义化版本意识、跨环境一致性保障以及对整个开发生命周期的理解。无论你是写Python脚本的运维工程师、做前端组件库的UI开发者还是用Rust写CLI工具的系统程序员只要你希望别人能像使用requests或lodash一样轻松引入你的代码“Creating a package”就是你绕不开的基本功。它解决的核心问题是如何让“我的代码”从“我能用”变成“别人也能可靠、无痛、可预期地用”。接下来的内容我会以Python生态为锚点因其成熟度高、文档丰富、新手友好但所有设计逻辑、决策依据和避坑经验都适用于其他主流语言生态——因为包的本质是开发者之间的信任协议。2. 核心设计思路与方案选型为什么必须放弃“手动复制”拥抱标准化结构2.1 传统做法的致命缺陷从“能跑”到“能维护”之间隔着一堵墙很多团队早期都走过这条路写完功能建个myproject/文件夹里面放main.py、utils.py、config.json再丢个README.md最后用zip -r myproject.zip myproject/打包发给同事。这看似省事实则埋下三颗雷依赖黑洞main.py里import了pandas但requirements.txt里漏写了pandas1.3.0或者写成了pandas1.3.0硬绑定结果用户环境里装的是pandas2.0.0某个API签名变了程序直接崩溃。手动管理依赖等于把版本兼容性责任推给使用者而使用者根本不知道该装什么。导入路径地狱用户解压后执行python myproject/main.py里面from utils import helper会报错——因为Python解释器的sys.path默认不包含当前目录的子目录。你得教用户先cd myproject python -m main或者改PYTHONPATH或者在代码里加一堆sys.path.append()。这不是在提供工具是在设置使用门槛。版本混沌你发了v1.0两周后修了个bug发v1.0.1但没人知道哪个zip对应哪个版本git tag没打CHANGELOG.md是空的用户问“这个功能是哪个版本加的”你得翻Git日志逐条比对。没有版本号就没有可追溯性没有可追溯性就没有可维护性。提示我见过最离谱的案例是某金融公司内部工具包名叫trading_helper_v2_final_really_final.zip里面__version__ 1.0但实际代码已经是第7次大改。这种命名方式本质上是在宣告“我不打算维护它”。2.2 现代包的标准骨架用结构强制规范行为真正的包必须是一个符合语言生态约定的、自描述的目录结构。以Python为例一个最小可行包Minimal Viable Package必须包含以下核心元素顶层包目录如mytool/名称即包名也是Python模块名。所有可被外部import的代码都放在这里且必须包含__init__.py哪怕为空这是Python识别其为包的关键标志。setup.py或pyproject.toml这是包的“宪法”。它声明包名、版本、作者、依赖、入口点等元数据。过去用setup.pyPython脚本现在官方推荐pyproject.toml纯配置文件更安全、更清晰、更易解析。README.md和LICENSE前者是用户第一眼看到的文档后者是法律契约。没有License你的代码在法律上默认是“保留所有权利”别人不敢用。tests/目录强烈建议不是可选项。包的可靠性必须由自动化测试来背书。一个没有测试的包就像一辆没装刹车的车——你能开但没人敢坐。这个结构的价值不在于“看起来专业”而在于它把所有模糊地带都固化下来版本号写在哪、依赖写在哪、主程序入口在哪、文档在哪。当所有包都遵循同一套规则pip才能成为通用的安装引擎twine才能成为通用的上传工具pip-tools才能帮你生成精确的锁定文件。标准化不是束缚而是解放——它让你从“解释怎么用”中解脱出来专注在“怎么做得更好”上。2.3 工具链选型为什么选择pyproject.toml而非setup.py2023年之后的新项目我一律推荐pyproject.toml。原因很实在安全性setup.py本质是可执行Python代码。如果用户从不可信源下载包并运行python setup.py install恶意代码就能在用户机器上执行。而pyproject.toml是纯数据文件pip只读取其中的配置无法执行任意代码风险降为零。可解析性TOML格式是标准的键值对表结构任何语言都能轻松解析。这意味着CI/CD流水线可以写脚本自动读取[project.version]来生成Docker标签或者用GitHub Actions自动发布时提取版本号而不用去exec一个Python脚本来import setup再print(__version__)。生态统一poetry、hatch、setuptools等主流构建工具现在都原生支持pyproject.toml作为单一配置源。你不再需要同时维护setup.py、MANIFEST.in、setup.cfg多个文件所有配置集中一处心智负担大幅降低。当然setup.py并未淘汰大量老项目仍在用。但如果你从零开始或者重构旧包pyproject.toml是唯一合理的选择。它的语法也极其简单一个基础模板如下[build-system] requires [setuptools45, wheel, setuptools_scm[toml]6.2] build-backend setuptools.build_meta [project] name mytool version 0.1.0 description A handy CLI tool for data processing authors [{name Your Name, email youexample.com}] readme README.md requires-python 3.8 classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, ] dependencies [ click8.0, pandas1.5.0, ] [project.optional-dependencies] dev [pytest7.0, black22.0] [project.urls] Homepage https://github.com/yourname/mytool Repository https://github.com/yourname/mytool这段配置里[build-system]告诉pip用什么工具来构建包[project]是核心元数据[project.optional-dependencies]定义了开发时才需要的依赖如测试框架用户pip install mytool时不会装它们但pip install mytool[dev]就会装[project.urls]则为包提供了可点击的链接。每一个字段都有其不可替代的作用。3. 核心细节解析与实操要点从零搭建一个可安装、可发布的Python包3.1 目录结构详解每个文件夹和文件的“存在理由”让我们动手创建一个真实可用的包。假设我们要做一个命令行工具textcount功能是统计文本文件中的行数、单词数和字符数类似Unix的wc命令。以下是经过我十年实战验证的、最精简又最健壮的目录结构textcount/ ├── pyproject.toml # 包的“宪法”定义元数据和构建规则 ├── README.md # 用户第一文档必须包含安装、使用、示例 ├── LICENSE # 开源许可证MIT最常用几行文字解决法律问题 ├── src/ # 源码根目录推荐避免顶层污染 │ └── textcount/ # 实际的Python包目录名称包名 │ ├── __init__.py # 必须存在可为空标识此为Python包 │ ├── __main__.py # 支持python -m textcount调用 │ ├── cli.py # Click命令行接口定义 │ └── core.py # 核心业务逻辑与CLI解耦 ├── tests/ # 测试目录与src平级保持结构清晰 │ ├── __init__.py # 同样必须存在 │ └── test_core.py # 测试core.py的单元测试 └── .gitignore # 忽略构建产物和IDE文件关键细节说明为什么用src/目录这是Python社区近年的强烈推荐实践。如果不放src/你的包目录textcount/和项目根目录同名会导致python -m pytest tests/时Python可能错误地把当前目录即textcount/加入sys.path从而import到未安装的本地代码掩盖了“包是否真能被正确安装和import”的问题。src/结构强制你通过pip install -e .开发模式来安装确保测试环境与最终用户环境一致。我踩过太多次这个坑现在新项目必加src/。__main__.py的作用它让包本身可直接作为脚本运行。用户安装后既可以用textcount --help通过entry-points也可以用python -m textcount --help。后者对调试和CI环境特别友好因为它不依赖shell的PATH查找而是由Python解释器直接定位模块。cli.py与core.py分离这是架构设计的黄金法则。cli.py只负责解析命令行参数、调用core.py的函数、打印结果core.py则纯粹处理业务逻辑不关心输入输出形式。这样未来你想把textcount做成Web API只需写一个新的web.py复用core.py无需重写统计逻辑。解耦是可维护性的基石。3.2pyproject.toml深度配置不只是填空更要理解每个字段的意图上面给出的模板是起点但生产环境需要更多细节。下面是我实际项目中必填的增强版配置并解释每一处的“为什么”[build-system] # 构建系统要求setuptools是事实标准wheel是二进制分发格式 requires [setuptools61.0, wheel, setuptools-scm[toml]8.0] build-backend setuptools.build_meta [project] name textcount # 版本号这里用setuptools-scm动态生成而非硬编码 # 好处git tag v0.1.0 - 自动得到0.1.0git tag v0.1.0-1-gabc123 - 0.1.0.dev1gabc123 dynamic [version] description A simple, fast command-line tool to count lines, words, and characters in text files. authors [{name Alex Chen, email alexexample.com}] readme README.md # 要求的最低Python版本根据你代码中使用的特性决定 # 例如用了match/case就必须3.10用了str.removeprefix()就必须3.9 requires-python 3.8 # 依赖列表精确到最小兼容版本避免太宽泛导致意外升级 dependencies [ click8.0,9.0, # Click 8.x是稳定API9.x有breaking change rich12.0,13.0, # 用于彩色输出同理 ] # 可选依赖开发时用用户不装 # 注意dev是组名可自定义如test, docs optional-dependencies { dev [pytest7.0,8.0, pytest-cov4.0, black23.0, ruff0.0.250], docs [sphinx6.0, furo2023.0], } # 入口点定义命令行工具名和对应的函数 # textcount textcount.cli:main 表示 # 当用户输入textcount命令时执行src/textcount/cli.py里的main()函数 [project.entry-points.console_scripts] textcount textcount.cli:main # 项目URL这些链接会显示在PyPI页面上对用户至关重要 [project.urls] Homepage https://github.com/alexchen/textcount Repository https://github.com/alexchen/textcount Documentation https://textcount.readthedocs.io Changelog https://github.com/alexchen/textcount/blob/main/CHANGELOG.md # setuptools-scm配置告诉它如何从git获取版本 [tool.setuptools-scm] # 使用git描述符tag格式为v{version} version-file src/textcount/_version.py write-to src/textcount/_version.py write-to-template # This file is auto-generated by setuptools-scm. Do not edit. __version__ {version} # Black代码格式化配置内联避免单独的pyproject.toml [tool.black] line-length 88 skip-string-normalization true include \.pyi?$ exclude /( \.eggs | \.git | \.mypy_cache | \.tox | \.venv | _build | buck-out | build | dist )/ # Ruff静态检查配置替代flake8pylint更快更准 [tool.ruff] select [E, F, I, B, C4, SIM] # 错误、格式、导入、bug、集合字面量、简化 ignore [E501] # 忽略行过长警告由black处理 line-length 88 src [src, tests]这个配置的威力在于它把构建、版本、依赖、入口、文档、测试、格式化、静态检查全部集成在一个文件里。setuptools-scm动态版本管理让我彻底告别手动改__version__字符串entry-points让textcount命令全局可用optional-dependencies让开发环境一键配置pip install -e .[dev]tool.black和tool.ruff则把代码质量检查前置到本地而不是等CI失败才反馈。每一个配置项都是为了解决一个具体痛点。3.3src/textcount/core.py业务逻辑的纯净实现核心逻辑必须与框架解耦。core.py只做一件事给定一个文件路径返回一个包含行数、单词数、字符数的字典。它不关心是命令行调用、Web请求还是单元测试。Core business logic for text counting. from pathlib import Path from typing import Dict, Any def count_file(filepath: str) - Dict[str, int]: Count lines, words, and characters in a text file. Args: filepath: Path to the text file. Returns: A dictionary with keys lines, words, chars and their counts. Raises: FileNotFoundError: If the file does not exist. PermissionError: If the file cannot be read. UnicodeDecodeError: If the file is not valid UTF-8. path Path(filepath) if not path.exists(): raise FileNotFoundError(fFile not found: {filepath}) if not path.is_file(): raise ValueError(fNot a file: {filepath}) try: content path.read_text(encodingutf-8) except UnicodeDecodeError as e: # 尝试用latin-1总能解码并给出警告 content path.read_text(encodinglatin-1) print(fWarning: {filepath} is not UTF-8 encoded. Using latin-1. Error: {e}) lines len(content.splitlines()) words len(content.split()) chars len(content) return {lines: lines, words: words, chars: chars} # 为了方便测试提供一个针对字符串的函数 def count_string(text: str) - Dict[str, int]: Count lines, words, and characters in a string. lines len(text.splitlines()) words len(text.split()) chars len(text) return {lines: lines, words: words, chars: chars}这个函数的设计哲学是强类型提示- Dict[str, int]让IDE能自动补全也让调用者清楚返回结构。详尽的文档字符串说明了参数、返回值、可能抛出的异常。这是用户阅读API的第一手资料。防御性编程检查文件是否存在、是否为文件、编码错误时优雅降级用latin-1兜底并警告而不是让程序崩溃。职责单一只做计数不做打印、不做参数解析、不做文件遍历那是CLI层的事。3.4src/textcount/cli.py优雅的命令行界面CLI是用户接触包的第一界面必须直观、健壮、有帮助。我们用Click库它比原生argparse更简洁且自带颜色、分组、自动帮助生成。Command-line interface for textcount. import click from textcount.core import count_file, count_string click.command() click.argument(files, nargs-1, typeclick.Path(existsTrue, dir_okayFalse)) click.option(--total, -t, is_flagTrue, helpShow total counts across all files.) click.option(--bytes, -c, is_flagTrue, helpCount bytes instead of characters.) click.version_option(package_nametextcount) def main(files, total, bytes): Count lines, words, and characters in text files. FILES: One or more text file paths. If no files are given, reads from stdin. Examples: textcount file1.txt file2.txt textcount *.txt echo hello world | textcount if not files: # 从stdin读取 import sys try: content sys.stdin.read() except KeyboardInterrupt: return result count_string(content) _print_result(result, stdin) return results [] for f in files: try: result count_file(f) results.append((f, result)) _print_result(result, f) except Exception as e: click.echo(fError processing {f}: {e}, errTrue) if total and len(results) 1: total_lines sum(r[lines] for _, r in results) total_words sum(r[words] for _, r in results) total_chars sum(r[chars] for _, r in results) _print_result({lines: total_lines, words: total_words, chars: total_chars}, total) def _print_result(result: dict, filename: str): Helper to print formatted result. # 使用rich库实现彩色输出更美观 try: from rich.console import Console console Console() console.print(f{result[lines]:8d} {result[words]:8d} {result[chars]:8d} {filename}) except ImportError: # 如果rich没装回退到纯文本 print(f{result[lines]:8d} {result[words]:8d} {result[chars]:8d} {filename})关键点click.command()和click.option()声明命令和选项--total和--bytes是用户最常需要的开关。nargs-1允许传入多个文件textcount file1.txt file2.txt。stdin支持当不传文件时自动从管道读取echo hi | textcount这是Unix哲学的体现。错误处理单个文件出错不影响其他文件处理并将错误输出到stderrerrTrue。_print_result封装分离输出逻辑便于未来替换为JSON、CSV等格式。4. 完整实操流程与核心环节实现从本地开发到PyPI发布4.1 本地开发与测试确保每一步都“可验证”创建包不是写完代码就结束而是要建立一套本地可重复的验证流程。我的标准步骤如下第一步初始化Git仓库并打初始tagmkdir textcount cd textcount git init # 创建上面描述的完整目录结构 touch pyproject.toml README.md LICENSE mkdir -p src/textcount tests touch src/textcount/{__init__.py,__main__.py,cli.py,core.py} tests/__init__.py tests/test_core.py # 写入基础内容后 git add . git commit -m chore: init project structure git tag v0.0.1注意git tag是setuptools-scm工作的前提。没有tag它无法生成版本号。第二步创建并激活虚拟环境python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows第三步以开发模式安装包pip install -e .[dev]-e代表“editable”即“可编辑安装”。它会在Python的site-packages里创建一个指向你当前src/目录的链接而不是复制一份代码。这样你修改src/textcount/core.py后textcount命令立即生效无需反复pip install。.[dev]则表示同时安装pyproject.toml中[project.optional-dependencies.dev]定义的依赖pytest, black等。第四步运行测试验证核心逻辑先写一个简单的测试# tests/test_core.py import pytest from textcount.core import count_string, count_file import tempfile import os def test_count_string(): assert count_string(a b c) {lines: 1, words: 3, chars: 5} assert count_string() {lines: 0, words: 0, chars: 0} def test_count_file(): # 创建临时文件进行测试 with tempfile.NamedTemporaryFile(modew, deleteFalse, suffix.txt) as f: f.write(line1\nline2\n) temp_path f.name try: result count_file(temp_path) assert result[lines] 2 assert result[words] 2 assert result[chars] 13 # line1\nline2\n - 5151113 finally: os.unlink(temp_path)然后运行pytest tests/ -v如果测试通过说明core.py逻辑正确且包结构能让pytest正确找到并importtextcount模块。这是最关键的验证点——证明你的包“能被正确安装和使用”。第五步格式化与静态检查black src/ tests/ ruff check --fix src/ tests/black自动格式化代码ruff检查潜在bug和风格问题。这两个命令应该成为你每次提交前的固定动作。4.2 构建分发包生成可上传的.whl和.tar.gz当本地一切就绪就可以构建分发包了。现代Python推荐构建wheel.whl格式它是预编译的二进制包安装速度极快且不依赖用户的编译环境。# 确保构建工具是最新的 pip install --upgrade build twine # 构建 python -m build执行后会在项目根目录下生成dist/文件夹里面有两个文件textcount-0.0.1-py3-none-any.whlWheel包py3表示Python 3none-any表示纯Python无平台依赖。textcount-0.0.1.tar.gzSource Distributionsdist是源码压缩包供无法使用wheel的环境如某些嵌入式系统使用。提示build命令会自动读取pyproject.toml调用setuptools完成构建。你不需要手动写setup.py。4.3 本地安装验证模拟用户视角构建完成后不要急着上传先在干净环境中验证安装是否真的work# 创建一个全新的虚拟环境 python -m venv /tmp/textcount-test source /tmp/textcount-test/bin/activate # 从本地dist安装模拟用户从PyPI下载 pip install dist/textcount-0.0.1-py3-none-any.whl # 验证命令是否可用 textcount --help # 创建一个测试文件并运行 echo Hello World test.txt textcount test.txt # 应该输出 1 2 12 test.txt deactivate rm -rf /tmp/textcount-test这一步至关重要。它模拟了真实用户的安装体验。如果这一步失败PyPI上的包也一定会失败。我曾因跳过此步在PyPI发布后收到数十个“command not found”的issue只因entry-points配置写错了。4.4 发布到PyPI一次成功永不后悔PyPI是Python世界的中央仓库。发布前请务必注册账号访问 https://pypi.org/account/register/ 获取用户名和密码。创建API token在 https://pypi.org/manage/account/token/ 创建一个tokenscope选Entire account或限制到textcount项目永远不要在配置文件中硬编码密码。配置~/.pypirc可选但推荐[distutils] index-servers pypi [pypi] username __token__ password pypi-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX然后上传twine upload dist/*twine会将dist/下的所有文件上传到PyPI。上传成功后访问https://pypi.org/project/textcount/你应该能看到你的包页包含README渲染、版本历史、下载统计。注意PyPI上的包名是全局唯一的且一旦上传不能删除或覆盖同名同版本的包。所以请确保pyproject.toml中的name和version准确无误。如果发错了只能发新版本如v0.0.2。5. 常见问题与排查技巧实录那些文档里不会写的“血泪教训”5.1 “ModuleNotFoundError: No module named xxx” —— 最高频的包结构陷阱现象本地pip install -e .后python -m textcount能运行但textcount命令报错ModuleNotFoundError。根本原因entry-points中指定的模块路径错误。textcount.cli:main要求textcount包必须能被Python import而import textcount失败通常是因为src/目录没被加入sys.path。pip install -e .会自动处理但如果你手动python setup.py develop可能遗漏。src/textcount/__init__.py文件缺失或为空注意必须存在哪怕为空。项目根目录下有一个textcount.py或textcount/文件夹与包名冲突导致Python优先import了它。排查步骤在命令行中进入项目根目录运行python -c import textcount; print(textcount.__file__)。如果报错说明包根本没被正确安装。检查pip show textcount确认Location:指向的是你的项目路径且Version:正确。检查src/textcount/__init__.py是否存在。终极解决方案严格遵守src/布局并始终用pip install -e .[dev]安装。这是最可靠的开发模式。5.2 “ImportError: cannot import name xxx from yyy” —— 循环导入的幽灵现象textcount命令能启动但一执行就报错说某个函数找不到。场景还原cli.py里from textcount.core import count_file而core.py里又from textcount.cli import some_util形成循环。为什么发生Python在import时会按顺序执行模块代码。如果A导入BB又在定义过程中导入A就会卡住。解决方法重构把some_util移到一个独立的utils.py模块让cli.py和core.py都import它打破循环。延迟导入在core.py的函数内部需要时才import textcount.cli而不是在模块顶层。但这通常是设计缺陷的遮羞布。实操心得我在review代码时会用pydeps textcount一个可视化import依赖的工具生成依赖图。如果图中出现环立刻重构。没有环的依赖图才是健康的包。5.3 “The rich distribution was not found” —— 可选依赖的加载难题现象用户安装textcount后运行textcount报错说找不到rich尽管rich在dependencies里是必需的。真相你在pyproject.toml里把rich写在了[project.optional-dependencies.dev]下而不是[project.dependencies]里optional-dependencies只在你显式指定时才安装普通pip install textcount不会装它们。修正检查pyproject.toml确保所有运行时必需的库如click,rich都在[project.dependencies]列表中。optional-dependencies只放pytest,black这类开发期工具。5.4 “UnicodeDecodeError: utf-8 codec cant decode byte” —— 生产环境的编码噩梦现象用户用textcount处理一个Windows记事本保存的文件报错。原因Windows记事本默认用GBK或UTF-16编码而你的代码强制用utf-8读取。专业解法不要试图猜编码chardet库不可靠且慢。提供--encoding命令行选项让用户指定。在core.py的count_file函数中增加编码参数def count_file(filepath: str, encoding: str utf-8) - Dict[str, int]: try: content Path(filepath).read_text(encodingencoding) except UnicodeDecodeError: # 尝试fallback到latin-1万能解码器 content Path(filepath).read_text(encodinglatin-1) print(fWarning: {filepath} decoded with latin-1 (not {encoding}).) # ... rest of logic然后在cli.py中暴露这个选项click.option(--encoding, -e, defaultutf-8, helpFile encoding (default: utf-8)) def main(..., encoding): ... result count_file(f, encodingencoding)这比任何自动检测都更可靠、更透明。5.5 “No module named setuptools_scm” —— 构建时的依赖地狱现象在CI流水线如GitHub Actions中运行python -m build报错说找不到setuptools_scm。原因pyproject.toml的[build-system]部分指定了requires [setuptools61.0, wheel, setuptools-scm[toml]8.0]但CI环境的Python是干净的没有预装这些构建依赖。解决方案在CI脚本中先pip install构建依赖再build# .github/workflows/publish.yml - name: Install build dependencies run: pip install setuptools wheel setuptools-scm[toml] - name: Build package run: python -m build或者更现代的做法是使用pip的--build-option但直接pip install最稳妥。6. 后续演进与工程化思考从“能用”到“好用”、“爱用”创建一个包只是起点。一个真正成功的包会持续演进。基于我维护多个开源包的经验后续值得投入的方向有自动化发布流水线用GitHub Actions监听git tag事件自动构建、测试、上传到PyPI。一行git tag v1.0.0 git push --tags就完成发布杜绝人为失误。自动生成CHANGELOG结合conventional commits如feat: add --encoding option和工具如auto-changelog每次发布时自动生成带链接的变更日志