Python 应用程序开发指南（二）：项目基础夯实

💡 本文适合刚开始参与 Python 项目开发的新手阅读。如果你已经学过 Python，但对实际开发场景还是感到迷茫，这篇也是写给你的。
我不仅想讲“怎么写代码”，更想告诉你“为什么这么写”，避免只停留在教科书上的知识。请不要觉得我们还在提及过于基础的内容，这些知识点是你在实际项目中最常用的。
我会给大家逐一讲解实际工程中的应用场景、注意事项、为什么这么写、怎么写得更好，确保每一个小节不仅有代码，还有“思维”。

版本控制与协作#

Git基础#

Git是目前最流行的版本控制系统，可以追踪文件变化和协作开发。换句话来说，Git 是团队协作的「时间机器」，能回到过去的任意一个版本。

实战建议：

写代码之前先 git pull，避免冲突
冲突解决要细心，注意谁覆盖了谁

具体版本控制与写作的内容，会专门用一个博文好好来讲解。在这里，大家只需要先有个框架和概念。

基本命令：#

# 初始化Git仓库
git init

# 查看状态
git status

# 添加文件到暂存区
git add filename.py

# 提交更改
git commit -m "添加了新功能"

# 查看提交历史
git log

# 从远程仓库克隆
git clone https://github.com/username/repository.git

# 推送到远程仓库
git push origin main

# 从远程仓库拉取更新
git pull origin main

分支管理#

# 创建新分支
git branch feature-login

# 切换到分支
git checkout feature-login

# 合并分支
git merge feature-login

数据交换格式#

JSON#

JSON是最常用的数据交换格式，前后端通信的标准。

import json

# Python对象转JSON字符串
user_data = {
    "name": "张三",
    "age": 25,
    "skills": ["Python", "PyQt"]
}
json_str = json.dumps(user_data, ensure_ascii=False)
print(json_str)

# JSON字符串转Python对象
received_data = '{"name": "李四", "age": 30}'
user = json.loads(received_data)
print(user["name"])  # 输出: 李四

CSV#

CSV用于表格数据，是sequenzo包用户上传的最主要处理的数据文件格式。

下面的例子与sequenzo无关，只是帮助大家理解CSV文件的读写操作。

import csv

# 读取CSV文件
with open('data.csv', 'r', encoding='utf-8') as file:
    reader = csv.reader(file)
    for row in reader:
        print(row)

# 写入CSV文件
data = [
    ['姓名', '年龄', '城市'],
    ['张三', '25', '北京'],
    ['李四', '30', '上海']
]
with open('output.csv', 'w', newline='', encoding='utf-8') as file:
    writer = csv.writer(file)
    writer.writerows(data)

开发环境配置#

Python安装#

下载并安装Python: https://www.python.org/downloads/
确认安装成功:

python --version

虚拟环境#

虚拟环境可以为不同项目创建隔离的Python环境，非常重要。基本上，一个项目就得有一个虚拟环境。非常推荐用PyCharm来作为IDE创建虚拟环境。IDE (Integrated Development Environment) 集成开发环境，用于提供程序开发环境的应用程序，一般包括代码编辑器、编译器、调试器等工具，集成代码编写、分析、编译等功能，是一种一体化的开发软件服务套件。

# 创建虚拟环境
python -m venv sequenzo_env

# 激活虚拟环境
# Windows:
sequenzo_env\Scripts\activate
# Mac/Linux:
source sequenzo_env/bin/activate

# 安装依赖
pip install PyQt5 pandas numpy

包管理#

# 安装包
pip install packagename

# 列出已安装的包
pip list

# 创建requirements.txt
pip freeze > requirements.txt

# 从requirements.txt安装
pip install -r requirements.txt

测试与调试#

打印调试#

# 使用print进行简单调试
print(f"变量值: {variable}")
print("函数被调用，参数:", param1, param2)

异常处理#

try:
    result = some_function()
except Exception as e:
    print(f"发生错误: {e}")
    # 处理错误
else:
    # 没有错误时执行
    print("操作成功")
finally:
    # 无论是否有错误都执行
    print("清理资源")

使用日志#

import logging

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    filename='app.log'
)

# 使用日志
logging.info("程序启动")
logging.error("发生错误")

文档编写#

函数文档#

在编写函数时，添加清晰、规范的文档字符串（docstring）是非常重要的。它不仅能帮助其他开发者快速理解代码的用途和使用方法，也便于后续维护和自动化文档生成工具（如 Sphinx）使用。

我个人非常推荐使用下面这种格式来写函数文档：

def save_figure_to_buffer(fig, dpi: int = 200) -> BytesIO:
    """
    Saves a matplotlib figure to a BytesIO buffer.

    Parameters:
        fig: Matplotlib figure to save
        dpi: Resolution of the output image

    Returns:
        BytesIO: Buffer containing the figure image
    """
    buffer = BytesIO()
    fig.savefig(buffer, format='png', dpi=dpi, bbox_inches='tight')
    plt.close(fig)
    buffer.seek(0)
    return buffer

这个函数的作用是：将一个 Matplotlib 图像对象保存为 PNG 格式，并写入内存中的二进制缓冲区（BytesIO）中，而不是保存为本地文件。

为什么要这样做？在一些应用场景中，比如：

Web 应用：你想将图像发送给前端浏览器，而不是保存在服务器本地；
接口服务：你需要将图像作为二进制数据通过 API 返回；
避免文件系统依赖：有时不方便或不能写入磁盘，比如在云函数、沙箱环境或临时计算中；

这时候，将图像写入 BytesIO 缓冲区就非常有用。

参数说明：

fig: 一个 Matplotlib 的 Figure 对象，也就是你已经绘制好的图；
dpi: 图像的分辨率（每英寸的点数），可以控制输出图片的清晰程度，默认值是 200；

返回值：

返回一个 BytesIO 对象，它就是包含了图像二进制数据的内存缓冲区。你可以把这个缓冲区作为图片数据发送给网络、保存到数据库、上传云端等等。

README文件#

每个项目应该有一个README.md文件，它是项目的门面，这也是为什么你在GitHub每个项目的首页下方都能看到说明文档。这个文档主要说明:

项目是什么
如何安装
如何使用
如何贡献
许可证信息
作者信息

举个例子，请看我和团队做的Sequenzo Python 软件包的官方文档。