darren-utils 0.2.1.307

一个功能丰富的工具包

darren_utils

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：本地开发安装（推荐）

pip install -e .

方式 2：按依赖安装

pip install -r requirements.txt

核心依赖

• httpx[http2]
• cryptography
• gmssl
• redis
• pyperclip
• send2trash
• loguru
• socksio

---

快速开始

import darren

1) 加密示例（AES）

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

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

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 统一返回（推荐新接口）

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) 代理配置与使用

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 使用

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 结构

{
  "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://）

示例：

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 冒烟测试脚本：

python Test.py

测试覆盖：

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

---

发布

提供一键发布脚本：

# 默认发布到 TestPyPI
python release.py

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

---

FAQ

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

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

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

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

3) 代理一定要 Redis 吗？

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

---

注意事项

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