记录 | 个人开发库推送至PyPi流程梳理（ChatGPT to Markdown 工具发布完整流程）

前言：从ChatGPT对话到可复用的Python包作为一名技术博主，我经常需要把ChatGPT生成的精彩回答保存为Markdown文件。手动复制粘贴不仅效率低，还容易丢失格式。于是，我萌生了一个想法：写一个Python工具，把ChatGPT对话一键导出为Markdown。更妙的是，把这个工具发布到PyPi上，让全世界的人都能用pip install安装！本文将详细记录我从零开始，将本地Python脚本打包、测试、并成功推送至PyPi的完整流程。无论你是初学者还是老手，都能从中获得实用的经验。## 一、准备工作：项目结构与基础文件### 1.1 创建项目目录首先，在本地创建一个项目文件夹，例如chatgpt_to_markdown。目录结构如下：chatgpt_to_markdown/├── chatgpt_to_markdown/│ ├── __init__.py│ └── converter.py├── tests/│ └── test_converter.py├── README.md├── setup.py├── setup.cfg└── LICENSE### 1.2 核心功能代码我们的核心功能是将ChatGPT的JSON格式对话转换为Markdown。下面是一个简化版的实现：python# chatgpt_to_markdown/converter.pyimport jsonfrom typing import List, Dictdef convert_to_markdown(conversation: List[Dict]) -> str: """ 将ChatGPT对话列表转换为Markdown格式 Args: conversation: 包含对话消息的列表，每条消息应有'role'和'content'字段 Returns: 格式化后的Markdown字符串 """ markdown_lines = [] for msg in conversation: role = msg.get('role', 'unknown') content = msg.get('content', '') # 根据角色添加不同前缀 if role == 'user': markdown_lines.append(f"## 用户提问\n\n{content}\n") elif role == 'assistant': markdown_lines.append(f"## ChatGPT回答\n\n{content}\n") else: markdown_lines.append(f"## {role.capitalize()}\n\n{content}\n") return '\n'.join(markdown_lines)def save_to_file(markdown_content: str, filename: str = "output.md"): """ 将Markdown内容保存到文件 Args: markdown_content: 要保存的Markdown字符串 filename: 输出文件名，默认为output.md """ with open(filename, 'w', encoding='utf-8') as f: f.write(markdown_content) print(f"文件已保存为: {filename}")### 1.3 测试代码编写测试来确保功能正确：python# tests/test_converter.pyimport unittestfrom chatgpt_to_markdown.converter import convert_to_markdown, save_to_fileimport tempfileimport osclass TestConverter(unittest.TestCase): """测试转换器核心功能""" def setUp(self): """准备测试数据""" self.sample_conversation = [ {"role": "user", "content": "请用Python写一个Hello World"}, {"role": "assistant", "content": "python\nprint(‘Hello World’)\n"} ] def test_convert_to_markdown(self): """测试Markdown转换""" result = convert_to_markdown(self.sample_conversation) self.assertIn("## 用户提问", result) self.assertIn("## ChatGPT回答", result) self.assertIn("print('Hello World')", result) def test_save_to_file(self): """测试文件保存功能""" content = "# 测试内容" with tempfile.NamedTemporaryFile(suffix='.md', delete=False) as tmp: save_to_file(content, tmp.name) with open(tmp.name, 'r', encoding='utf-8') as f: saved_content = f.read() self.assertEqual(saved_content, content) os.unlink(tmp.name)if __name__ == '__main__': unittest.main()## 二、打包配置：让项目可以被pip安装### 2.1 setup.py文件这是PyPi打包的核心文件，包含了项目的元数据：python# setup.pyfrom setuptools import setup, find_packagessetup( name='chatgpt-to-markdown', # PyPi上的包名 version='0.1.0', author='你的名字', author_email='你的邮箱@example.com', description='将ChatGPT对话转换为Markdown格式的工具', long_description=open('README.md', 'r', encoding='utf-8').read(), long_description_content_type='text/markdown', url='https://github.com/你的用户名/chatgpt-to-markdown', packages=find_packages(), classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], python_requires='>=3.6', install_requires=[], # 如果有依赖，在这里列出)### 2.2 setup.cfg文件另一种配置方式，我更喜欢这种简洁的写法：ini# setup.cfg[metadata]name = chatgpt-to-markdownversion = 0.1.0description = 将ChatGPT对话转换为Markdown格式long_description = file: README.mdlong_description_content_type = text/markdownurl = https://github.com/你的用户名/chatgpt-to-markdownauthor = 你的名字author_email = 你的邮箱@example.comlicense = MITclassifiers = Programming Language :: Python :: 3 License :: OSI Approved :: MIT License Operating System :: OS Independent[options]packages = find:python_requires = >=3.6## 三、本地测试与构建### 3.1 安装本地包在项目根目录下运行：bashpip install -e .这会以开发模式安装包，任何代码修改都会立即生效。### 3.2 运行测试bashpython -m pytest tests/如果所有测试通过，说明代码没有问题。### 3.3 构建分发包使用setuptools和wheel构建：bashpython setup.py sdist bdist_wheel这会在dist/目录下生成两个文件：- chatgpt_to_markdown-0.1.0.tar.gz（源码包）- chatgpt_to_markdown-0.1.0-py3-none-any.whl（wheel包）## 四、推送至PyPi：从本地到全球### 4.1 注册PyPi账号访问 pypi.org 注册账号，并启用双因素认证（推荐）。### 4.2 安装上传工具bashpip install twine### 4.3 配置API Token在PyPi网站上生成一个API Token，然后创建~/.pypirc文件：ini[pypi]username = __token__password = pypi-你的token### 4.4 上传包bashtwine upload dist/*如果一切顺利，你会看到类似这样的输出：Uploading distributions to https://upload.pypi.org/legacy/Uploading chatgpt_to_markdown-0.1.0-py3-none-any.whl100%|████████████████████| 4.15k/4.15k [00:02<00:00, 1.68kB/s]Uploading chatgpt_to_markdown-0.1.0.tar.gz100%|████████████████████| 3.21k/3.21k [00:01<00:00, 2.04kB/s]### 4.5 验证安装bashpip install chatgpt-to-markdown然后在你的Python代码中测试：pythonfrom chatgpt_to_markdown import converter# 现在可以正常使用了！## 五、常见问题与解决方案### 5.1 版本号冲突如果你之前上传过同名包，需要更新版本号。在setup.py中修改version字段，然后重新构建和上传。### 5.2 依赖问题如果包有外部依赖，需要在install_requires中列出。例如：pythoninstall_requires=[ 'requests>=2.25.0', 'beautifulsoup4>=4.9.0',]### 5.3 命名规范PyPi包名只能包含小写字母、数字、短横线和下划线。避免使用保留名或已存在的名字。## 六、持续集成与自动化为了让发布流程更丝滑，可以配置GitHub Actions自动发布：yaml# .github/workflows/publish.ymlname: Publish to PyPIon: release: types: [published]jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install setuptools wheel twine - name: Build and publish env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | python setup.py sdist bdist_wheel twine upload dist/*这样，每次发布GitHub Release时，包就会自动上传到PyPi。## 总结通过这个ChatGPT to Markdown工具的完整发布流程，我们学到了：1. 项目结构：合理的目录组织是发布的基础，包括核心代码、测试文件和配置文件。2. 打包配置：setup.py或setup.cfg是连接本地代码和PyPi的桥梁，需要仔细填写元数据。3. 测试与构建：在发布前一定要本地测试，使用pytest确保功能正确，再用setuptools构建分发包。4. 上传与发布：twine是官方的上传工具，配合API Token使用更安全。5. 持续集成：自动化发布可以节省大量时间，避免人为错误。最后赠送一个小贴士：发布前先用test.pypi.org测试一下，确保一切正常再发布到正式PyPi。现在，你已经掌握了从零到一发布Python包的全部技能，快去把你的创意分享给全世界吧！