Metadata-Version: 2.4
Name: litefs
Version: 0.10.0
Summary: Build a web server framework using Python.
Home-page: https://github.com/leafcoder/litefs
Author: Leafcoder
Author-email: Leafcoder <leafcoder@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/leafcoder/litefs
Project-URL: Documentation, https://github.com/leafcoder/litefs#readme
Project-URL: Repository, https://github.com/leafcoder/litefs
Project-URL: Issues, https://github.com/leafcoder/litefs/issues
Keywords: web,server,wsgi,http,framework
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: CGI Tools/Libraries
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: argh>=0.26.2
Requires-Dist: greenlet>=0.4.13
Requires-Dist: Mako>=1.0.6
Requires-Dist: MarkupSafe>=1.1.1
Requires-Dist: orjson>=3.10
Requires-Dist: PyYAML>=5.1
Requires-Dist: watchdog>=0.8.3
Requires-Dist: SQLAlchemy>=2.0.0
Provides-Extra: wsgi
Requires-Dist: gunicorn>=20.1.0; extra == "wsgi"
Requires-Dist: uwsgi>=2.0.20; extra == "wsgi"
Requires-Dist: waitress>=2.1.0; extra == "wsgi"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: prometheus-client>=0.20.0; extra == "dev"
Requires-Dist: alembic>=1.13.0; extra == "dev"
Requires-Dist: pymemcache>=4.0.0; extra == "dev"
Requires-Dist: redis>=5.0.0; extra == "dev"
Requires-Dist: celery>=5.3.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.3; extra == "dev"
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.20.0; extra == "prometheus"
Provides-Extra: db
Requires-Dist: alembic>=1.13.0; extra == "db"
Provides-Extra: mail
Requires-Dist: celery>=5.3.0; extra == "mail"
Provides-Extra: docs
Requires-Dist: sphinx>=9.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
Requires-Dist: myst-parser>=3.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == "docs"
Provides-Extra: performance
Requires-Dist: memory-profiler>=0.60.0; extra == "performance"
Requires-Dist: line-profiler>=3.5.0; extra == "performance"
Requires-Dist: locust>=2.15.0; extra == "performance"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "performance"
Requires-Dist: psutil>=5.9.0; extra == "performance"
Requires-Dist: py-spy>=0.3.14; extra == "performance"
Requires-Dist: pytest-xdist>=3.0.0; extra == "performance"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: platform
Dynamic: requires-python

<div align="center">

# Litefs

<p>
    <!-- Place this tag where you want the button to render. -->
    <a class="github-button" href="https://github.com/leafcoder/litefs/subscription" data-color-scheme="no-preference: light; light: light; dark: dark;" data-show-count="true" aria-label="Watch leafcoder/litefs on GitHub">
        <img alt="GitHub forks" src="https://img.shields.io/github/watchers/leafcoder/litefs?style=social">
    </a>
    <a class="github-button" href="https://github.com/leafcoder/litefs" data-color-scheme="no-preference: light; light: light; dark: dark;" data-show-count="true" aria-label="Star leafcoder/litefs on GitHub">
        <img alt="GitHub forks" src="https://img.shields.io/github/stars/leafcoder/litefs?style=social">
    </a>
    <a class="github-button" href="https://github.com/leafcoder/litefs/fork" data-color-scheme="no-preference: light; light: light; dark: dark;" data-show-count="true" aria-label="Fork leafcoder/litefs on GitHub">
        <img alt="GitHub forks" src="https://img.shields.io/github/forks/leafcoder/litefs?style=social">
    </a>
</p>

<p>
    <img src="https://img.shields.io/github/v/release/leafcoder/litefs" data-origin="https://img.shields.io/github/v/release/leafcoder/litefs" alt="GitHub release (latest by date)">
    <img src="https://img.shields.io/github/languages/top/leafcoder/litefs" data-origin="https://img.shields.io/github/languages/top/leafcoder/litefs" alt="GitHub top language">
    <img src="https://img.shields.io/github/languages/code-size/leafcoder/litefs" data-origin="https://img.shields.io/github/languages/code-size/leafcoder/litefs" alt="GitHub code size in bytes">
    <img src="https://img.shields.io/github/commit-activity/w/leafcoder/litefs" data-origin="https://img.shields.io/github/commit-activity/w/leafcoder/litefs" alt="GitHub commit activity">
    <img src="https://img.shields.io/pypi/dm/litefs" data-origin="https://img.shields.io/pypi/dm/litefs" alt="PyPI - Downloads">
</p>

</div>

Litefs 是一个轻量级的 Python Web 框架，提供高性能的 HTTP 服务器、现代路由系统、WSGI/ASGI 支持、中间件系统、缓存管理等功能。

## 🌟 特性亮点

- **高性能 HTTP 服务器** - 支持 epoll、greenlet 和 asyncio
- **现代路由系统** - 装饰器风格、方法链风格，支持路径参数
- **WSGI/ASGI 兼容** - 支持 Gunicorn、Uvicorn、UWSGI 等服务器
- **中间件系统** - 日志、安全、CORS、限流、健康检查
- **多级缓存** - Memory、Tree、Redis、Database、Memcache 后端
- **会话管理** - Database、Redis、Memcache 后端支持
- **认证授权** - JWT Token、OAuth2 社交登录（GitHub、Google、微信、企业微信）
- **WebSocket 支持** - 实时通信、房间管理、心跳检测
- **Celery 集成** - 异步任务队列、定时任务
- **OpenAPI 文档** - 自动生成 Swagger UI 文档
- **静态文件服务** - 自动 MIME 类型、安全防护、子路径访问
- **健康检查** - 内置健康检查端点
- **文件监控** - 热重载支持
- **Python 3.8+ 支持** - 兼容多个 Python 版本

## 📖 文档

**完整文档已迁移至 Docsify：**

- 🌐 [在线文档](https://leafcoder.github.io/litefs/) - 基于 Docsify 的完整文档
- 📚 [文档目录](docs/README.md) - 本地文档导航
- 📝 [快速开始](docs/source/getting-started.md) - 安装和基本使用
- 🗺️ [路由系统](docs/source/routing-guide.md) - 装饰器和方法链风格路由
- 🛠️ [中间件](docs/source/middleware-guide.md) - 内置和自定义中间件
- 💾 [缓存系统](docs/source/cache-system.md) - 多级缓存管理
- 🔐 [认证授权](docs/source/auth-system.md) - JWT 和 OAuth2 社交登录
- 🔄 [WebSocket](docs/source/websocket.md) - 实时通信
- ⚡ [Celery 集成](docs/source/celery-integration.md) - 异步任务队列
- 📖 [OpenAPI 文档](docs/source/openapi-integration.md) - 自动生成 API 文档
- 🛡️ [会话管理](docs/source/session-management.md) - Session 后端和使用
- 🚀 [WSGI 部署](docs/source/wsgi-deployment.md) - Gunicorn、uWSGI 部署
- ⚡ [ASGI 部署](docs/source/asgi-deployment.md) - Uvicorn、Daphne 部署

## 🚀 快速开始

### 安装

```bash
pip install litefs
```

或从源码安装：

```bash
git clone https://github.com/leafcoder/litefs.git
cd litefs
pip install -r requirements.txt
python setup.py install
```

### 基本示例

#### 装饰器风格

```python
from litefs.core import Litefs
from litefs.routing import get, post

app = Litefs(host='0.0.0.0', port=8080, debug=True)

@get('/', name='index')
def index_handler(request):
    return 'Hello, World!'

@get('/user/{id}', name='user_detail')
def user_detail_handler(request, id):
    return f'User ID: {id}'

@post('/login', name='login')
def login_handler(request):
    username = request.data.get('username')
    password = request.data.get('password')
    return {'status': 'success', 'username': username}

app.register_routes(__name__)
app.run()
```

#### 方法链风格

```python
from litefs.core import Litefs

app = Litefs()

def index_handler(request):
    return 'Hello, World!'

def user_detail_handler(request, id):
    return f'User ID: {id}'

app.add_get('/', index_handler, name='index')
app.add_get('/user/{id}', user_detail_handler, name='user_detail')

app.run()
```

### WSGI 部署

创建 `wsgi.py`：

```python
from litefs.core import Litefs

app = Litefs()

@get('/', name='index')
def index_handler(request):
    return 'Hello, World!'

application = app.wsgi()
```

使用 Gunicorn：

```bash
gunicorn -w 4 -b :8000 wsgi:application
```

使用 Uvicorn (ASGI)：

```bash
uvicorn asgi:application --host 0.0.0.0 --port 8000 --workers 4
```

## 📁 项目结构

```
litefs/
├── README.md              # 项目说明
├── pyproject.toml         # 项目配置
├── setup.py               # 安装脚本
├── docs/                  # 文档目录
│   ├── README.md         # 文档导航
│   └── source/           # 文档源文件
│       ├── getting-started.md
│       ├── routing-guide.md
│       ├── middleware-guide.md
│       ├── auth-system.md
│       ├── websocket.md
│       ├── celery-integration.md
│       ├── openapi-integration.md
│       └── ...
├── examples/              # 示例代码
│   ├── 01-quickstart/
│   ├── 02-rest-api/
│   ├── 03-web-app/
│   ├── 04-realtime/
│   └── 05-production/
├── src/litefs/            # 源代码
│   ├── __init__.py
│   ├── core.py
│   ├── routing/
│   ├── middleware/
│   ├── auth/
│   ├── websocket/
│   ├── tasks/
│   ├── openapi/
│   ├── cache/
│   ├── session/
│   └── ...
└── tests/                 # 测试代码
    ├── unit/
    ├── integration/
    └── performance/
```

## 📚 示例代码

Litefs 提供了丰富的示例，按照功能模块组织：

- [01-quickstart](examples/01-quickstart/) - 快速入门示例
- [02-rest-api](examples/02-rest-api/) - REST API 示例
- [03-web-app](examples/03-web-app/) - 完整的 Web 应用示例（博客系统）
- [04-realtime](examples/04-realtime/) - 实时通信示例（WebSocket 聊天室）
- [05-production](examples/05-production/) - 生产环境部署示例（Docker + Celery）

每个示例都包含详细的 README 文档和可运行的代码，请参考 [examples/README.md](examples/README.md) 了解更多。

## 📊 性能测试

LiteFS 提供完整的性能测试套件，支持多种服务器模式和部署方案的对比测试。

### 测试矩阵

| 服务器形式 | 单进程 | 多进程 | 测试场景 |
|-----------|--------|--------|---------|
| **LiteFS HttpServer** | ✅ | ✅ (4/8 Worker) | Hello World |
| **LiteFS + Gunicorn (gevent)** | ✅ | ✅ (4/8 Worker) | Hello World |
| **FastAPI + Gunicorn + UvicornWorker** (对照组) | ✅ | ✅ (4/8 Worker) | Hello World |
| **FastAPI + Uvicorn** (对照组) | ✅ | ✅ (4/8 Worker) | Hello World |

### 性能测试结果

> 测试环境: 12 核 CPU, Python 3.10.9, Linux 6.18
> 测试工具: Apache Benchmark (ab), 10000 请求, 3 次迭代取中位数
> 测试时间: 2026-05-19

#### 1 Worker 性能对比 (req/s)

| 并发数 | LiteFS+HttpServer | LiteFS+Gunicorn | FastAPI+Gunicorn+Uvicorn | FastAPI+Uvicorn | 优势倍数 (HS vs GU) |
|--------|-------------------|-----------------|--------------------------|-----------------|---------------------|
| 100 | **7,977** | 5,259 | 2,804 | 2,984 | **2.84x** |
| 500 | 4,865 | **5,272** | 3,071 | 2,388 | **1.58x** |
| 1000 | **6,068** | 5,076 | 2,777 | 2,692 | **2.18x** |

#### 4 Worker 性能对比 (req/s)

| 并发数 | LiteFS+HttpServer | LiteFS+Gunicorn | FastAPI+Gunicorn+Uvicorn | FastAPI+Uvicorn | 优势倍数 (HS vs GU) |
|--------|-------------------|-----------------|--------------------------|-----------------|---------------------|
| 100 | **15,851** | 13,117 | 3,861 | 5,019 | **4.10x** |
| 500 | 9,895 | **10,133** | 5,906 | 5,228 | **1.67x** |
| 1000 | **12,783** | 6,666 | 4,662 | 6,001 | **2.74x** |

#### 8 Worker 性能对比 (req/s)

| 并发数 | LiteFS+HttpServer | LiteFS+Gunicorn | FastAPI+Gunicorn+Uvicorn | FastAPI+Uvicorn | 优势倍数 (HS vs GU) |
|--------|-------------------|-----------------|--------------------------|-----------------|---------------------|
| 100 | **19,590** | 13,706 | 5,316 | 6,845 | **3.68x** |
| 500 | **12,291** | 7,121 | 6,798 | 5,905 | **1.80x** |
| 1000 | **11,518** | 9,952 | 6,710 | 6,742 | **1.71x** |

#### 性能特点

- **LiteFS HttpServer 最高 RPS**: 8 Worker / 100 并发下达 19,590 req/s
- **多 Worker 扩展性优异**: 从 1 Worker 到 8 Worker，RPS 提升 2.5 倍
- **低并发优势最大**: 100 并发下 LiteFS HttpServer 是 FastAPI 的 2.8~4.1 倍
- **高并发依然领先**: 即使 1000 并发，LiteFS 仍保持 1.7~2.7 倍优势
- **内置服务器最优**: LiteFS HttpServer 在所有场景下均优于 Gunicorn 部署

### 快速开始

```bash
# 进入测试目录
cd tests/performance

# 运行完整性能测试
bash run_test.sh

# 测试完成后查看报告
cat performance_report.md
```

### 测试配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 总请求数 | 10,000 | ab -n 参数 |
| 预热请求数 | 1,000 | 消除冷启动影响 |
| 迭代次数 | 3 | 取中位数减少波动 |
| 并发级别 | 100 / 500 / 1000 | ab -c 参数 |
| Worker 数 | 1 / 4 / 8 | 多进程对比 |
| 冷却间隔 | 2s | 确保端口完全释放 |

### 输出报告

测试完成后在 `tests/performance/` 目录生成:

- `performance_report.md` - 详细性能测试报告
- `test_results/` - 原始测试数据

报告包含：
- 各部署模式 RPS 性能对比
- 多 Worker / 多并发级别交叉对比
- LiteFS vs FastAPI 优势倍数
- 性能分析及建议

---

## 🧪 测试

运行单元测试：

```bash
pytest tests/unit/ -v --cov=litefs --cov-report=html
```

运行性能测试：

```bash
cd tests/performance && bash run_test.sh
```

查看测试覆盖率：

```bash
make coverage
```

## 📊 测试覆盖率

当前测试覆盖率：**52%**

目标：**80%+**

详细测试报告见 [单元测试文档](docs/source/unit-tests.md)。

## 🔧 开发指南

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/leafcoder/litefs.git
cd litefs

# 安装依赖
pip install -r requirements.txt

# 安装开发依赖
pip install -r requirements-dev.txt

# 运行测试
pytest

# 构建文档
make docs-build

# 运行文档服务器
make docs-serve
```

### 代码规范

- 遵循 PEP8 规范
- 使用类型注解
- 编写单元测试
- 保持文档更新

## 🤝 贡献

欢迎贡献代码、文档和建议！

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

## 📄 License

MIT License - 详见 [LICENSE](LICENSE) 文件。

## 🔗 相关链接

- [GitHub 仓库](https://github.com/leafcoder/litefs)
- [PyPI 包](https://pypi.org/project/litefs/)
- [在线文档](https://leafcoder.github.io/litefs/)
- [问题反馈](https://github.com/leafcoder/litefs/issues)

---

<div align="center">
    <p>如果这个项目对你有帮助，请给一个 ⭐️ Star 支持！</p>
</div>
