Metadata-Version: 2.3
Name: simtoolsz
Version: 0.2.14.2
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
Requires-Dist: pyarrow>=22.0.0
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()` 基于时间或大小的文件查找

### 国家代码转换 (`simtoolsz.countrycode`)
- **国家名称到代码**: 支持将国家名称转换为对应的ISO 3166-1 alpha-2代码
- **代码到国家名称**: 支持将ISO 3166-1 alpha-2代码转换为国家名称
- **G7/G20国家列表**: 提供G7和G20国家的代码列表
- **多类型国家代码转换**：支持类型丰富，详细可见[代码转换模块说明](README_countrycode.md)

## 安装

```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
```
### 国家代码转换
```python
from simtoolsz.countrycode import CountryCode

# 初始化国家代码转换工具
cc = CountryCode()

# 转换国家名称到代码
code = cc.convert("中国")  # 返回 "CN"

# 转换代码到国家名称
name = cc.convert("US", target="name")  # 返回 "United States"

# 获取G7国家列表
g7 = cc.convert("G7", target="name")
print(g7)
```