Metadata-Version: 2.4
Name: mxboxutils
Version: 0.1.6
Summary: An utils collection for python called MxBoxUtils
Author-email: RyanLu <lyydev@qq.com>
License: MIT License
        
        Copyright (c) 2025 Ryan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://gitee.com/RyanLuDev/MxBoxUtils
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# MxBoxUtils

MxBoxUtils 是一个 Python 工具库，提供了文件操作、TOML 配置解析等实用功能，专注于提高开发效率和代码复用性。

## 目录结构

```
MxBoxUtils/
├── src/
│   └── mxboxutils/      # 核心功能模块
│       ├── __init__.py  # 包初始化文件
│       ├── file.py      # 文件操作工具
│       └── toml.py      # TOML 配置文件解析工具
├── tests/               # 测试文件目录
│   └── test_mxboxutils.py  # 单元测试文件
├── LICENSE              # 许可证文件
├── pyproject.toml       # 项目配置文件
└── README.md            # 项目说明文档
```

## 功能模块

### 1. 文件操作 (file.py)

提供丰富的文件和目录操作功能，包括文件查找、路径处理、哈希计算等。

#### files(f_path: str, f_ext: list[str]) -> list[str]
列出指定目录下的所有指定扩展名的文件名（不包含路径）。
- **参数**: 
  - `f_path` - 要搜索的目录路径
  - `f_ext` - 要匹配的文件扩展名列表（不包含点号）
- **返回值**: 匹配的文件名列表

#### file_paths(f_path: str, f_ext: list[str]) -> list[str]
获取指定目录下所有指定扩展名的文件的完整路径。
- **参数**: 
  - `f_path` - 要搜索的目录路径
  - `f_ext` - 要匹配的文件扩展名列表
- **返回值**: 完整文件路径列表

#### imgs(f_path: str, f_ext: list[str] = IMG_TYPE) -> list[str]
列出指定目录下的所有图像文件（默认支持 jpg、jpeg、png）。
- **参数**: 
  - `f_path` - 要搜索的目录路径
  - `f_ext` - 要匹配的图像文件扩展名（可选）
- **返回值**: 图像文件名列表

#### img_paths(f_path: str, f_ext: list[str] = IMG_TYPE) -> list[str]
获取指定目录下所有图像文件的完整路径。
- **参数**: 
  - `f_path` - 要搜索的目录路径
  - `f_ext` - 要匹配的图像文件扩展名（可选）
- **返回值**: 图像文件完整路径列表

#### file_hash(file_path: str, hash_type: str) -> str
计算文件的哈希值（支持 SHA256 和 MD5）。
- **参数**: 
  - `file_path` - 要计算哈希值的文件路径
  - `hash_type` - 哈希算法类型，支持 "SHA256" 或 "MD5"
- **返回值**: 计算后的哈希字符串

### 2. TOML 配置解析 (toml.py)

提供简洁的 TOML 配置文件解析功能，便于加载和管理配置数据。

#### load_toml(filepath)
加载并解析 TOML 配置文件。
- **参数**: 
  - `filepath` - TOML 文件的完整路径
- **返回值**: 解析后的配置数据字典，如果文件不存在则返回 None

## 安装说明

```bash
# 从源代码安装
pip install -e .

# 安装开发依赖（包括 pytest）
pip install -e .[dev]
```

## 使用示例

### 文件操作示例

```python
from mxboxutils.file import files, file_paths, file_hash

# 查找所有 Python 文件
py_files = files("/path/to/code", ["py"])
print(f"找到 {len(py_files)} 个 Python 文件")

# 获取文件完整路径
py_file_paths = file_paths("/path/to/code", ["py"])

# 计算文件 SHA256 哈希
file_sha256 = file_hash("/path/to/file", "SHA256")
```

### TOML 配置解析示例

```python
from mxboxutils.toml import load_toml

config = load_toml("config.toml")
if config:
    print(f"配置加载成功: {config}")
```

## 测试

项目已集成完整的单元测试，确保所有功能正常工作。

```bash
# 运行所有测试
python -m pytest tests/test_mxboxutils.py -v
```

## 版本信息

当前版本: 0.1.6

## 系统要求

- Python 3.9 或更高版本（推荐 3.12+）

## 依赖

- 标准库，无需额外依赖
- **可选依赖** (dev): pytest, setuptools, twine, build

## 开发

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

## 许可证

MIT License
