hagike 0.0.3

hagike toolkit for everything

hagike

hagike是一个用于开发与部署的通用套件，由hagikehappy开发。

基本思想

为什么要创建这样的一个框架？事实上，在这样一个计算机蓬勃发展的时代，网上公开的包是很多的，那我们是不是就不需要一套软件基础设施了？基于以下几点观察，其实并不是：

1. 公开的包往往都是对某个子功能的实现与封装，但缺乏一套适用于一般研究者与部署者的通用框架。
2. 包存在那里，不意味着你就能用得上。由于不同人研究的领域、方向和需求不同，所以网上的包，或者聚焦于某个已经高度成熟的领域，或者极其广泛而通用，恰好匹配个人使用习惯的包是很难存在的。用强化学习来类比，作为不同智能体，状态空间的访问性，是不同的。例如，网上的包，往往能够覆盖各种情况，但这也导致了配置上是高度繁琐的，如果你能够把这些功能进一步封装为你常用的子功能，那么使用效率将会大大提升。
3. 很多时候存在这样一种情况，你在各个项目或任务中所写的代码，是不可积累的。例如，你每接触一个新的项目，都开一份新的代码。那么有没有办法将这些代码积累起来？如果可以做到的话，那么随着时间的增长，你的软件基础设施将趋于完善，这会给你带来效率上的巨大提升。
4. 为了使得代码可积累，那么在编程方式、思路、通用性等各方面都需要一个彻底的转变。与其说，这是一个框架，不如说，这是一个标准，或者规范，用于将各场景下的代码集合起来。
5. 本框架中的内容是作者在各种任务与项目中逐步添加的，因此与作者的使用频率和使用习惯是最相符的。如果你希望应用这个框架，你可能需要阅读框架中包含的文档（下面有专门部分会做进一步说明）。以及，你可以根据自己的需求和状态分布在此基础上逐渐丰富这个框架，打造一套符合你自己使用习惯和频率的软件基础设施。
6. 如上所说，本框架的目标并不是弃用网上的已经非常成熟的包。而是寻找一种方式，将各个包集合在一起，并进行二次封装，定义各个包空间到框架空间的接口规范，以便各种灵活的应用。同时，抽取出包中的常用功能，以提升使用效率。
7. 本框架使用MIT开源协议。这意味着，你可以自由使用，但是必须保障原作者的著名权。即，在转发或使用时注明框架原作者，在论文中的参考文献部分注明框架作者的贡献。

框架构成

其内容包括以下几个子包，这里仅举例部分，具体内容要看document.html文档：

1. utils: 通用工具，如常量表等
2. tools: 辅助工具，包括画图、基本图形化界面、分析工具等
3. system: 任务级并行运算系统
   1. interface: 调用系统内核的接口模板
   2. core: 系统内核
4. basics: 基本算法库
   1. cv: 计算机视觉类
   2. ml: 机器学习类
5. models: 模型套件
   1. cv: 计算机视觉类模型
   2. nlp: 自然语言处理类模型
   3. rl: 强化学习类模型
   4. template: 通用模型模板
   5. train: 训练与评估模板
   6. deploy: 部署模板
6. log: 日志系统，由于日志的重要性与特殊性，这里单独将其从utils中抽出，单独列为一个子模块

编写规范

文档规范

为了保障代码的可开发性、可阅读性、可使用性与可迁移性，本框架下的代码遵循以下模板说明：

1. 所有python文件的开头都有注释，会对该文件的总体情况进行说明
2. __init__.py文件开头的说明是对该子包的总体说明
3. 代码强制要求进行类型标注
4. 代码中的各功能子模块都会有注释进行简单或复杂的说明

代码内文档的书写需要满足一定的规范，框架应配置文档自动生成工具，可以自动提取代码内的注释并组织成文档。

对于复杂的逻辑系统（如系统内核），还需要配备.drawio格式的UML图来辅助说明。

异常处理

代码中会存在异常检查项，在一般情况下没有外置try-except语句，因此如果需要使用日志系统记录异常或在存在异常的情况下依然使代码尽最大程度正常运行，则需要使用自行添加外置结构。

例外在于系统内核中，为了保证系统运行的稳定性，在除了Panic（内核恐慌）中会直接崩溃，否则会有适当的错误处理代码，至少保障日志系统可以保存工作状态用于后续分析或状态还原。

异常检查的存在是为了填补那些存在某类逻辑错误但不会导致代码立刻崩溃的情况而实现的手动发起崩溃。这是为了保障错误能够被正确定位并及时修复。

测试规范

对于每个文件中的核心功能，需要配备测试程序。其用途如下：

1. 增加代码本身的置信度
2. 便于作者测试代码运行是否正常
3. 可以提供使用样板供使用者参考
4. 可以在版本更新造成接口不匹配的情况下及时发现

测试的编写需要满足一定规范，最好可以被pytest等自动化工具执行