CCSDSPy/ccsdspy 项目开发指南

项目概述

CCSDSPy/ccsdspy 是一个用于处理 CCSDS（Consultative Committee for Space Data Systems）数据包的 Python 库。CCDS 是空间数据系统咨询委员会制定的一套标准，广泛应用于航天器遥测和遥控系统中。本项目为开发者提供了处理这类标准化数据包的工具集。

开发环境搭建

安装开发版本

要参与项目开发，首先需要设置本地开发环境：

1. 获取项目源代码
2. 进入项目目录
3. 使用以下命令安装开发依赖：

pip install -e '.[dev]'

如果需要构建文档，还需安装文档依赖：

pip install -e '.[docs]'

这种"可编辑"安装模式允许你在修改代码后立即看到效果，而无需重新安装。

代码规范

语言标准

• 兼容 Python 3.6 及以上版本
• 推荐使用 Python 3 的 f-string 格式化字符串
• 避免使用过时的字符串格式化方式（如 % 操作符）

编码风格

项目遵循 PEP 8 编码规范，特别强调：

• 使用 4 个空格缩进，禁止使用制表符
• 保持文件内现有编码风格的一致性
• 优先使用绝对导入，仅在避免循环导入时使用相对导入
• 遵循常见的导入别名约定：
  • import numpy as np
  • import matplotlib as mpl
  • import matplotlib.pyplot as plt

类设计原则

• 使用属性（property）机制或直接变量访问
• 使用 super() 调用父类方法
• 避免多重继承
• __init__.py 文件应保持简洁，主要用于模块组织

私有代码约定

私有代码（不对外暴露的API）应以下划线开头命名：

• 私有函数/变量：_private_name
• 私有模块：_private_module.py

代码质量保障

代码格式化与检查

项目使用自动化工具保证代码质量：

1. Black：自动格式化代码

   black ccsdspy
   

2. Flake8：静态代码检查

   flake8 ccsdspy --count --select=E9,F63,F7,F82 --show-source --statistics
   

测试要求

• 所有新功能必须包含测试用例
• 使用 pytest 框架编写测试
• 测试文件应放在 tests 目录下
• 测试覆盖率是代码合并的重要指标

文档规范

• 使用美式英语撰写文档
• 所有公共API必须有文档字符串
• 尽可能包含可执行的示例代码
• 推荐使用 doctest 格式的示例，这些示例会被纳入测试范围

版本发布流程

版本号管理

项目遵循语义化版本控制（SemVer），格式为 X.Y.Z：

• X：主版本号（重大变更）
• Y：次版本号（向后兼容的功能新增）
• Z：修订号（向后兼容的问题修正）

使用 setuptools_scm 自动管理版本号，基于 Git 标签生成。

发布新版本步骤

1. 创建 Git 标签：

   git tag -a vX.Y.Z -m "Release version X.Y.Z"
   

2. 构建源代码分发包：

   pip install build
   python -m build --sdist --outdir dist .
   

3. 发布到 PyPI：

   pip install twine
   twine upload dist/ccsdspy*.tar.gz
   

开发建议

1. 保持一致性：在修改现有代码时，遵循文件中原有的编码风格
2. 模块化设计：将通用功能放在 utils.py 中，根据使用范围决定是否公开
3. 测试驱动：先写测试用例，再实现功能
4. 文档同步：代码变更时及时更新相关文档

通过遵循这些开发规范，可以确保项目代码的质量和可维护性，同时也便于其他开发者理解和参与项目贡献。