Metadata-Version: 2.4
Name: brief-excel
Version: 1.0.1
Summary: 一个简洁的Excel处理工具包
Author-email: hh66dw <hh66dw@163.com>
License: MIT License
        
        Copyright (c) 2025 hh66dw
        
        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: Homepage, https://gitee.com/hh66dw/brief_excel
Project-URL: Documentation, https://gitee.com/hh66dw/brief_excel#readme
Project-URL: Repository, https://gitee.com/hh66dw/brief_excel
Project-URL: Issues, https://gitee.com/hh66dw/brief_excel/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl==3.1.5
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Dynamic: license-file

# brief-excel

一个简洁的Excel处理工具包，提供简洁的API用于创建、读取、编辑Excel文件，支持工作表管理、单元格操作、图片插入等功能。

## 📋 目录
- [特性](#特性)
- [快速开始](#快速开始)
  - [前提条件](#前提条件)
  - [安装](#安装)
- [使用指南](#使用指南)
- [API 文档](#api-文档)
- [开发](#开发)
- [贡献指南](#贡献指南)
- [许可证](#许可证)
- [联系方式](#联系方式)

## ✨ 特性
- **简洁的API设计**：链式调用，代码清晰易读
- **完整的工作表管理**：创建、复制、移动、删除工作表
- **灵活的单元格操作**：支持单个单元格、整行、整列、区域数据的读写
- **图片插入功能**：支持在单元格中插入图片，可调整大小和位置
- **错误处理**：详细的异常信息，便于调试
- **数据缓冲区**：提供临时数据存储，方便数据传递

## 🚀 快速开始
### 前提条件
- Python 3.7 或更高版本
- 基本的Python编程知识

### 安装
#### 从PyPI安装（推荐）
```bash
pip install brief_excel
```

#### 从源码安装
```bash
git clone https://gitee.com/hh66dw/brief_excel.git
cd brief_excel
pip install -e .
```

## 📖 使用指南
### 基本用法
```python
from brief_excel import BriefExcel

# 创建Excel文件
excel = BriefExcel("example").create()

# 添加工作表
excel.ws_append("新工作表", 2)

# 定位到第一个工作表
excel.ws_location(1)

# 写入数据到单元格
excel.cell_write(1, 1, "Hello, World!")

# 写入整行数据
excel.cell_row_write(2, 1, ["A", "B", "C", "D"])

# 保存文件
excel.save()
```

### 高级用法
```python
from brief_excel import BriefExcel

# 加载现有Excel文件
excel = BriefExcel().load("existing_file")

# 复制工作表
excel.ws_location("Sheet1").ws_copy()

# 移动工作表
excel.ws_move(3)

# 读取区域数据
data = excel.cell_area_read(1, 1, 5, 3).info()
print(data)

# 插入图片
excel.insert_pic(1, 1, "test_images/red_square_100x100.png", 100, 100)

# 保存修改
excel.save()
```

## 📚 API 文档
### 主要类
#### `BriefExcel`
主要的Excel操作类。

##### `__init__(name: str = None)`
初始化BriefExcel实例。

##### `set_name(name: str) -> BriefExcel`
设置Excel文件名。

##### `create() -> BriefExcel`
创建新的Excel文件。

##### `load(fpn: str = None) -> BriefExcel`
加载现有的Excel文件。

##### `save(fpn: str = None)`
保存Excel文件。

##### `ws_append(name: str = 'Sheet', num: int = 1) -> BriefExcel`
添加工作表。

##### `ws_location(title_or_num: str | int, debug = True) -> BriefExcel`
定位到指定工作表。

##### `ws_move(index: int, title_or_num: str | int = None) -> BriefExcel`
移动当前工作表位置。

##### `ws_copy(title_or_num: str | int = None) -> BriefExcel`
复制工作表。

##### `ws_delete(title_or_num: str | int = None) -> BriefExcel`
删除当前工作表。

##### `cell_location(row: int, col: int = 0, debug = True) -> BriefExcel`
定位到指定单元格。

##### `cell_write(row: int = 0, col: int = 0, data: str = None, debug = True) -> BriefExcel`
写入单个单元格数据。

##### `cell_row_write(row: int, col: int = 1, datas: list = None, debug = True) -> BriefExcel`
写入整行数据。

##### `cell_row_read(row: int, col_start = 1, col_end = 1) -> BriefExcel`
读取整行数据。

##### `cell_col_write(row: int = 1, col: int = 1, datas: list = None) -> BriefExcel`
写入整列数据。

##### `cell_col_read(col: int = 0, row_start = 1, row_end = 1) -> BriefExcel`
读取整列数据。

##### `cell_area_write(row: int, col: int = 1, datas: list[list] = None) -> BriefExcel`
写入区域数据。

##### `cell_area_read(row_start: int = 0, col_start: int = 0, row_end = 0, col_end = 0) -> BriefExcel`
读取区域数据。

##### `insert_pic(row: int, col: int = 0, path: str = None, width: int = 720, height: int = 1280, width_scale: float = 0.14, height_scale: float = 0.78, width_min: float = 8.43, height_min: float = 15, debug = True) -> BriefExcel`
插入单张图片。

##### `insert_pic_row(row: int, col: int = 0, paths: str = None, width: int = 720, height: int = 1280)`
以行插入图片。

##### `insert_pic_col(row: int = 0, col: int = 1, paths: str = None, width: int = 720, height: int = 1280)`
以列插入图片。

## 💻 开发
### 项目结构
```
brief_excel/
├── src/
│   └── brief_excel/
│       ├── __init__.py
│       └── module.py
├── tests/
│   ├── test.py
│   └── test_images/
├── pyproject.toml
├── requirements.txt
├── README.md
└── LICENSE
```

## 🤝 贡献指南
我们欢迎各种形式的贡献，包括但不限于代码、文档、测试用例、问题报告和功能建议。

1. **Fork 本仓库**
2. **创建特性分支** (`git checkout -b feature/AmazingFeature`)
3. **提交更改** (`git commit -m 'Add some AmazingFeature'`)
4. **推送到分支** (`git push origin feature/AmazingFeature`)
5. **开启 Pull Request**

请确保代码风格一致，并通过所有测试。

## 📄 许可证
本项目基于 MIT 许可证发行。详情请参阅 [LICENSE](LICENSE) 文件。

## 📞 联系方式
- **项目维护者**: [hh66dw](https://gitee.com/hh66dw)
- **邮箱**: hh66dw@163.com
- **项目链接**: https://gitee.com/hh66dw/brief_excel
- **问题反馈**: https://gitee.com/hh66dw/brief_excel/issues

---

**如果这个项目对您有帮助，请给个 ⭐️ 星标支持！**
