Metadata-Version: 2.4
Name: darren_utils
Version: 0.2.1.309
Summary: 一个功能丰富的工具包
Author-email: Darren <2775856@qq.com>
License: MIT
Project-URL: Homepage, https://github.com/Darren5211314
Project-URL: Repository, https://github.com/Darren5211314
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: cryptography
Requires-Dist: gmssl
Requires-Dist: httpx[http2]
Requires-Dist: redis
Requires-Dist: pyperclip
Requires-Dist: send2trash
Requires-Dist: loguru
Requires-Dist: socksio
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: send2trash; extra == "dev"
Requires-Dist: pyperclip; extra == "dev"
Requires-Dist: pillow; extra == "dev"
Requires-Dist: psutil; extra == "dev"
Requires-Dist: pyarmor>=9.0; extra == "dev"

# darren_utils

[![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue)](https://www.python.org/)
[![HTTP](https://img.shields.io/badge/http-httpx-success)](https://www.python-httpx.org/)
[![Crypto](https://img.shields.io/badge/crypto-AES%20%7C%20RSA%20%7C%20SMx-informational)](#模块概览)

`darren_utils` 是一个面向爬虫、自动化与通用工具场景的 Python 工具库，重点提供：

- 对称/非对称加密与摘要签名（AES / DES / 3DES / RC4 / RSA / SM2 / SM3 / SM4 / HASH / HMAC）
- 基于 `httpx` 的同步 HTTP 封装（Session 与非 Session、代理、下载、统一返回）
- 代理池管理（API 拉取、可用性验证、内存/Redis 模式）
- 字符串、时间、文件、剪贴板、设备信息等高频工具
- 通用返回对象 `DarrenRet`（`success/message/data/error_code`）

---

## 安装

### 方式 1：本地开发安装（推荐）

```bash
pip install -e .
```

### 方式 2：按依赖安装

```bash
pip install -r requirements.txt
```

### 核心依赖

- `httpx[http2]`
- `cryptography`
- `gmssl`
- `redis`
- `pyperclip`
- `send2trash`
- `loguru`
- `socksio`

---

## 快速开始

```python
import darren
```

### 1) 加密示例（AES）

```python
cipher = darren.aes.encry(
    "cbc",
    "hello",
    "1234567890abcdef",
    "abcdef1234567890",
    "pkcs7",
)
plain = darren.aes.decry(
    "cbc",
    cipher,
    "1234567890abcdef",
    "abcdef1234567890",
    "pkcs7",
)
print(cipher, plain)
```

### 2) HTTP 基础（保持旧接口）

```python
resp = darren.http.get("https://example.com", timeout=10, max_retries=1)
if resp:
    print(resp.status_code)
    print(resp.text_trunc(120))
    print(resp.getLocation())
    print(resp.getProxyUsed())
```

### 3) HTTP 统一返回（推荐新接口）

```python
ret = darren.http.get_ret("https://example.com", timeout=10, max_retries=0)
if ret.isSuccess():
    data = ret.getData({})
    print(data.get("status_code"))
    print(data.get("proxy_used"))
else:
    print(ret.getErrorCode(), ret.getMessage(), ret.getErrorDetail())
```

### 4) 代理配置与使用

```python
cfg = darren.ProxyConfig()
cfg.set_api_url("http://your-proxy-api")
cfg.set_timeout(8)
cfg.set_verify_proxy(True)

darren.proxy.set_config(cfg)
proxy_dict = darren.proxy.get_one_proxy(timeout=5)
print(proxy_dict)
```

### 5) DarrenRet 使用

```python
ok_ret = darren.DarrenRet.success_ret(data={"id": 1}, message="ok")
fail_ret = darren.DarrenRet.failure_ret(
    error_code="TIMEOUT",
    message="request timeout",
    error_detail="connect timeout 5s",
)
print(ok_ret.isSuccess(), ok_ret.to_dict())
print(fail_ret.isFailure(), fail_ret.toErrorString())
```

---

## 模块概览

| 模块                                         | 说明                             |
| ------------------------------------------ | ------------------------------ |
| `darren.aes`                               | AES 加解密（模式、填充、格式）              |
| `darren.des` / `darren.triple_des`         | DES / 3DES                     |
| `darren.rc4`                               | RC4                            |
| `darren.rsa`                               | RSA 密钥生成、加解密、签名验签              |
| `darren.sm2` / `darren.sm3` / `darren.sm4` | 国密算法                           |
| `darren.hash` / `darren.hmac`              | 摘要与 HMAC                       |
| `darren.http`                              | HTTP 封装（`httpx`、代理、下载、`*_ret`） |
| `darren.proxy` / `darren.ProxyConfig`      | 代理池与配置                         |
| `darren.string`                            | 字符串/URL/Cookie/JSON 工具         |
| `darren.time`                              | 时间与重试间隔工具                      |
| `darren.file`                              | 文件与目录工具                        |
| `darren.clipboard`                         | 剪贴板工具                          |
| `darren.device`                            | 设备信息采集                         |
| `darren.DarrenRet`                         | 通用返回对象                         |

---

## HTTP 与返回模型

### 兼容策略

- 旧接口不变：`get/post/... -> DarrenResponse | None`
- 新接口统一：`get_ret/post_ret/... -> DarrenRet`

### `DarrenRet` 结构

```python
{
  "success": bool,
  "message": str,
  "data": Any,
  "error_code": str,
  "error_detail": str,
  "meta": dict
}
```

### 常见错误码

- `OK`
- `TIMEOUT`
- `NETWORK_ERROR`
- `PROXY_ERROR`
- `HTTP_STATUS_ERROR`
- `INTERNAL_ERROR`

---

## 代理与 SOCKS 支持

- HTTP 代理：`http://ip:port`
- 带认证代理：`http://user:pass@ip:port`
- SOCKS 代理：`socks5://ip:port`
- 兼容别名：`socket://` / `socket5://` / `socks://`（内部归一化为 `socks5://`）

示例：

```python
proxies = {
    "http": "socks5://user:pass@127.0.0.1:7890",
    "https": "socks5://user:pass@127.0.0.1:7890",
}
ret = darren.http.get_ret("http://utils.darren8.com/ip/getIP", proxies=proxies, use_proxy=False)
print(ret.getMeta("proxy_used"))
```

---

## 测试

项目内置非 pytest 冒烟测试脚本：

```bash
python Test.py
```

测试覆盖：

- 剪贴板工具
- 文件工具
- `DarrenRet` 对象
- `http-ret` 成功/失败路径

---

## 发布

提供一键发布脚本：

```bash
# 默认发布到 TestPyPI
python release.py

# 发布到正式 PyPI
python release.py --target pypi
```

---

## FAQ

### 1) 为什么设备字段有时为空？

不同系统权限、硬件厂商暴露能力不同，空值属于正常情况。建议组合多个字段生成设备指纹。

### 2) 为什么请求失败但程序没有崩溃？

HTTP 封装默认采用安全返回策略（旧接口返回 `None`，`*_ret` 返回失败对象），便于上层统一处理。

### 3) 代理一定要 Redis 吗？

不需要。默认内存模式即可使用；仅在你需要跨进程共享代理池时启用 Redis。

---

## 注意事项

- `gmssl` 为国密相关模块必需依赖。
- SOCKS 代理需 `socksio`。
- 代理密码若含特殊字符（如 `@`, `:`, `/`），建议先进行 URL 编码。
