# MWJ Tools - 实用的Python工具库

MWJ Tools是一个实用的Python工具库，提供了丰富的工具类来简化日常开发任务。目前包含日期时间处理和表格数据处理两大核心功能模块。

## 安装

```bash
uv add mwj_tools
```

## 功能特性

### 1. 日期时间处理工具 (DateTimeUtils)

提供时间计算、转换、格式化等常用功能：

- 获取当前时间
- 时间加减计算（支持天、小时、分钟、月份）
- 时间戳转换
- 计算时间差
- 计算未来日期
- 时间格式化
- 周末判断
- 获取周范围

#### 使用示例

```python
from mwj_tools import DateTimeUtils

# 获取当前时间
current_time = DateTimeUtils.now()
formatted_time = DateTimeUtils.now('%Y-%m-%d %H:%M:%S')

# 时间加减计算
future_time = DateTimeUtils.add_time(days=5, hours=3)
past_time = DateTimeUtils.add_time(months=-2)

# 时间戳转换
timestamp = DateTimeUtils.to_timestamp()
dt_from_timestamp = DateTimeUtils.from_timestamp(timestamp)

# 计算时间差
diff = DateTimeUtils.time_difference('2025-01-01', unit='days')

# 获取未来日期
future_date = DateTimeUtils.future_date(30)

# 格式化时间
formatted = DateTimeUtils.format_time('2025-07-15 10:30:00', '%Y年%m月%d日')

# 判断是否为周末
is_weekend = DateTimeUtils.is_weekend()

# 获取周范围
week_range = DateTimeUtils.get_week_range()
```

### 2. 表格数据处理工具 (TableUtils)

提供数据读取、清洗、转换、分析等常用功能：

- 读取多种格式表格文件（CSV、Excel、JSON）
- 保存表格到文件
- 数据筛选
- 数据分组聚合
- 表格合并
- 数据清洗（处理缺失值）
- 生成数据描述统计
- 创建数据透视表

#### 使用示例

```python
from mwj_tools import TableUtils
import pandas as pd

# 读取表格文件
df = TableUtils.read_table('data.csv')  # 自动识别格式
df = TableUtils.read_table('data.xlsx', file_type='excel')

# 保存表格文件
TableUtils.save_table(df, 'output.csv')

# 数据筛选
filtered_df = TableUtils.filter_data(df, {
    'age': ('>=', 18),
    'city': 'Beijing',
    'name': ('contains', 'John')
})

# 数据聚合
aggregated_df = TableUtils.aggregate_data(df, 
    group_by=['department'], 
    aggregations={'salary': ['mean', 'sum'], 'age': 'max'}
)

# 表格合并
merged_df = TableUtils.merge_tables(df1, df2, on='id', how='left')

# 数据清洗
cleaned_df = TableUtils.clean_data(df, strategy='fill', fill_value=0)

# 生成数据描述统计
stats = TableUtils.describe_data(df)

# 创建数据透视表
pivot_df = TableUtils.pivot_table(df, 
    index='category', 
    columns='month', 
    values='sales', 
    aggfunc='sum'
)
```

## 项目结构

```
mwj_tools/
├── src/
│   └── mwj_tools/
│       ├── __init__.py
│       ├── datetime_utils.py      # 日期时间处理工具
│       └── table_utils.py         # 表格数据处理工具
├── tests/
│   ├── test_datetime_utils.py
│   └── test_table_utils.py
├── examples/
│   ├── datetime_example.py
│   └── table_example.py
├── README.md
└── pyproject.toml
```

## 开发与测试

### 运行测试

```bash
# 运行所有测试
uv run pytest tests/

# 运行特定模块测试
uv run pytest tests/test_datetime_utils.py
uv run pytest tests/test_table_utils.py
```

### 示例代码

查看 `examples/` 目录获取更多使用示例。

## 依赖

- python >= 3.13
- openpyxl
- pandas
- python-dateutil

## 作者

- **梦无矶** - *Lvan826199@163.com*

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进此项目。