Metadata-Version: 2.4
Name: fly-common
Version: 0.1.0
Summary: 通用模块
Author-email: fly <fzkf117@163.com>
License: MIT
Keywords: utils,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotated-types==0.7.0
Requires-Dist: cffi==2.0.0
Requires-Dist: cryptography==46.0.5
Requires-Dist: ecdsa==0.19.1
Requires-Dist: passlib==1.7.4
Requires-Dist: pyasn1==0.6.3
Requires-Dist: pycparser==2.23
Requires-Dist: pydantic==2.12.5
Requires-Dist: pydantic-core==2.41.5
Requires-Dist: python-jose==3.5.0
Requires-Dist: rsa==4.9.1
Requires-Dist: six==1.17.0
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: typing-inspection==0.4.2
Dynamic: license-file

# fly-common

> 一个轻量级的 Python 公共工具库，专注于安全认证和常用工具函数

## 📖 介绍

fly-common 是一个功能精简但实用的 Python 公共库，主要提供以下核心功能：

- **JWT Token 管理**：支持对称加密（HS256）和非对称加密（RS256）的 JWT Token 生成、验证和刷新
- **密码加密**：提供 MD5、PBKDF2 等多种加密方式
- **工具函数**：提供单例模式、随机字符串生成等实用工具

## ✨ 功能特性

### 安全模块 (safety)

#### JWT Token
- 支持对称加密（HS256）和非对称加密（RS256）
- 提供 Access Token 和 Refresh Token 的生成
- Token 验证与刷新机制
- 支持自定义过期时间、签发者（issuer）和受众（audience）
- 单例模式实现，确保全局唯一实例

#### 密码加密
- MD5 加密
- PBKDF2 加密（推荐用于密码存储）
- 密码验证功能
- 随机字符串生成
- 数字验证码生成

### 工具模块 (tools)

- 线程安全的单例模式装饰器

## 📦 安装

### 环境要求

- Python >= 3.9

### 安装依赖

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

## 🚀 使用说明

### JWT Token 使用示例

#### 对称加密（HS256）

```python
from fly_common.safety.jwt_token import JWTSymmetry

# 初始化（单例模式）
jwt_sym = JWTSymmetry(
    secret_key="your-secret-key",
    access_token_expire_seconds=86400,  # 24小时
    refresh_token_expire_seconds=604800,  # 7天
    issuer="your-app",
    audience="your-users"
)

# 生成 Token
result = jwt_sym.create_at_rf_token(payload={"sub": "user123"})
if result.ok:
    access_token = result.data["access_token"]
    refresh_token = result.data["refresh_token"]

# 验证 Token
verify_result = jwt_sym.verify_token(access_token)
if verify_result.ok:
    print("Token 有效:", verify_result.data)

# 刷新 Token
refresh_result = jwt_sym.refresh_token(access_token, refresh_token)
if refresh_result.ok:
    new_tokens = refresh_result.data
```

#### 非对称加密（RS256）

```python
from fly_common.safety.jwt_token import JWTAsymmetry

# 初始化（单例模式）
jwt_asym = JWTAsymmetry(
    private_key="your-private-key",
    public_key="your-public-key",
    algorithm="RS256"
)

# 使用方式与对称加密相同
result = jwt_asym.create_at_rf_token(payload={"sub": "user123"})
```

### 密码加密使用示例

```python
from fly_common.safety.md5 import md5, en_password, check_password, code_number

# MD5 加密
hashed = md5("your-string")

# 密码加密（PBKDF2）
password_hash = en_password("user-password")

# 验证密码
is_valid = check_password("user-password", password_hash)

# 生成验证码
code = code_number(6)  # 生成6位数字验证码
```

### 单例模式使用示例

```python
from fly_common.tools.single import Singleton

@Singleton
class MyService:
    def __init__(self):
        self.data = []

# 获取实例
service1 = MyService()
service2 = MyService()

# service1 和 service2 是同一个实例
assert service1 is service2
```

## 📁 项目结构

```
fly-common/
├── safety/           # 安全模块
│   ├── jwt_token.py  # JWT Token 管理
│   └── md5.py        # 密码加密工具
├── tools/            # 工具模块
│   └── single.py     # 单例模式
└── __init__.py
```

## 🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 新建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 许可证

本项目采用 MIT 许可证
