# Module : log
> **Coder** : ASH   
> **Last Update** : 2026-7-22-22:56     
> **Contact** : yore159357@163.com  
> **Version** : 0.0.1

---

## Features : 功能特性

### 核心功能
1. **自动日志记录** - 自动记录事件发生的时间（相对于模块启动）
2. **多级别日志** - 支持 `debug`、`info`、`warn`、`error`、`fatal` 五个标准日志级别
3. **自定义事件类型** - 允许为日志事件添加自定义类型标签
4. **自动文件管理** - 自动创建日志目录和日志文件
5. **日志解析** - 提供日志文件解析和统计分析功能
6. **日志转换** - 支持将解析后的日志重新写入日志文件

### 日志级别
- `debug` - 调试信息
- `info` - 一般信息
- `warn` - 警告信息
- `error` - 错误信息
- `fatal` - 致命错误

---

## Default Parameter : 默认参数
`st`:在您的程序导入时，会自动将导入的时间记作系统时，如果需要中途调用，请用赋值语句:`log.st = [您所想更改的时间]`

`defult_log_file_dir`:默认的日志文件存放目录，未修改时，默认路径为`./logs`

---

## Function Declaration : 函数说明

### `log(event_content,level = 'debug',type = 'event',event_time = None)`
> ASH:这是主要的日志记录函数，也是模块的核心

#### 参数

- `event_content` (`str`) : 日志事件内容描述

- `level` (`str`, `optional`) : 日志级别，默认为 'debug'

- `type` (`str`, `optional`) : 事件类型，默认为 'event'

- `event_time` (`float`, `optional`) : 自定义事件时间戳，默认为 None（使用当前时间）
#### 功能

记录事件到日志文件并自动计算相对启动时间的时间戳，格式为：

```[相对时间][级别][类型][内容]```

#### 示例
```py
log('程序启动')                    # 默认debug级别
log('用户登录成功', level='info')   # info级别
log('磁盘空间不足', level='warn', type='system')
log('初始化完成', event_time=time.time())
```
---

### `trans_log(log_list)`
> ASH:日志转换函数,没啥大用

#### 参数

`log_list` (`list`) : 写有固定格式的日志内容的列表

#### 功能

1. 解析标准格式的日志行

2. 将解析后的日志重新写入当前日志文件

3. 保持时间戳相对性

#### 提示
##### 1.传入的列表的格式
对于传入函数的列表，有以下格式要求:
```js
[
    "事件1伪日志",
    "事件2伪日志",
    ...
]
```
对于每一条伪日志，结构要求为:
```js
"[绝对时间][级别][类型][内容]"
```
##### 2.绝对时间与相对时间
本函数要求传入的伪日志内容要求时间为绝对时间（Unix时间戳）而非日志记录文件内的相对时间

---

### `read_log_files()`
>ASH:这个函数可以读取对应路径的日志文件,并返回相应的事件类型计数
该函数返回值(dict)的结构如下:
```js
{
    'file_name':'文件名称.log',
    'file_path':'文件路径',
    'event_num':{
        'debug':debug_number,
        'info':info_number,
        'warn':warn_number,
        'error':error_number,
        'fatal':fatal_number
    },
    'normal_exit':True
    'end_event':event
}
```
#### 参数说明

- `'event_num'` : 不同重要程度的事件类型的计数的字典,其值为`int`型.

- `'normal_exit'` : 对应程序退出是否正常的布尔值

- `'end_event'` : 表示结束事件的类型

在调用该函数时,请确保读取文件在模组默认所在的目录内,并使用以下语句
```py
from Modules import log
read_result = log.read_log_file(files_path)
print(read_result)
```
最终输出结果可能同上