xp3-tool 5.0__tar.gz → 5.1__tar.gz

xp3_tool-5.1/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.1
+Name: xp3_tool
+Version: 5.1
+Summary: xp_t3_tool
+Home-page: 
+Author: XuPeng
+Author-email: xupeng23456@126.com
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10.0
+Description-Content-Type: text/markdown
+Requires-Dist: openai
+Requires-Dist: pandas
+Requires-Dist: oss2
+Requires-Dist: python-dotenv
+
+
+# Excel 与 OSS 处理工具库
+
+这是一个集成了 OpenAI API 调用、阿里云 OSS 文件管理和 Excel 数据处理功能的 Python 工具库。
+
+## 功能特性
+
+### 🤖 AI 对话功能 (CallAi 类)
+- 支持 OpenAI 兼容的 API 调用
+- 可自定义系统提示词和模型参数
+- 灵活的对话配置（temperature、top_p）
+
+### ☁️ OSS 文件管理 (ExcelOSSHandler 类)
+- Excel 文件上传到阿里云 OSS
+- 从 OSS 下载 Excel 文件并转换为 pandas DataFrame
+- 支持环境变量自动配置
+- 完整的错误处理和文件验证
+
+### 📧 数据导出与邮件发送 (ExportToEmail 函数)
+- 将 DataFrame 导出为 Excel 文件
+- 自动通过邮件发送 Excel 附件
+- 支持 HTML 格式的邮件内容
+- 自动清理临时文件
+
+## 安装依赖
+
+```bash
+pip install openai pandas oss2 python-dotenv openpyxl
+```
+
+## 快速开始
+
+### 1. 环境配置
+
+创建 `.env` 文件配置敏感信息：
+
+```env
+# OpenAI 配置
+OPENAI_API_KEY=your-openai-api-key
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# 阿里云 OSS 配置
+access_key_id=your-access-key-id
+access_key_secret=your-access-key-secret
+endpoint=oss-cn-hangzhou.aliyuncs.com
+bucket_name=your-bucket-name
+
+# 邮件配置
+email_sender=your-email@163.com
+email_password=your-email-authorization-code
+```
+
+### 2. AI 对话功能
+
+```python
+from your_module import CallAi
+
+# 初始化 AI 客户端
+ai = CallAi(
+    api_key="your-api-key",
+    base_url="https://api.openai.com/v1",
+    model="qwen-plus"  # 默认模型
+)
+
+# 设置系统提示词
+ai.prompt = "你是一个有用的助手"
+
+# 进行对话
+response = ai.chat("你好，请介绍一下自己")
+print(response)
+```
+
+### 3. OSS 文件管理（支持环境变量自动加载）
+
+```python
+from your_module import ExcelOSSHandler
+
+# 方式1：使用环境变量自动配置
+oss_handler = ExcelOSSHandler()  # 自动从 .env 文件读取配置
+
+# 方式2：手动传入配置
+oss_handler = ExcelOSSHandler(
+    access_key_id="your-access-key-id",
+    access_key_secret="your-access-key-secret",
+    endpoint="https://oss-cn-hangzhou.aliyuncs.com",
+    bucket_name="your-bucket-name"
+)
+
+# 上传 Excel 文件到 OSS
+success = oss_handler.upload_excel_to_oss(
+    local_file_path="local_file.xlsx",
+    oss_file_path="oss/path/file.xlsx"
+)
+
+# 从 OSS 下载 Excel 并转换为 DataFrame
+df = oss_handler.get_excel_from_oss("oss/path/file.xlsx")
+```
+
+### 4. 数据导出与邮件发送
+
+```python
+from your_module import ExportToEmail
+import pandas as pd
+
+# 创建示例数据
+df = pd.DataFrame({
+    'Name': ['Alice', 'Bob', 'Charlie'],
+    'Age': [25, 30, 35],
+    'City': ['Beijing', 'Shanghai', 'Guangzhou']
+})
+
+# 方式1：使用环境变量自动配置邮件
+result = ExportToEmail(
+    df=df,
+    receiver="recipient@example.com",
+    subject="数据导出报告"
+)
+
+# 方式2：手动配置邮件
+result = ExportToEmail(
+    df=df,
+    receiver="recipient@example.com",
+    subject="数据导出报告",
+    sender="your-email@163.com",
+    password="your-email-password"
+)
+
+print(result)
+```
+
+## API 参考
+
+### CallAi 类
+
+#### 初始化参数
+- `api_key`: OpenAI API 密钥
+- `base_url`: API 基础地址
+- `model`: 模型名称（默认：'qwen-plus'）
+
+#### 属性
+- `prompt`: 系统提示词（可读写属性）
+
+#### 方法
+- `chat(text, top_p=0.9, temperature=0.7)`: 发送对话请求
+
+### ExcelOSSHandler 类
+
+#### 初始化参数
+所有参数都是可选的，如果不提供会自动从环境变量读取：
+- `access_key_id`: 阿里云访问密钥 ID
+- `access_key_secret`: 阿里云访问密钥 Secret
+- `endpoint`: OSS 服务端点
+- `bucket_name`: 存储桶名称
+
+#### 方法
+- `upload_excel_to_oss(local_file_path, oss_file_path)`: 上传 Excel 文件到 OSS
+- `get_excel_from_oss(oss_file_path)`: 从 OSS 下载 Excel 文件并转换为 DataFrame
+
+### ExportToEmail 函数
+
+#### 参数
+- `df`: 要导出的 pandas DataFrame（必需）
+- `receiver`: 收件人邮箱地址（默认：'xupeng23456@126.com'）
+- `subject`: 邮件主题（可选，自动生成时间戳）
+- `sender`: 发件人邮箱（可选，从环境变量读取）
+- `password`: 发件人邮箱密码/授权码（可选，从环境变量读取）
+
+#### 返回值
+返回包含操作结果的字典：
+```python
+{
+    "status": "success" | "failed",
+    "message": "描述信息",
+    "file_path": "临时文件路径",
+    "email_sent": True | False,
+    "row_count": 数据行数,
+    "timestamp": "时间戳"
+}
+```
+
+### 工具函数
+- `uuid(length=16)`: 生成随机字符串 ID
+
+## 使用示例
+
+### 完整工作流程示例
+
+```python
+from your_module import CallAi, ExcelOSSHandler, ExportToEmail
+import pandas as pd
+
+# 1. 使用 AI 生成数据建议
+ai = CallAi(api_key="your-key", base_url="your-url")
+ai.prompt = "你是一个数据分析专家"
+analysis = ai.chat("分析销售数据时应该关注哪些指标？")
+
+# 2. 从 OSS 获取数据
+oss_handler = ExcelOSSHandler()  # 自动使用环境变量
+df = oss_handler.get_excel_from_oss("sales/data.xlsx")
+
+# 3. 处理数据
+processed_df = df.groupby('category').sum()
+
+# 4. 导出并发送邮件
+result = ExportToEmail(
+    df=processed_df,
+    receiver="team@company.com",
+    subject="销售数据汇总报告"
+)
+
+print(f"操作结果: {result['status']}")
+print(f"发送状态: {'成功' if result['email_sent'] else '失败'}")
+```
+
+## 错误处理
+
+所有函数都包含完整的异常处理，会返回详细的错误信息：
+
+```python
+# 检查操作结果
+result = oss_handler.upload_excel_to_oss("nonexistent.xlsx", "oss/path/file.xlsx")
+if not result:
+    print("文件上传失败")
+
+# 检查邮件发送结果
+email_result = ExportToEmail(df, "receiver@example.com")
+if email_result["status"] == "failed":
+    print(f"发送失败: {email_result['message']}")
+```
+
+## 注意事项
+
+1. **文件格式**: 仅支持 `.xlsx` 和 `.xls` 格式的 Excel 文件
+2. **邮件服务**: 默认使用 163 邮箱的 SMTP 服务（端口 465，SSL）
+3. **临时文件**: 自动创建 `./temp` 目录存放临时文件，邮件发送成功后自动清理
+4. **环境变量**: 建议使用 `.env` 文件管理敏感信息，不要将密钥硬编码在代码中
+
+## 故障排除
+
+### 常见问题
+
+**OSS 连接问题**:
+- 检查 Access Key 和 Secret 是否正确
+- 确认 endpoint 格式正确（包含 http/https）
+- 验证 bucket 名称和权限
+
+**邮件发送失败**:
+- 确认邮箱密码是授权码而非登录密码
+- 检查发件人邮箱是否开启 SMTP 服务
+- 验证网络连接和防火墙设置
+
+**Excel 文件处理错误**:
+- 确认文件没有被其他程序占用
+- 检查 pandas 和 openpyxl 版本兼容性
+- 验证文件内容格式正确
+
+## 更新日志
+
+### v1.1.0
+- 新增环境变量自动加载功能
+- 改进错误处理和日志输出
+- 优化邮件发送逻辑
+
+## 许可证
+
+MIT License

xp3_tool-5.1/README.md

@@ -0,0 +1,265 @@
+# Excel 与 OSS 处理工具库
+
+这是一个集成了 OpenAI API 调用、阿里云 OSS 文件管理和 Excel 数据处理功能的 Python 工具库。
+
+## 功能特性
+
+### 🤖 AI 对话功能 (CallAi 类)
+- 支持 OpenAI 兼容的 API 调用
+- 可自定义系统提示词和模型参数
+- 灵活的对话配置（temperature、top_p）
+
+### ☁️ OSS 文件管理 (ExcelOSSHandler 类)
+- Excel 文件上传到阿里云 OSS
+- 从 OSS 下载 Excel 文件并转换为 pandas DataFrame
+- 支持环境变量自动配置
+- 完整的错误处理和文件验证
+
+### 📧 数据导出与邮件发送 (ExportToEmail 函数)
+- 将 DataFrame 导出为 Excel 文件
+- 自动通过邮件发送 Excel 附件
+- 支持 HTML 格式的邮件内容
+- 自动清理临时文件
+
+## 安装依赖
+
+```bash
+pip install openai pandas oss2 python-dotenv openpyxl
+```
+
+## 快速开始
+
+### 1. 环境配置
+
+创建 `.env` 文件配置敏感信息：
+
+```env
+# OpenAI 配置
+OPENAI_API_KEY=your-openai-api-key
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# 阿里云 OSS 配置
+access_key_id=your-access-key-id
+access_key_secret=your-access-key-secret
+endpoint=oss-cn-hangzhou.aliyuncs.com
+bucket_name=your-bucket-name
+
+# 邮件配置
+email_sender=your-email@163.com
+email_password=your-email-authorization-code
+```
+
+### 2. AI 对话功能
+
+```python
+from your_module import CallAi
+
+# 初始化 AI 客户端
+ai = CallAi(
+    api_key="your-api-key",
+    base_url="https://api.openai.com/v1",
+    model="qwen-plus"  # 默认模型
+)
+
+# 设置系统提示词
+ai.prompt = "你是一个有用的助手"
+
+# 进行对话
+response = ai.chat("你好，请介绍一下自己")
+print(response)
+```
+
+### 3. OSS 文件管理（支持环境变量自动加载）
+
+```python
+from your_module import ExcelOSSHandler
+
+# 方式1：使用环境变量自动配置
+oss_handler = ExcelOSSHandler()  # 自动从 .env 文件读取配置
+
+# 方式2：手动传入配置
+oss_handler = ExcelOSSHandler(
+    access_key_id="your-access-key-id",
+    access_key_secret="your-access-key-secret",
+    endpoint="https://oss-cn-hangzhou.aliyuncs.com",
+    bucket_name="your-bucket-name"
+)
+
+# 上传 Excel 文件到 OSS
+success = oss_handler.upload_excel_to_oss(
+    local_file_path="local_file.xlsx",
+    oss_file_path="oss/path/file.xlsx"
+)
+
+# 从 OSS 下载 Excel 并转换为 DataFrame
+df = oss_handler.get_excel_from_oss("oss/path/file.xlsx")
+```
+
+### 4. 数据导出与邮件发送
+
+```python
+from your_module import ExportToEmail
+import pandas as pd
+
+# 创建示例数据
+df = pd.DataFrame({
+    'Name': ['Alice', 'Bob', 'Charlie'],
+    'Age': [25, 30, 35],
+    'City': ['Beijing', 'Shanghai', 'Guangzhou']
+})
+
+# 方式1：使用环境变量自动配置邮件
+result = ExportToEmail(
+    df=df,
+    receiver="recipient@example.com",
+    subject="数据导出报告"
+)
+
+# 方式2：手动配置邮件
+result = ExportToEmail(
+    df=df,
+    receiver="recipient@example.com",
+    subject="数据导出报告",
+    sender="your-email@163.com",
+    password="your-email-password"
+)
+
+print(result)
+```
+
+## API 参考
+
+### CallAi 类
+
+#### 初始化参数
+- `api_key`: OpenAI API 密钥
+- `base_url`: API 基础地址
+- `model`: 模型名称（默认：'qwen-plus'）
+
+#### 属性
+- `prompt`: 系统提示词（可读写属性）
+
+#### 方法
+- `chat(text, top_p=0.9, temperature=0.7)`: 发送对话请求
+
+### ExcelOSSHandler 类
+
+#### 初始化参数
+所有参数都是可选的，如果不提供会自动从环境变量读取：
+- `access_key_id`: 阿里云访问密钥 ID
+- `access_key_secret`: 阿里云访问密钥 Secret
+- `endpoint`: OSS 服务端点
+- `bucket_name`: 存储桶名称
+
+#### 方法
+- `upload_excel_to_oss(local_file_path, oss_file_path)`: 上传 Excel 文件到 OSS
+- `get_excel_from_oss(oss_file_path)`: 从 OSS 下载 Excel 文件并转换为 DataFrame
+
+### ExportToEmail 函数
+
+#### 参数
+- `df`: 要导出的 pandas DataFrame（必需）
+- `receiver`: 收件人邮箱地址（默认：'xupeng23456@126.com'）
+- `subject`: 邮件主题（可选，自动生成时间戳）
+- `sender`: 发件人邮箱（可选，从环境变量读取）
+- `password`: 发件人邮箱密码/授权码（可选，从环境变量读取）
+
+#### 返回值
+返回包含操作结果的字典：
+```python
+{
+    "status": "success" | "failed",
+    "message": "描述信息",
+    "file_path": "临时文件路径",
+    "email_sent": True | False,
+    "row_count": 数据行数,
+    "timestamp": "时间戳"
+}
+```
+
+### 工具函数
+- `uuid(length=16)`: 生成随机字符串 ID
+
+## 使用示例
+
+### 完整工作流程示例
+
+```python
+from your_module import CallAi, ExcelOSSHandler, ExportToEmail
+import pandas as pd
+
+# 1. 使用 AI 生成数据建议
+ai = CallAi(api_key="your-key", base_url="your-url")
+ai.prompt = "你是一个数据分析专家"
+analysis = ai.chat("分析销售数据时应该关注哪些指标？")
+
+# 2. 从 OSS 获取数据
+oss_handler = ExcelOSSHandler()  # 自动使用环境变量
+df = oss_handler.get_excel_from_oss("sales/data.xlsx")
+
+# 3. 处理数据
+processed_df = df.groupby('category').sum()
+
+# 4. 导出并发送邮件
+result = ExportToEmail(
+    df=processed_df,
+    receiver="team@company.com",
+    subject="销售数据汇总报告"
+)
+
+print(f"操作结果: {result['status']}")
+print(f"发送状态: {'成功' if result['email_sent'] else '失败'}")
+```
+
+## 错误处理
+
+所有函数都包含完整的异常处理，会返回详细的错误信息：
+
+```python
+# 检查操作结果
+result = oss_handler.upload_excel_to_oss("nonexistent.xlsx", "oss/path/file.xlsx")
+if not result:
+    print("文件上传失败")
+
+# 检查邮件发送结果
+email_result = ExportToEmail(df, "receiver@example.com")
+if email_result["status"] == "failed":
+    print(f"发送失败: {email_result['message']}")
+```
+
+## 注意事项
+
+1. **文件格式**: 仅支持 `.xlsx` 和 `.xls` 格式的 Excel 文件
+2. **邮件服务**: 默认使用 163 邮箱的 SMTP 服务（端口 465，SSL）
+3. **临时文件**: 自动创建 `./temp` 目录存放临时文件，邮件发送成功后自动清理
+4. **环境变量**: 建议使用 `.env` 文件管理敏感信息，不要将密钥硬编码在代码中
+
+## 故障排除
+
+### 常见问题
+
+**OSS 连接问题**:
+- 检查 Access Key 和 Secret 是否正确
+- 确认 endpoint 格式正确（包含 http/https）
+- 验证 bucket 名称和权限
+
+**邮件发送失败**:
+- 确认邮箱密码是授权码而非登录密码
+- 检查发件人邮箱是否开启 SMTP 服务
+- 验证网络连接和防火墙设置
+
+**Excel 文件处理错误**:
+- 确认文件没有被其他程序占用
+- 检查 pandas 和 openpyxl 版本兼容性
+- 验证文件内容格式正确
+
+## 更新日志
+
+### v1.1.0
+- 新增环境变量自动加载功能
+- 改进错误处理和日志输出
+- 优化邮件发送逻辑
+
+## 许可证
+
+MIT License

{xp3_tool-5.0 → xp3_tool-5.1}/setup.py

@@ -18,7 +18,7 @@ URL = ''
 EMAIL = 'xupeng23456@126.com'
 AUTHOR = 'XuPeng'
 REQUIRES_PYTHON = '>=3.10.0'
-VERSION = '5.0'
+VERSION = '5.1'
 
 # What packages are required for this module to be executed?
 REQUIRED = [

{xp3_tool-5.0 → xp3_tool-5.1}/xp3_tool/__init__.py

@@ -7,4 +7,4 @@ __all__ = [
     "ExportToEmail"
 ]
 
-__version__ = "5.0"
+__version__ = "5.1"

{xp3_tool-5.0 → xp3_tool-5.1}/xp3_tool/xp3_tool.py

@@ -59,7 +59,7 @@ class CallAi:
 class ExcelOSSHandler:
     """处理Excel文件与阿里云OSS的交互，并提供转换为pandas DataFrame的功能"""
     
-    def __init__(self, access_key_id: str, access_key_secret: str, endpoint: str, bucket_name: str):
+    def __init__(self, access_key_id: str = None, access_key_secret: str = None, endpoint: str = None, bucket_name: str = None):
         """
         初始化OSS连接
         
@@ -69,6 +69,13 @@ class ExcelOSSHandler:
         :param bucket_name: OSS存储桶名称
         """
         # 初始化OSS认证
+        if not access_key_id:
+            load_dotenv()
+            access_key_id = os.getenv("ACCESS_KEY_ID")
+            access_key_secret = os.getenv("ACCESS_KEY_SECRET")
+            endpoint = os.getenv("ENDPOINT")
+            bucket_name = os.getenv("BUCKET_NAME")
+            
         self.auth = oss2.Auth(access_key_id, access_key_secret)
         # 获取存储桶对象
         self.bucket = oss2.Bucket(self.auth, endpoint, bucket_name)