simtoolsz 0.2.2__tar.gz → 0.2.6__tar.gz

simtoolsz-0.2.6/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.3
+Name: simtoolsz
+Version: 0.2.6
+Summary: A simple and convenient toolkit containing useful functions, classes, and methods.
+Project-URL: Homepage, https://github.com/SidneyLYZhang/simtoolsz
+Project-URL: Repository, https://github.com/SidneyLYZhang/simtoolsz.git
+Project-URL: Issues, https://github.com/SidneyLYZhang/simtoolsz/issues
+Author-email: Sidney Zhang <liangyi@me.com>
+License: MulanPSL-2.0
+Keywords: collection,tool
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Mulan Permissive Software License v2 (MulanPSL-2.0)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.4.0
+Requires-Dist: pendulum>=3.1.0
+Requires-Dist: polars>=1.33.1
+Description-Content-Type: text/markdown
+
+# simtoolsz
+
+<div>
+<img alt="PyPI - License" src="https://img.shields.io/pypi/l/simtoolsz">
+<img alt="PyPI - Version" src="https://img.shields.io/pypi/v/simtoolsz">
+<img alt="Python - Version" src="https://img.shields.io/pypi/pyversions/simtoolsz">
+</div>
+
+[English](README_EN.md) | 中文
+
+一个简单、方便的工具集合，均是个人工作中的常用功能。对之前[pytoolsz](https://github.com/SidneyLYZhang/pytoolsz)工具包的精简重构，保留最实用的功能模块。
+
+## 功能特性
+
+### 🕐 时间处理 (`simtoolsz.datetime`)
+- **时间格式转换**: 支持多种时间格式间的相互转换（中文、英文、ISO8601、秒、分钟、小时等）
+- **智能格式识别**: 自动识别输入的时间格式类型
+- **枚举支持**: 提供 `DurationFormat` 枚举类，标准化时间格式处理
+- **时间计算**: 支持时间跨度的计算和转换
+
+### 📧 邮件处理 (`simtoolsz.mail`)
+- **邮件发送**: 支持HTML/纯文本邮件，附件、抄送、密送
+- **邮件接收**: IMAP协议邮件读取，支持主题搜索
+- **编码支持**: UTF-7编码解码，处理国际化邮件
+- **内嵌图片**: 支持HTML邮件中的内嵌图片
+
+### 💾 数据处理 (`simtoolsz.db`)
+- **压缩包数据读取**: 直接从ZIP压缩包读取CSV、Excel、Parquet、JSON数据到DuckDB
+- **特殊格式支持**: 支持TSV、Avro、Arrow等特殊格式文件的数据库转换
+- **批量处理**: 支持多文件批量导入数据库
+- **灵活配置**: 可自定义表名映射和导入参数
+
+### 📖 数据读取 (`simtoolsz.reader`)
+- **多格式读取**: 统一接口读取CSV、TSV、Excel、Parquet、JSON、IPC、Avro等格式
+- **Polars集成**: 基于Polars的高性能数据读取
+- **智能选择**: 根据文件扩展名自动选择合适的读取器
+- **Lazy加载支持**: 支持大数据集的懒加载模式
+
+### 🛠️ 工具函数 (`simtoolsz.utils`)
+- **日期获取**: `today()` 函数，支持时区、格式化、标准datetime对象返回
+- **列表操作**: `take_from_list()` 智能列表元素查找
+- **文件夹操作**: `checkFolders()` 批量文件夹检查和创建
+- **文件查找**: `lastFile()` 基于时间或大小的文件查找
+
+## 安装
+
+```bash
+pip install simtoolsz
+```
+
+### 核心依赖
+
+- Python >= 3.11
+- pendulum >= 3.1.0
+- duckdb >= 1.4.0
+- polars >= 1.0.0
+
+## 快速开始
+
+### 时间格式转换
+```python
+from simtoolsz.datetime import TimeConversion
+
+# 中文时间到秒
+tc = TimeConversion("1天2小时30分钟45秒", "chinese")
+seconds = tc.convert("seconds")
+print(f"1天2小时30分钟45秒 = {seconds}秒")
+
+# 秒到中文时间
+tc = TimeConversion(90061, "seconds")
+chinese = tc.convert("chinese")
+print(f"90061秒 = {chinese}")
+```
+
+### 发送邮件
+```python
+from simtoolsz.mail import send_email
+
+# 发送纯文本邮件
+result = send_email(
+    email_account="your@qq.com",
+    password="your_password",
+    subject="测试邮件",
+    content="这是一封测试邮件",
+    recipients="friend@example.com"
+)
+
+# 发送HTML邮件带附件
+result = send_email(
+    email_account="your@gmail.com",
+    password="app_password",
+    subject="项目报告",
+    content="<h1>本月工作报告</h1><p>详见附件</p>",
+    recipients=["boss@company.com", "同事<colleague@company.com>"],
+    attachments=["report.pdf", "data.xlsx"],
+    html_mode=True
+)
+```
+
+### 数据读取
+```python
+from simtoolsz.reader import getreader
+import polars as pl
+
+# 使用getreader读取CSV文件
+reader = getreader("data.csv")
+df = reader("data.csv")
+
+# 读取TSV文件
+df = load_tsv("data.tsv")
+
+# Lazy加载大数据集
+lazy_df = load_data("large_data.csv", lazy=True)
+
+# 加载压缩数据集
+df = load_data("large_data_archive.tar.gz/data.csv")
+```
+
+### 压缩包数据导入数据库
+```python
+from simtoolsz.db import zip2db
+
+# 从ZIP文件读取数据到DuckDB
+con = zip2db(
+    zip_file="data.zip",
+    db_file="output.db",
+    table={"users.csv": "用户表", "orders.xlsx": "订单表"}
+)
+
+# 查询数据
+tables = con.execute("SHOW TABLES").fetchall()
+print(f"导入的表: {tables}")
+```
+
+### 工具函数
+```python
+from simtoolsz.utils import today, take_from_list
+
+# 获取当前日期时间
+current = today(addtime=True)
+formatted = today(fmt="YYYY年MM月DD日 HH:mm:ss")
+
+# 列表查找
+result = take_from_list("hello", ["he", "world"])  # 返回 "he"
+result = take_from_list([2, 3], [1, 2, 3, 4])    # 返回 2
+```

simtoolsz-0.2.6/README.md

@@ -0,0 +1,146 @@
+# simtoolsz
+
+<div>
+<img alt="PyPI - License" src="https://img.shields.io/pypi/l/simtoolsz">
+<img alt="PyPI - Version" src="https://img.shields.io/pypi/v/simtoolsz">
+<img alt="Python - Version" src="https://img.shields.io/pypi/pyversions/simtoolsz">
+</div>
+
+[English](README_EN.md) | 中文
+
+一个简单、方便的工具集合，均是个人工作中的常用功能。对之前[pytoolsz](https://github.com/SidneyLYZhang/pytoolsz)工具包的精简重构，保留最实用的功能模块。
+
+## 功能特性
+
+### 🕐 时间处理 (`simtoolsz.datetime`)
+- **时间格式转换**: 支持多种时间格式间的相互转换（中文、英文、ISO8601、秒、分钟、小时等）
+- **智能格式识别**: 自动识别输入的时间格式类型
+- **枚举支持**: 提供 `DurationFormat` 枚举类，标准化时间格式处理
+- **时间计算**: 支持时间跨度的计算和转换
+
+### 📧 邮件处理 (`simtoolsz.mail`)
+- **邮件发送**: 支持HTML/纯文本邮件，附件、抄送、密送
+- **邮件接收**: IMAP协议邮件读取，支持主题搜索
+- **编码支持**: UTF-7编码解码，处理国际化邮件
+- **内嵌图片**: 支持HTML邮件中的内嵌图片
+
+### 💾 数据处理 (`simtoolsz.db`)
+- **压缩包数据读取**: 直接从ZIP压缩包读取CSV、Excel、Parquet、JSON数据到DuckDB
+- **特殊格式支持**: 支持TSV、Avro、Arrow等特殊格式文件的数据库转换
+- **批量处理**: 支持多文件批量导入数据库
+- **灵活配置**: 可自定义表名映射和导入参数
+
+### 📖 数据读取 (`simtoolsz.reader`)
+- **多格式读取**: 统一接口读取CSV、TSV、Excel、Parquet、JSON、IPC、Avro等格式
+- **Polars集成**: 基于Polars的高性能数据读取
+- **智能选择**: 根据文件扩展名自动选择合适的读取器
+- **Lazy加载支持**: 支持大数据集的懒加载模式
+
+### 🛠️ 工具函数 (`simtoolsz.utils`)
+- **日期获取**: `today()` 函数，支持时区、格式化、标准datetime对象返回
+- **列表操作**: `take_from_list()` 智能列表元素查找
+- **文件夹操作**: `checkFolders()` 批量文件夹检查和创建
+- **文件查找**: `lastFile()` 基于时间或大小的文件查找
+
+## 安装
+
+```bash
+pip install simtoolsz
+```
+
+### 核心依赖
+
+- Python >= 3.11
+- pendulum >= 3.1.0
+- duckdb >= 1.4.0
+- polars >= 1.0.0
+
+## 快速开始
+
+### 时间格式转换
+```python
+from simtoolsz.datetime import TimeConversion
+
+# 中文时间到秒
+tc = TimeConversion("1天2小时30分钟45秒", "chinese")
+seconds = tc.convert("seconds")
+print(f"1天2小时30分钟45秒 = {seconds}秒")
+
+# 秒到中文时间
+tc = TimeConversion(90061, "seconds")
+chinese = tc.convert("chinese")
+print(f"90061秒 = {chinese}")
+```
+
+### 发送邮件
+```python
+from simtoolsz.mail import send_email
+
+# 发送纯文本邮件
+result = send_email(
+    email_account="your@qq.com",
+    password="your_password",
+    subject="测试邮件",
+    content="这是一封测试邮件",
+    recipients="friend@example.com"
+)
+
+# 发送HTML邮件带附件
+result = send_email(
+    email_account="your@gmail.com",
+    password="app_password",
+    subject="项目报告",
+    content="<h1>本月工作报告</h1><p>详见附件</p>",
+    recipients=["boss@company.com", "同事<colleague@company.com>"],
+    attachments=["report.pdf", "data.xlsx"],
+    html_mode=True
+)
+```
+
+### 数据读取
+```python
+from simtoolsz.reader import getreader
+import polars as pl
+
+# 使用getreader读取CSV文件
+reader = getreader("data.csv")
+df = reader("data.csv")
+
+# 读取TSV文件
+df = load_tsv("data.tsv")
+
+# Lazy加载大数据集
+lazy_df = load_data("large_data.csv", lazy=True)
+
+# 加载压缩数据集
+df = load_data("large_data_archive.tar.gz/data.csv")
+```
+
+### 压缩包数据导入数据库
+```python
+from simtoolsz.db import zip2db
+
+# 从ZIP文件读取数据到DuckDB
+con = zip2db(
+    zip_file="data.zip",
+    db_file="output.db",
+    table={"users.csv": "用户表", "orders.xlsx": "订单表"}
+)
+
+# 查询数据
+tables = con.execute("SHOW TABLES").fetchall()
+print(f"导入的表: {tables}")
+```
+
+### 工具函数
+```python
+from simtoolsz.utils import today, take_from_list
+
+# 获取当前日期时间
+current = today(addtime=True)
+formatted = today(fmt="YYYY年MM月DD日 HH:mm:ss")
+
+# 列表查找
+result = take_from_list("hello", ["he", "world"])  # 返回 "he"
+result = take_from_list([2, 3], [1, 2, 3, 4])    # 返回 2
+```

simtoolsz-0.2.6/README_EN.md

@@ -0,0 +1,146 @@
+# simtoolsz
+
+<div>
+<img alt="PyPI - License" src="https://img.shields.io/pypi/l/simtoolsz">
+<img alt="PyPI - Version" src="https://img.shields.io/pypi/v/simtoolsz">
+<img alt="Python - Version" src="https://img.shields.io/pypi/pyversions/simtoolsz">
+</div>
+
+English | [中文](README.md)
+
+A simple and convenient toolkit containing useful functions, classes, and methods. A streamlined refactoring of the previous [pytoolsz](https://github.com/SidneyLYZhang/pytoolsz) toolkit, keeping only the most practical functional modules.
+
+## Features
+
+### 🕐 Time Processing (`simtoolsz.datetime`)
+- **Time Format Conversion**: Supports mutual conversion between multiple time formats (Chinese, English, ISO8601, seconds, minutes, hours, etc.)
+- **Smart Format Recognition**: Automatically identifies the type of input time format
+- **Enum Support**: Provides `DurationFormat` enum class for standardized time format processing
+- **Time Calculation**: Supports calculation and conversion of time spans
+
+### 📧 Email Processing (`simtoolsz.mail`)
+- **Email Sending**: Supports HTML/plain text emails, attachments, CC, BCC
+- **Email Receiving**: IMAP protocol email reading, supports subject search
+- **Encoding Support**: UTF-7 encoding and decoding for handling internationalized emails
+- **Embedded Images**: Supports embedded images in HTML emails
+
+### 💾 Data Processing (`simtoolsz.db`)
+- **Compressed Data Reading**: Directly reads CSV, Excel, Parquet, JSON data from ZIP archives to DuckDB
+- **Special Format Support**: Supports database conversion of special format files like TSV, Avro, Arrow
+- **Batch Processing**: Supports batch import of multiple files to database
+- **Flexible Configuration**: Customizable table name mapping and import parameters
+
+### 📖 Data Reading (`simtoolsz.reader`)
+- **Multi-format Reading**: Unified interface for reading CSV, TSV, Excel, Parquet, JSON, IPC, Avro and other formats
+- **Polars Integration**: High-performance data reading based on Polars
+- **Smart Selection**: Automatically selects appropriate reader based on file extension
+- **Lazy Loading Support**: Supports lazy loading mode for large datasets
+
+### 🛠️ Utility Functions (`simtoolsz.utils`)
+- **Date Acquisition**: `today()` function, supports timezone, formatting, standard datetime object return
+- **List Operations**: `take_from_list()` intelligent list element lookup
+- **Folder Operations**: `checkFolders()` batch folder checking and creation
+- **File Lookup**: `lastFile()` file lookup based on time or size
+
+## Installation
+
+```bash
+pip install simtoolsz
+```
+
+### Core Dependencies
+
+- Python >= 3.11
+- pendulum >= 3.1.0
+- duckdb >= 1.4.0
+- polars >= 1.0.0
+
+## Quick Start
+
+### Time Format Conversion
+```python
+from simtoolsz.datetime import TimeConversion
+
+# Chinese time to seconds
+tc = TimeConversion("1天2小时30分钟45秒", "chinese")
+seconds = tc.convert("seconds")
+print(f"1天2小时30分钟45秒 = {seconds}秒")
+
+# Seconds to Chinese time
+tc = TimeConversion(90061, "seconds")
+chinese = tc.convert("chinese")
+print(f"90061秒 = {chinese}")
+```
+
+### Send Email
+```python
+from simtoolsz.mail import send_email
+
+# Send plain text email
+result = send_email(
+    email_account="your@qq.com",
+    password="your_password",
+    subject="Test Email",
+    content="This is a test email",
+    recipients="friend@example.com"
+)
+
+# Send HTML email with attachments
+result = send_email(
+    email_account="your@gmail.com",
+    password="app_password",
+    subject="Project Report",
+    content="<h1>This Month's Work Report</h1><p>See attachment for details</p>",
+    recipients=["boss@company.com", "colleague<colleague@company.com>"],
+    attachments=["report.pdf", "data.xlsx"],
+    html_mode=True
+)
+```
+
+### Data Reading
+```python
+from simtoolsz.reader import getreader
+import polars as pl
+
+# Read CSV file using getreader
+reader = getreader("data.csv")
+df = reader("data.csv")
+
+# Read TSV file
+df = load_tsv("data.tsv")
+
+# Lazy loading for large datasets
+lazy_df = load_data("large_data.csv", lazy=True)
+
+# Load compressed dataset
+df = load_data("large_data_archive.tar.gz/data.csv")
+```
+
+### Compressed Data Import to Database
+```python
+from simtoolsz.db import zip2db
+
+# Read data from ZIP file to DuckDB
+con = zip2db(
+    zip_file="data.zip",
+    db_file="output.db",
+    table={"users.csv": "users_table", "orders.xlsx": "orders_table"}
+)
+
+# Query data
+tables = con.execute("SHOW TABLES").fetchall()
+print(f"Imported tables: {tables}")
+```
+
+### Utility Functions
+```python
+from simtoolsz.utils import today, take_from_list
+
+# Get current date and time
+current = today(addtime=True)
+formatted = today(fmt="YYYY-MM-DD HH:mm:ss")
+
+# List lookup
+result = take_from_list("hello", ["he", "world"])  # Returns "he"
+result = take_from_list([2, 3], [1, 2, 3, 4])    # Returns 2
+```

simtoolsz-0.2.6/docs/special2db_usage.md

@@ -0,0 +1,106 @@
+# special2db 函数使用指南
+
+`special2db` 函数用于将特殊格式的数据文件（TSV、Avro、Arrow）转换为DuckDB数据库。
+
+## 支持的文件格式
+
+- **TSV**: 制表符分隔的文本文件
+- **Avro**: Apache Avro格式文件  
+- **Arrow**: Apache Arrow格式文件
+
+## 基本用法
+
+### 读取单个TSV文件
+
+```python
+from simtoolsz.db import special2db
+
+# 读取单个TSV文件到DuckDB
+con = special2db('data/users.tsv', 'users.db')
+
+# 查询数据
+tables = con.execute("SHOW TABLES").fetchall()
+count = con.execute("SELECT COUNT(*) FROM users").fetchone()[0]
+print(f"记录数: {count}")
+
+# 关闭连接
+con.close()
+```
+
+### 使用自定义表名
+
+```python
+# 使用自定义表名
+con = special2db('data/customers.tsv', 'customers.db', table='客户表')
+
+# 查询自定义表名的数据
+count = con.execute("SELECT COUNT(*) FROM 客户表").fetchone()[0]
+print(f"客户表记录数: {count}")
+con.close()
+```
+
+### 处理目录中的多个文件
+
+```python
+# 处理目录中的所有TSV文件
+con = special2db('data_directory', 'all_data.db')
+
+# 查看所有创建的表
+tables = con.execute("SHOW TABLES").fetchall()
+print(f"创建的表: {[table[0] for table in tables]}")
+
+# 查询特定表
+count = con.execute("SELECT COUNT(*) FROM users").fetchone()[0]
+print(f"users表记录数: {count}")
+con.close()
+```
+
+### 指定读取参数
+
+```python
+# 指定编码和其他参数
+con = special2db('data/data.tsv', 'output.db', 
+                encoding='utf-8', 
+                header=True)
+
+# 查询数据
+tables = con.execute("SHOW TABLES").fetchall()
+print(f"创建的表: {[table[0] for table in tables]}")
+con.close()
+```
+
+## 错误处理
+
+函数会在以下情况下抛出 `ValueError`：
+
+1. **找不到支持的数据文件**
+   ```python
+   # 目录中没有TSV、Avro或Arrow文件
+   con = special2db('empty_directory', 'output.db')
+   # ValueError: 未找到支持的数据文件（tsv、avro、arrow）
+   ```
+
+2. **不支持的文件格式**
+   ```python
+   # 尝试读取不支持的文件格式
+   con = special2db('data/file.txt', 'output.db')
+   # ValueError: 不支持的文件格式: .txt。支持的格式: tsv, avro, arrow
+   ```
+
+## 表名处理规则
+
+1. **默认表名**: 使用文件名（不含扩展名）
+2. **自定义表名**: 通过 `table` 参数指定
+3. **表名清理**: 自动移除特殊字符，只保留字母、数字和下划线
+4. **多文件处理**: 每个文件创建一个表，表名基于文件名
+
+## 注意事项
+
+1. **数据库连接**: 函数返回DuckDB连接对象，使用完毕后需要手动关闭
+2. **表覆盖**: 如果表已存在，会先删除再重新创建
+3. **文件锁定**: 确保在使用完连接后关闭，避免文件锁定问题
+4. **临时文件**: 示例中使用临时文件时，注意文件生命周期管理
+
+## 完整示例
+
+参考 `examples/special2db_example.py` 文件获取完整的使用示例。