Metadata-Version: 2.4
Name: EmailWidget
Version: 0.1.0
Summary: 🚀 一个现代化、易用的Python邮件组件库，让你轻松创建美观的HTML邮件报告
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.6
Description-Content-Type: text/markdown

# EmailWidget - 强大的邮件组件库

<div align="center">

**🚀 一个现代化、易用的Python邮件组件库，让你轻松创建美观的HTML邮件报告**

[![PyPI version](https://badge.fury.io/py/EmailWidget.svg)](https://badge.fury.io/py/EmailWidget)
[![Python versions](https://img.shields.io/pypi/pyversions/EmailWidget.svg)](https://pypi.org/project/EmailWidget/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Codecov](https://codecov.io/gh/username/EmailWidget/branch/main/graph/badge.svg)](https://codecov.io/gh/username/EmailWidget)

[📖 文档](https://271374667.github.io/EmailWidget) • [🚀 快速开始](#-快速开始) • [💡 示例](#-组件展示)

</div>

---

## ✨ 为什么选择 EmailWidget？

> **想发警告或者日志到邮箱，但是不会美化，样式太丑？使用 EmailWidget 来打通发送邮件的最后一步！**

EmailWidget 是专为Python开发者设计的邮件组件库，让你用几行代码就能创建出美观的HTML邮件报告而不需要了解HTML的细节。项目经过**500+个测试用例**验证，**核心代码 100% 测试覆盖**, 确保稳定可靠。

### 🎨 **丰富的组件生态** - 12个专业组件

```python
# 一行代码，多种组件
email.add_widget(TextWidget().set_content("标题").set_type(TextType.TITLE_LARGE))
email.add_widget(TableWidget().set_dataframe(df))
email.add_widget(ChartWidget().set_chart(plt))
email.add_widget(ProgressWidget().set_value(85).set_theme(ProgressTheme.SUCCESS))
```

| 🎯 **组件类型** | 📝 **功能特色** | 🔧 **使用场景** |
|---------------|---------------|---------------|
| 📝 **TextWidget** | 8种文本样式、自动编号、章节管理 | 标题、正文、说明文字 |
| 📊 **TableWidget** | DataFrame集成、状态单元格、彩色标记 | 数据表格、统计报表 |
| 📈 **ChartWidget** | matplotlib/seaborn原生支持、自动编码 | 数据可视化、趋势图 |
| 📊 **ProgressWidget** | 5种主题、增减操作、百分比显示 | 任务进度、完成率 |
| ⭕ **CircularProgressWidget** | 圆形进度条、多种尺寸、动态更新 | KPI指标、完成度 |
| 🎴 **CardWidget** | 信息卡片、图标支持、元数据管理 | 摘要信息、状态展示 |
| ⚠️ **AlertWidget** | 5种警告类型、自定义图标、消息提醒 | 通知、警告、提示 |
| 🖼️ **ImageWidget** | 多源支持、尺寸控制、描述文字 | 图片展示、Logo显示 |
| 💬 **QuoteWidget** | 引用样式、作者信息、来源标注 | 引言、评论、摘录 |
| 📊 **StatusWidget** | 状态项管理、布局控制、动态更新 | 系统状态、服务监控 |
| 📑 **ColumnWidget** | 自动/手动列、响应式布局、Widget管理 | 多列布局、内容分组 |
| 📋 **LogWidget** | 日志级别、语法高亮、过滤功能 | 系统日志、运行记录 |


## 🏃‍♂️ 快速开始

### 📦 安装

#### 基础安装（推荐）
```bash
pip install email-widget
```

> 💡 **安装说明**：基础版本仅需jinja2依赖，轻量快速。如果需要TableWidget的DataFrame功能，或者ChartWidget的Matplotlib请自行安装pandas或者matplotlib/seaborn。

### 🎯 30秒创建第一个报告

```python
from email_widget import Email, TextWidget, TableWidget, ProgressWidget
from email_widget.enums import TextType, ProgressTheme
import pandas as pd

# 1️⃣ 创建邮件对象
email = Email("📊 销售数据日报")

# 2️⃣ 添加标题和副标题  
email.set_subtitle("2024年第一季度业绩汇总")
email.set_footer("本报告由数据分析团队自动生成")

# 3️⃣ 添加关键指标
email.add_widget(
    TextWidget()
    .set_content("📈 销售业绩总览")
    .set_type(TextType.TITLE_LARGE)
)

# 4️⃣ 添加进度指标
email.add_widget(
    ProgressWidget()
    .set_value(92)
    .set_label("季度目标完成率")
    .set_theme(ProgressTheme.SUCCESS)
)

# 5️⃣ 添加数据表格
data = [
    ["iPhone 15", "1,250", "¥1,875,000", "125%"],
    ["MacBook Pro", "580", "¥1,740,000", "116%"], 
    ["iPad Air", "920", "¥552,000", "108%"]
]
email.add_table_from_data(
    data=data,
    headers=["产品", "销量", "收入", "达成率"],
    title="🏆 产品销售明细"
)

# 6️⃣ 导出HTML文件
file_path = email.export_html("daily_report.html")
print(f"🎉 报告已生成: {file_path}")
```

![image-20250702215545140](./README.assets/image-20250702215545140.png)

## 🔧 组件展示

下面为目前所有可用控件的展示(部分功能可能未能及时更新，如果出现错误或者不一致的情况请以文档为准)

![image-20250702215350732](./README.assets/image-20250702215350732.png)

## 🎨 高级特性

### 🎯 **链式调用支持**

```python
# 流畅的API设计
email = (Email("项目进展报告")
         .set_subtitle("第一季度总结")
         .set_footer("Generated by EmailWidget")
         .add_widget(TextWidget().set_content("概览").set_type(TextType.TITLE_LARGE))
         .add_widget(ProgressWidget().set_value(78).set_label("整体进度")))
```

## 📚 学习资源

| 📖 **资源类型** | 🔗 **链接** | 📝 **内容** |
|---------------|------------|-----------|
| 🚀 **快速开始** | [安装指南](https://271374667.github.io/SpiderDaily/getting-started/installation/) | 环境配置、第一个邮件 |
| 📘 **用户手册** | [组件详解](https://271374667.github.io/SpiderDaily/user-guide/core-classes/) | 12个组件完整教程 |
| 🔧 **API文档** | [API参考](https://271374667.github.io/SpiderDaily/api/core/) | 完整类和方法文档 |
| 💡 **实战示例** | [应用案例](https://271374667.github.io/SpiderDaily/examples/basic/) | 真实场景代码 |
| 🛠️ **开发指南** | [贡献代码](https://271374667.github.io/SpiderDaily/development/contributing/) | 参与项目开发 |

## 🤝 社区与贡献

### 🌟 **参与开源**

```bash
# 克隆项目
git clone https://github.com/271374667/SpiderDaily.git

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/

# 提交代码
git add .
git commit -m "feat: 添加新功能"
```

### 📞 **联系我们**

- **🐛 问题反馈**: [GitHub Issues](https://github.com/271374667/EmailWidget/issues)
- **💬 讨论交流**: [GitHub Discussions](https://github.com/271374667/EmailWidget/discussions)
- **📧 邮件联系**: 271374667@qq.com
- **📺 视频教程**: [Bilibili频道](https://space.bilibili.com/282527875)

## 📄 许可证

本项目采用 [MIT License](https://opensource.org/licenses/MIT) 开源协议。

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给我们一个Star！ ⭐**

Made with ❤️ by [Python调包侠](https://github.com/271374667) | [观看教程](https://space.bilibili.com/282527875) | [查看文档](https://271374667.github.io/SpiderDaily/)

</div>
