pycorelibs 0.3.2
A collection of reusable python core library from AI Lingues.
License: MIT
Requires Python: >=3.11
Keywords: AILingues, components, core, library

# PyCoreLibs

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.2.9-orange.svg)](https://github.com/ailingues/pycorelibs)

**PyCoreLibs** 是由 AI Lingues 开发的 Python 核心工具库，提供了一套完整、可靠、跨平台的基础组件，涵盖网络请求、系统信息、消息队列、安全加密、日志管理等常用功能。旨在帮助开发者快速构建稳定的 Python 应用程序。

---

## ✨ 核心特性

- 🌐 **网络工具** - 强化版 HTTP 请求（支持重试、代理、SSL）、网页抓取、文件上传
- 💻 **系统信息** - 跨平台获取 CPU、主板、显示器、网卡、操作系统等硬件信息
- 📨 **消息队列** - 基于 Redis 的异步消息框架，支持优先级、重试、确认机制
- 🔐 **安全加密** - RSA/AES 混合加密、数字签名、硬件指纹、MD5/Base64 工具
- 📝 **日志管理** - 支持日志切割（按时间/大小）、多级别输出、彩色终端
- 🛠️ **实用工具** - 配置管理、文件操作、字符串处理等常用辅助函数

---

## 📦 安装

### 使用 pip 安装（推荐）

```bash
pip install pycorelibs
```

### 从源码安装

不支持

### 依赖要求

- Python >= 3.11
- Redis 服务（仅消息队列模块需要）

---

## 🚀 快速开始

### 1. 网络请求

```python
from pycorelibs.network.requests import fetch_url, HTTPMethod

# 同步请求
resp = fetch_url(
    url="https://api.github.com/repos/python/cpython",
    method=HTTPMethod.GET,
    timeout=10,
    max_retries=3
)

if resp["success"]:
    print("响应内容:", resp["content"])
else:
    print("请求失败:", resp["error"])
```

### 2. 系统信息获取

```python
from pycorelibs.system.inspector import SystemInfo

# 获取完整系统硬件指纹
info = SystemInfo().get_data()
print(f"操作系统: {info['os']['system']}")
print(f"CPU: {info['cpu']['brand_raw']}")
print(f"主 MAC: {info.get('primary_mac')}")
```

### 3. 异步消息队列

```python
import asyncio
from pycorelibs.message.redis.redis_queue import RedisMessageQueue
from pycorelibs.message.redis.redis_sender import MessageSender
from pycorelibs.message.redis.redis_receiver import MessageReceiver

# 创建全局队列
queue = RedisMessageQueue(db=5, queue_key="my_queue")

# 消息处理函数
async def handle_message(msg):
    print(f"收到消息: {msg.text}")
    queue.confirm(msg.msg_id)

# 启动接收器
async def main():
    receiver = MessageReceiver(queue=queue, callback=handle_message)
    asyncio.create_task(receiver.run())

    # 发送消息
    sender = MessageSender(queue)
    sender.send(text="Hello World!", priority=0)

    await asyncio.sleep(2)

asyncio.run(main())
```

### 4. 加密与签名

```python
from pycorelibs.security.cryptographys import AsymmetricCrypto

# 生成密钥对
priv, pub = AsymmetricCrypto.generate_keypair(key_size=2048)

# 加密
message = b"Secret data"
encrypted = AsymmetricCrypto.encrypt(message, pub)

# 解密
decrypted = AsymmetricCrypto.decrypt(encrypted, priv)
assert decrypted == message

# 签名
signature = AsymmetricCrypto.sign(message, priv)

# 验签
is_valid = AsymmetricCrypto.verify(message, signature, pub)
print(f"签名验证: {is_valid}")
```

### 5. 日志管理

```python
from pycorelibs.utils.logger import Logger

# 创建日志器（支持按大小或时间切割）
logger = Logger(
    log_dir="./logs",
    filename_prefix="myapp",
    level_console=Logger.INFO,
    rotation_mode="size",
    rotation_size=10 * 1024 * 1024  # 10MB
)

logger.info("应用启动")
logger.warning("这是一条警告")
logger.error("发生错误")
```

---

## 📚 模块说明

### 🌐 Network（网络）

| 模块       | 功能                                    | 文档                                  |
| ---------- | --------------------------------------- | ------------------------------------- |
| `requests` | 强化版 HTTP 请求（支持重试、代理、SSL） | [network.md](docs/network/network.md) |
| `scrawer`  | 网页内容抓取与 Markdown 转换            | [network.md](docs/network/network.md) |
| `upload`   | 文件上传处理（支持大小限制、哈希校验）  | [network.md](docs/network/network.md) |

### 💻 System（系统）

| 模块         | 功能                       | 文档                               |
| ------------ | -------------------------- | ---------------------------------- |
| `cpu`        | CPU 信息获取               | [system.md](docs/system/system.md) |
| `mainboard`  | 主板/BIOS/UUID 信息        | [system.md](docs/system/system.md) |
| `monitors`   | 显示器信息（分辨率、坐标） | [system.md](docs/system/system.md) |
| `netadapter` | 网卡信息（MAC、IP、状态）  | [system.md](docs/system/system.md) |
| `osinfo`     | 操作系统基本信息           | [system.md](docs/system/system.md) |
| `runtime`    | 系统启动时间、运行时长     | [system.md](docs/system/system.md) |
| `inspector`  | 系统硬件指纹聚合           | [system.md](docs/system/system.md) |

### 📨 Message（消息）

| 模块             | 功能                   | 文档                                  |
| ---------------- | ---------------------- | ------------------------------------- |
| `redis_queue`    | Redis 消息队列管理     | [message.md](docs/message/message.md) |
| `redis_sender`   | 消息发送器             | [message.md](docs/message/message.md) |
| `redis_receiver` | 消息接收器（异步处理） | [message.md](docs/message/message.md) |

### 🔐 Security（安全）

| 模块            | 功能                       | 文档                                     |
| --------------- | -------------------------- | ---------------------------------------- |
| `cryptographys` | RSA/AES 混合加密、数字签名 | [security.md](docs/security/security.md) |
| `fingerprints`  | 硬件指纹生成               | [security.md](docs/security/security.md) |
| `md5s`          | MD5 哈希计算               | [security.md](docs/security/security.md) |
| `base64s`       | Base64 编解码              | [security.md](docs/security/security.md) |

### 🛠️ Utils（工具）

| 模块                | 功能                 | 文档                                                          |
| ------------------- | -------------------- | ------------------------------------------------------------- |
| `logger`            | 日志管理（支持切割） | [logger.md](docs/utils/logger.md)                             |
| `config`            | 配置文件管理         | [config.md](docs/utils/config.md)                             |
| `files`             | 文件信息与统计       | [files.md](docs/utils/files.md)                               |
| `file_operations`   | 文本文件合并与拆分   | [file_operations.md](docs/utils/files/file_operations.md)     |
| `filetype_detector` | 文件类型检测         | [filetype_detector.md](docs/utils/files/filetype_detector.md) |
| `strings`           | 字符串处理工具       | [strings.md](docs/utils/strings.md)                           |

---

## 📖 完整文档

详细的 API 文档请查看 [docs](docs/) 目录：

- [网络模块 API](docs/network/network.md)
- [系统模块 API](docs/system/system.md)
- [消息模块 API](docs/message/message.md)
- [安全模块 API](docs/security/security.md)
- [工具模块 API](docs/utils/)

---

## 🏗️ 项目结构

```
pycorelibs/
├── pycorelibs/           # 源代码
│   ├── network/          # 网络模块
│   ├── system/           # 系统信息模块
│   ├── message/          # 消息队列模块
│   ├── security/         # 安全加密模块
│   └── utils/            # 工具模块
├── docs/                 # API 文档
├── test/                 # 单元测试
├── pyproject.toml        # 项目配置
├── requirements.txt      # 依赖列表
└── README.md             # 本文件
```

---

## 📝 许可证与使用条款

### 软件包使用许可

**PyCoreLibs** 软件包（通过 pip 安装的二进制包）采用 **MIT License** 开源协议：

- ✅ **自由使用** - 可在个人项目、企业项目中自由使用
- ✅ **商业用途** - 允许用于商业产品和服务
- ✅ **自由分发** - 可自由分发和再分发软件包
- ✅ **无使用限制** - 无需支付任何费用或获得额外授权

### 源代码保护条款

**重要声明**：本项目的 **源代码为私有财产**，受知识产权法保护：

- ❌ **不公开源代码** - 源代码不对外公开
- ❌ **禁止逆向工程** - 严禁对软件包进行反编译、逆向工程或反汇编
- ❌ **禁止源码分发** - 不得以任何形式获取、复制或分发源代码
- ❌ **禁止修改重发布** - 不得修改软件包后重新发布

**简而言之**：您可以自由使用我们的软件包（包括商业用途），但请尊重我们的源代码知识产权。

---

## 📧 联系我们

- **官网**: [https://www.ailingues.com](https://www.ailingues.com)
- **邮箱**: support@ailingues.com
- **技术支持**: 如有问题或建议，请通过邮箱联系我们

---

**Made with ❤️ by AI Lingues Team**