lilywhite 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lilywhite-0.1.0/LICENSE +21 -0
- lilywhite-0.1.0/PKG-INFO +232 -0
- lilywhite-0.1.0/README.md +207 -0
- lilywhite-0.1.0/lilywhite/__init__.py +19 -0
- lilywhite-0.1.0/lilywhite/__main__.py +61 -0
- lilywhite-0.1.0/lilywhite/app/__init__.py +7 -0
- lilywhite-0.1.0/lilywhite/app/application.py +82 -0
- lilywhite-0.1.0/lilywhite/app/container.py +359 -0
- lilywhite-0.1.0/lilywhite/app/discovery.py +83 -0
- lilywhite-0.1.0/lilywhite/app/exception_hooks.py +66 -0
- lilywhite-0.1.0/lilywhite/app/http.py +41 -0
- lilywhite-0.1.0/lilywhite/app/lifespan.py +107 -0
- lilywhite-0.1.0/lilywhite/app/main.py +143 -0
- lilywhite-0.1.0/lilywhite/app/runtime.py +65 -0
- lilywhite-0.1.0/lilywhite/banner.py +38 -0
- lilywhite-0.1.0/lilywhite/config.py +153 -0
- lilywhite-0.1.0/lilywhite/controller/__init__.py +5 -0
- lilywhite-0.1.0/lilywhite/controller/middleware/__init__.py +1 -0
- lilywhite-0.1.0/lilywhite/controller/middleware/metrics.py +71 -0
- lilywhite-0.1.0/lilywhite/controller/operations.py +51 -0
- lilywhite-0.1.0/lilywhite/controller/registry.py +47 -0
- lilywhite-0.1.0/lilywhite/controller/result.py +171 -0
- lilywhite-0.1.0/lilywhite/domain/__init__.py +1 -0
- lilywhite-0.1.0/lilywhite/domain/json.py +53 -0
- lilywhite-0.1.0/lilywhite/health.py +92 -0
- lilywhite-0.1.0/lilywhite/lifecycle.py +19 -0
- lilywhite-0.1.0/lilywhite/logger.py +193 -0
- lilywhite-0.1.0/lilywhite/metrics.py +131 -0
- lilywhite-0.1.0/lilywhite/observability/__init__.py +5 -0
- lilywhite-0.1.0/lilywhite/observability/log_stream.py +186 -0
- lilywhite-0.1.0/lilywhite/services/__init__.py +1 -0
- lilywhite-0.1.0/lilywhite/services/health.py +32 -0
- lilywhite-0.1.0/lilywhite/services/log.py +35 -0
- lilywhite-0.1.0/lilywhite/services/registry.py +59 -0
- lilywhite-0.1.0/lilywhite/services/result.py +43 -0
- lilywhite-0.1.0/lilywhite/storage/__init__.py +5 -0
- lilywhite-0.1.0/lilywhite/storage/memory/__init__.py +1 -0
- lilywhite-0.1.0/lilywhite/storage/registry.py +49 -0
- lilywhite-0.1.0/lilywhite/utils/__init__.py +1 -0
- lilywhite-0.1.0/lilywhite/utils/clock.py +34 -0
- lilywhite-0.1.0/lilywhite/utils/component.py +70 -0
- lilywhite-0.1.0/lilywhite/utils/random.py +26 -0
- lilywhite-0.1.0/lilywhite/utils/registry.py +76 -0
- lilywhite-0.1.0/lilywhite/utils/tasks.py +96 -0
- lilywhite-0.1.0/pyproject.toml +128 -0
- lilywhite-0.1.0/pyproject.toml.orig +85 -0
lilywhite-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 西行寺幽幽子
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
lilywhite-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: lilywhite
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: LilyWhite:基于 Litestar 与 Uvicorn 的 Pythonic 服务端框架
|
|
5
|
+
Keywords: litestar,uvicorn,dependency-injection,ioc,asgi,touhou
|
|
6
|
+
Author: SaigyoujYuyuko
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Framework :: AsyncIO
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
|
|
16
|
+
Requires-Dist: litestar>=2.25
|
|
17
|
+
Requires-Dist: loguru>=0.7
|
|
18
|
+
Requires-Dist: msgspec>=0.19
|
|
19
|
+
Requires-Dist: pyyaml>=6.0
|
|
20
|
+
Requires-Dist: uvicorn>=0.30
|
|
21
|
+
Requires-Python: >=3.14
|
|
22
|
+
Project-URL: Homepage, https://github.com/SaigyoujYuyuko/lilywhite
|
|
23
|
+
Project-URL: Repository, https://github.com/SaigyoujYuyuko/lilywhite
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# LilyWhite Framework
|
|
27
|
+
|
|
28
|
+
> 春が来た。
|
|
29
|
+
>
|
|
30
|
+
> 基于 Litestar + Uvicorn 的 Python 服务端框架。
|
|
31
|
+
> 你理解为 **Python 版 Spring** 就行!
|
|
32
|
+
|
|
33
|
+
装饰器一贴,构造器一写,剩下的交给容器。分层、DI、生命周期、多存储后端,都已经替你备好了。
|
|
34
|
+
|
|
35
|
+
没有代理、AOP 和字节码魔法,容器本身就是普通 Python 代码,想看随时能看懂。
|
|
36
|
+
|
|
37
|
+
Lily White 是报春妖精。这个框架也想做点类似的事:把 Spring 的开发体验带进 Python,再涂上一点幻想乡的颜色。
|
|
38
|
+
|
|
39
|
+
## 先来跑一下
|
|
40
|
+
|
|
41
|
+
准备 Python 3.14+ 和 uv:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
uv sync
|
|
45
|
+
cp -n config.example.yaml config.yaml
|
|
46
|
+
uv run python -m example
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
PowerShell 复制配置:
|
|
50
|
+
|
|
51
|
+
```powershell
|
|
52
|
+
Copy-Item config.example.yaml config.yaml
|
|
53
|
+
uv run python -m example
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
然后打开:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
问候接口 http://127.0.0.1:8000/api/v1/greetings/幻想乡
|
|
60
|
+
健康检查 http://127.0.0.1:8000/healthz
|
|
61
|
+
请求指标 http://127.0.0.1:8000/metrics
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
启动时会打印彩色 Banner、当前地址和实际启用的后端。
|
|
65
|
+
|
|
66
|
+
## 写个入口类
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
# example/application.py
|
|
70
|
+
from lilywhite import LilywhiteMain
|
|
71
|
+
|
|
72
|
+
@LilywhiteMain
|
|
73
|
+
class ExampleApplication:
|
|
74
|
+
application_name = "LilyWhite Greeting Example"
|
|
75
|
+
application_version = "0.1.0"
|
|
76
|
+
backends = ("memory",)
|
|
77
|
+
|
|
78
|
+
async def on_startup(self) -> None:
|
|
79
|
+
...
|
|
80
|
+
|
|
81
|
+
async def on_shutdown(self) -> None:
|
|
82
|
+
...
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`application_name` 和 `application_version` 会出现在 Banner 上,`backends` 是默认存储后端。
|
|
86
|
+
|
|
87
|
+
想加点自己的启动逻辑,就写 `on_startup()`;需要收拾资源,就写 `on_shutdown()`。同步、异步都可以,框架会把它们接进生命周期。
|
|
88
|
+
|
|
89
|
+
再用 `run()` 启动:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
# example/__main__.py
|
|
93
|
+
from lilywhite import run
|
|
94
|
+
from .application import ExampleApplication
|
|
95
|
+
|
|
96
|
+
if __name__ == "__main__":
|
|
97
|
+
run(ExampleApplication)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
入口类在哪个顶层包,`run()` 就扫描哪个包里的 `controller`、`services` 和 `storage`。
|
|
101
|
+
|
|
102
|
+
### 换个 ASGI 服务器也行
|
|
103
|
+
|
|
104
|
+
`@LilywhiteMain` 会给入口类注入 ASGI `__call__()`,所以入口实例本身就是应用:
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
import uvicorn
|
|
108
|
+
from example.application import ExampleApplication
|
|
109
|
+
|
|
110
|
+
uvicorn.run(ExampleApplication(), host="127.0.0.1", port=8000)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Litestar 应用会在首次调用时创建并缓存,HTTP、WebSocket 和 lifespan 都走同一个实例。外部服务器自己指定监听地址时,Banner 会把地址管理交给它。
|
|
114
|
+
|
|
115
|
+
## 业务怎么写
|
|
116
|
+
|
|
117
|
+
装饰器都可以从顶层拿到:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from lilywhite import component, controller, repository, service
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Controller
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
@controller("/api/v1")
|
|
127
|
+
class GreetingController(Controller):
|
|
128
|
+
@get("/greetings/{name:str}")
|
|
129
|
+
async def greeting(self, name: str) -> Response[HttpResult]:
|
|
130
|
+
...
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
根路径直接写在装饰器里。裸写 `@controller`,默认就是 `/`。
|
|
134
|
+
|
|
135
|
+
Controller 管 HTTP 参数和结果映射,Service 通过 `NamedDependency[具体Service]` 注入。完整例子在 `example/controller/greeting.py`。
|
|
136
|
+
|
|
137
|
+
### Service
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
@service
|
|
141
|
+
class GreetingService:
|
|
142
|
+
def __init__(self, greeting_repository: GreetingRepository) -> None:
|
|
143
|
+
self._greeting_repository = greeting_repository
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
需要什么依赖,就写进构造器。Service 里不用关心它来自内存、MySQL 还是别的存储。
|
|
147
|
+
|
|
148
|
+
### Repository 与 Adapter
|
|
149
|
+
|
|
150
|
+
接口放在业务包的 `storage/`,实现放进对应后端子包:
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
@repository(GreetingRepository, backend="memory")
|
|
154
|
+
class MemoryGreetingRepository:
|
|
155
|
+
...
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
在 `example/storage/__init__.py` 里声明有哪些后端:
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
backend_packages = ("memory",)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
启动时选一个,或者多选:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
uv run python -m example --backend memory
|
|
168
|
+
uv run python -m example --backend mysql --backend redis
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
容器会按 Repository Interface 找出实现。多个后端同时提供同一个接口时,启动会直接告诉你发生了冲突。
|
|
172
|
+
|
|
173
|
+
### 托管组件
|
|
174
|
+
|
|
175
|
+
需要随应用启动和关闭的组件,实现 `ManagedComponent`:
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
@component
|
|
179
|
+
class MyComponent:
|
|
180
|
+
async def initialize(self) -> None: ...
|
|
181
|
+
async def close(self) -> None: ...
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Singleton 组件会正序启动、逆序关闭,并出现在 `/healthz` 的组件状态里。
|
|
185
|
+
|
|
186
|
+
## 目录长这样
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
lilywhite/ 框架本体
|
|
190
|
+
app/ 入口、ASGI、DI、发现和生命周期
|
|
191
|
+
controller/ Controller、统一结果、SSE 和 HTTP 中间件
|
|
192
|
+
services/ 通用 Service、结果模型和 @service
|
|
193
|
+
storage/ @repository 和后端解析
|
|
194
|
+
domain/ 通用类型
|
|
195
|
+
observability/ 日志历史和异步订阅
|
|
196
|
+
utils/ @component、注册表、任务、时钟和随机源
|
|
197
|
+
config.py 配置模型和 YAML 加载
|
|
198
|
+
logger.py Loguru 配置
|
|
199
|
+
health.py 组件健康状态
|
|
200
|
+
metrics.py 请求指标
|
|
201
|
+
banner.py 东方主题彩色 Banner
|
|
202
|
+
|
|
203
|
+
example/ 问候示例
|
|
204
|
+
application.py @LilywhiteMain 入口类
|
|
205
|
+
__main__.py 命令行启动
|
|
206
|
+
controller/ 问候 Controller
|
|
207
|
+
services/ 问候 Service
|
|
208
|
+
storage/ Repository 接口与内存 Adapter
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## 配置
|
|
212
|
+
|
|
213
|
+
`config.example.yaml` 是公共示例,`config.yaml` 留给你自己的环境,不会进 Git。
|
|
214
|
+
|
|
215
|
+
- `server`:监听地址、端口、CORS。
|
|
216
|
+
- `logging`:日志级别、控制台、文件轮转与压缩。
|
|
217
|
+
- `operations`:指标窗口和实时日志 Token。
|
|
218
|
+
|
|
219
|
+
配置分区是不可变的 `msgspec.Struct`。新增分区后,容器可以按具体 Properties 类型注入。
|
|
220
|
+
|
|
221
|
+
## 开发
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
uv sync --locked
|
|
225
|
+
uv run pytest tests -q
|
|
226
|
+
uv run ruff format --check lilywhite example tests
|
|
227
|
+
uv run ruff check lilywhite example tests
|
|
228
|
+
uv run mypy
|
|
229
|
+
uv build
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`uv build` 会生成源码包和 wheel,发行包里只有 `lilywhite` 框架本体。
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# LilyWhite Framework
|
|
2
|
+
|
|
3
|
+
> 春が来た。
|
|
4
|
+
>
|
|
5
|
+
> 基于 Litestar + Uvicorn 的 Python 服务端框架。
|
|
6
|
+
> 你理解为 **Python 版 Spring** 就行!
|
|
7
|
+
|
|
8
|
+
装饰器一贴,构造器一写,剩下的交给容器。分层、DI、生命周期、多存储后端,都已经替你备好了。
|
|
9
|
+
|
|
10
|
+
没有代理、AOP 和字节码魔法,容器本身就是普通 Python 代码,想看随时能看懂。
|
|
11
|
+
|
|
12
|
+
Lily White 是报春妖精。这个框架也想做点类似的事:把 Spring 的开发体验带进 Python,再涂上一点幻想乡的颜色。
|
|
13
|
+
|
|
14
|
+
## 先来跑一下
|
|
15
|
+
|
|
16
|
+
准备 Python 3.14+ 和 uv:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
uv sync
|
|
20
|
+
cp -n config.example.yaml config.yaml
|
|
21
|
+
uv run python -m example
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
PowerShell 复制配置:
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
Copy-Item config.example.yaml config.yaml
|
|
28
|
+
uv run python -m example
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
然后打开:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
问候接口 http://127.0.0.1:8000/api/v1/greetings/幻想乡
|
|
35
|
+
健康检查 http://127.0.0.1:8000/healthz
|
|
36
|
+
请求指标 http://127.0.0.1:8000/metrics
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
启动时会打印彩色 Banner、当前地址和实际启用的后端。
|
|
40
|
+
|
|
41
|
+
## 写个入口类
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
# example/application.py
|
|
45
|
+
from lilywhite import LilywhiteMain
|
|
46
|
+
|
|
47
|
+
@LilywhiteMain
|
|
48
|
+
class ExampleApplication:
|
|
49
|
+
application_name = "LilyWhite Greeting Example"
|
|
50
|
+
application_version = "0.1.0"
|
|
51
|
+
backends = ("memory",)
|
|
52
|
+
|
|
53
|
+
async def on_startup(self) -> None:
|
|
54
|
+
...
|
|
55
|
+
|
|
56
|
+
async def on_shutdown(self) -> None:
|
|
57
|
+
...
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`application_name` 和 `application_version` 会出现在 Banner 上,`backends` 是默认存储后端。
|
|
61
|
+
|
|
62
|
+
想加点自己的启动逻辑,就写 `on_startup()`;需要收拾资源,就写 `on_shutdown()`。同步、异步都可以,框架会把它们接进生命周期。
|
|
63
|
+
|
|
64
|
+
再用 `run()` 启动:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
# example/__main__.py
|
|
68
|
+
from lilywhite import run
|
|
69
|
+
from .application import ExampleApplication
|
|
70
|
+
|
|
71
|
+
if __name__ == "__main__":
|
|
72
|
+
run(ExampleApplication)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
入口类在哪个顶层包,`run()` 就扫描哪个包里的 `controller`、`services` 和 `storage`。
|
|
76
|
+
|
|
77
|
+
### 换个 ASGI 服务器也行
|
|
78
|
+
|
|
79
|
+
`@LilywhiteMain` 会给入口类注入 ASGI `__call__()`,所以入口实例本身就是应用:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
import uvicorn
|
|
83
|
+
from example.application import ExampleApplication
|
|
84
|
+
|
|
85
|
+
uvicorn.run(ExampleApplication(), host="127.0.0.1", port=8000)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Litestar 应用会在首次调用时创建并缓存,HTTP、WebSocket 和 lifespan 都走同一个实例。外部服务器自己指定监听地址时,Banner 会把地址管理交给它。
|
|
89
|
+
|
|
90
|
+
## 业务怎么写
|
|
91
|
+
|
|
92
|
+
装饰器都可以从顶层拿到:
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from lilywhite import component, controller, repository, service
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Controller
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
@controller("/api/v1")
|
|
102
|
+
class GreetingController(Controller):
|
|
103
|
+
@get("/greetings/{name:str}")
|
|
104
|
+
async def greeting(self, name: str) -> Response[HttpResult]:
|
|
105
|
+
...
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
根路径直接写在装饰器里。裸写 `@controller`,默认就是 `/`。
|
|
109
|
+
|
|
110
|
+
Controller 管 HTTP 参数和结果映射,Service 通过 `NamedDependency[具体Service]` 注入。完整例子在 `example/controller/greeting.py`。
|
|
111
|
+
|
|
112
|
+
### Service
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
@service
|
|
116
|
+
class GreetingService:
|
|
117
|
+
def __init__(self, greeting_repository: GreetingRepository) -> None:
|
|
118
|
+
self._greeting_repository = greeting_repository
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
需要什么依赖,就写进构造器。Service 里不用关心它来自内存、MySQL 还是别的存储。
|
|
122
|
+
|
|
123
|
+
### Repository 与 Adapter
|
|
124
|
+
|
|
125
|
+
接口放在业务包的 `storage/`,实现放进对应后端子包:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
@repository(GreetingRepository, backend="memory")
|
|
129
|
+
class MemoryGreetingRepository:
|
|
130
|
+
...
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
在 `example/storage/__init__.py` 里声明有哪些后端:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
backend_packages = ("memory",)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
启动时选一个,或者多选:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
uv run python -m example --backend memory
|
|
143
|
+
uv run python -m example --backend mysql --backend redis
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
容器会按 Repository Interface 找出实现。多个后端同时提供同一个接口时,启动会直接告诉你发生了冲突。
|
|
147
|
+
|
|
148
|
+
### 托管组件
|
|
149
|
+
|
|
150
|
+
需要随应用启动和关闭的组件,实现 `ManagedComponent`:
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
@component
|
|
154
|
+
class MyComponent:
|
|
155
|
+
async def initialize(self) -> None: ...
|
|
156
|
+
async def close(self) -> None: ...
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Singleton 组件会正序启动、逆序关闭,并出现在 `/healthz` 的组件状态里。
|
|
160
|
+
|
|
161
|
+
## 目录长这样
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
lilywhite/ 框架本体
|
|
165
|
+
app/ 入口、ASGI、DI、发现和生命周期
|
|
166
|
+
controller/ Controller、统一结果、SSE 和 HTTP 中间件
|
|
167
|
+
services/ 通用 Service、结果模型和 @service
|
|
168
|
+
storage/ @repository 和后端解析
|
|
169
|
+
domain/ 通用类型
|
|
170
|
+
observability/ 日志历史和异步订阅
|
|
171
|
+
utils/ @component、注册表、任务、时钟和随机源
|
|
172
|
+
config.py 配置模型和 YAML 加载
|
|
173
|
+
logger.py Loguru 配置
|
|
174
|
+
health.py 组件健康状态
|
|
175
|
+
metrics.py 请求指标
|
|
176
|
+
banner.py 东方主题彩色 Banner
|
|
177
|
+
|
|
178
|
+
example/ 问候示例
|
|
179
|
+
application.py @LilywhiteMain 入口类
|
|
180
|
+
__main__.py 命令行启动
|
|
181
|
+
controller/ 问候 Controller
|
|
182
|
+
services/ 问候 Service
|
|
183
|
+
storage/ Repository 接口与内存 Adapter
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## 配置
|
|
187
|
+
|
|
188
|
+
`config.example.yaml` 是公共示例,`config.yaml` 留给你自己的环境,不会进 Git。
|
|
189
|
+
|
|
190
|
+
- `server`:监听地址、端口、CORS。
|
|
191
|
+
- `logging`:日志级别、控制台、文件轮转与压缩。
|
|
192
|
+
- `operations`:指标窗口和实时日志 Token。
|
|
193
|
+
|
|
194
|
+
配置分区是不可变的 `msgspec.Struct`。新增分区后,容器可以按具体 Properties 类型注入。
|
|
195
|
+
|
|
196
|
+
## 开发
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
uv sync --locked
|
|
200
|
+
uv run pytest tests -q
|
|
201
|
+
uv run ruff format --check lilywhite example tests
|
|
202
|
+
uv run ruff check lilywhite example tests
|
|
203
|
+
uv run mypy
|
|
204
|
+
uv build
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
`uv build` 会生成源码包和 wheel,发行包里只有 `lilywhite` 框架本体。
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""LilyWhite:基于 Litestar 的 Pythonic 服务端框架。"""
|
|
2
|
+
|
|
3
|
+
from .app import LilyWhiteApplication, LilywhiteMain, run
|
|
4
|
+
from .config import AppProperties
|
|
5
|
+
from .controller.registry import controller
|
|
6
|
+
from .services.registry import service
|
|
7
|
+
from .storage.registry import repository
|
|
8
|
+
from .utils.component import component
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"AppProperties",
|
|
12
|
+
"LilyWhiteApplication",
|
|
13
|
+
"LilywhiteMain",
|
|
14
|
+
"component",
|
|
15
|
+
"controller",
|
|
16
|
+
"repository",
|
|
17
|
+
"run",
|
|
18
|
+
"service",
|
|
19
|
+
]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""通用模板的命令行与Uvicorn启动入口。"""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
import msgspec
|
|
7
|
+
import uvicorn
|
|
8
|
+
|
|
9
|
+
from .app import LilyWhiteApplication
|
|
10
|
+
from .config import ConfigLoader
|
|
11
|
+
from .logger import shutdown_logging
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def main(argv: list[str] | None = None) -> None:
|
|
15
|
+
"""加载YAML,应用命令行覆盖并启动服务端。"""
|
|
16
|
+
parser = argparse.ArgumentParser(description="LilyWhite Framework")
|
|
17
|
+
parser.add_argument("--config", type=Path, default=Path("config.yaml"))
|
|
18
|
+
parser.add_argument("--host")
|
|
19
|
+
parser.add_argument("--port", type=int)
|
|
20
|
+
parser.add_argument("--backend", action="append", help="启用后端,可重复传入")
|
|
21
|
+
parser.add_argument(
|
|
22
|
+
"--log-level",
|
|
23
|
+
type=str.upper,
|
|
24
|
+
choices=("TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"),
|
|
25
|
+
)
|
|
26
|
+
parser.add_argument("--log-file", type=Path)
|
|
27
|
+
parser.add_argument("--no-console", action="store_true")
|
|
28
|
+
args = parser.parse_args(argv)
|
|
29
|
+
|
|
30
|
+
properties = ConfigLoader(args.config).load()
|
|
31
|
+
server = msgspec.structs.replace(
|
|
32
|
+
properties.server,
|
|
33
|
+
host=properties.server.host if args.host is None else args.host,
|
|
34
|
+
port=properties.server.port if args.port is None else args.port,
|
|
35
|
+
)
|
|
36
|
+
logging = msgspec.structs.replace(
|
|
37
|
+
properties.logging,
|
|
38
|
+
level=properties.logging.level if args.log_level is None else args.log_level,
|
|
39
|
+
console=properties.logging.console and not args.no_console,
|
|
40
|
+
file=properties.logging.file if args.log_file is None else args.log_file.resolve(),
|
|
41
|
+
)
|
|
42
|
+
properties = msgspec.structs.replace(properties, server=server, logging=logging)
|
|
43
|
+
|
|
44
|
+
completed_normally = False
|
|
45
|
+
try:
|
|
46
|
+
backends = tuple(args.backend or ["memory"])
|
|
47
|
+
application = LilyWhiteApplication(properties, backends=backends).create_app()
|
|
48
|
+
uvicorn.run(
|
|
49
|
+
application,
|
|
50
|
+
host=properties.server.host,
|
|
51
|
+
port=properties.server.port,
|
|
52
|
+
log_config={"version": 1, "disable_existing_loggers": False},
|
|
53
|
+
)
|
|
54
|
+
completed_normally = True
|
|
55
|
+
finally:
|
|
56
|
+
if completed_normally:
|
|
57
|
+
shutdown_logging()
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
if __name__ == "__main__":
|
|
61
|
+
main()
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
"""应用主类,只负责入口、运行时组合和启停日志。"""
|
|
2
|
+
|
|
3
|
+
from collections.abc import AsyncGenerator, Mapping
|
|
4
|
+
from contextlib import asynccontextmanager
|
|
5
|
+
|
|
6
|
+
from litestar import Litestar
|
|
7
|
+
|
|
8
|
+
from ..banner import server_url
|
|
9
|
+
from ..config import AppProperties
|
|
10
|
+
from ..logger import LoggerManager
|
|
11
|
+
from .exception_hooks import install_exception_hooks
|
|
12
|
+
from .http import create_http_app
|
|
13
|
+
from .runtime import ApplicationRuntime
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class LilyWhiteApplication:
|
|
17
|
+
"""持有通用运行时并创建Litestar应用,不直接引用业务实现。"""
|
|
18
|
+
|
|
19
|
+
def __init__(
|
|
20
|
+
self,
|
|
21
|
+
properties: AppProperties,
|
|
22
|
+
*,
|
|
23
|
+
backends: str | tuple[str, ...] = "memory",
|
|
24
|
+
resources: Mapping[type[object], object] | None = None,
|
|
25
|
+
controller_packages: tuple[str, ...] = ("lilywhite.controller",),
|
|
26
|
+
service_package: str = "lilywhite.services",
|
|
27
|
+
storage_package: str = "lilywhite.storage",
|
|
28
|
+
application_name: str = "LilyWhite Application",
|
|
29
|
+
external_server: bool = False,
|
|
30
|
+
) -> None:
|
|
31
|
+
"""初始化日志并自动收集配置、组件和生命周期。"""
|
|
32
|
+
LoggerManager.initialize(properties.logging)
|
|
33
|
+
install_exception_hooks()
|
|
34
|
+
self._log = LoggerManager.get_logger("APP")
|
|
35
|
+
self._log.info("logging initialized")
|
|
36
|
+
self._backend = backends
|
|
37
|
+
self._application_name = application_name
|
|
38
|
+
self._url = (
|
|
39
|
+
"external ASGI server"
|
|
40
|
+
if external_server
|
|
41
|
+
else server_url(properties.server.host, properties.server.port)
|
|
42
|
+
)
|
|
43
|
+
self._runtime = ApplicationRuntime(
|
|
44
|
+
properties,
|
|
45
|
+
backends=backends,
|
|
46
|
+
resources=resources,
|
|
47
|
+
service_package=service_package,
|
|
48
|
+
storage_package=storage_package,
|
|
49
|
+
)
|
|
50
|
+
self.health_center = self._runtime.health_center
|
|
51
|
+
self.request_metrics = self._runtime.request_metrics
|
|
52
|
+
self.log_stream = self._runtime.log_stream
|
|
53
|
+
self.lifespan = self._runtime.lifespan
|
|
54
|
+
self._controller_packages = controller_packages
|
|
55
|
+
|
|
56
|
+
def create_app(self) -> Litestar:
|
|
57
|
+
"""创建与当前运行时绑定的HTTP应用。"""
|
|
58
|
+
return create_http_app(self._runtime, self._controller_packages, self._application_lifespan)
|
|
59
|
+
|
|
60
|
+
@asynccontextmanager
|
|
61
|
+
async def _application_lifespan(self, _app: Litestar) -> AsyncGenerator[None]:
|
|
62
|
+
"""启动和关闭全部托管组件,并记录服务运行状态。"""
|
|
63
|
+
try:
|
|
64
|
+
await self.lifespan.start()
|
|
65
|
+
except Exception as error:
|
|
66
|
+
self._log.error("server startup failed type={}", type(error).__name__)
|
|
67
|
+
raise
|
|
68
|
+
|
|
69
|
+
self._log.info(
|
|
70
|
+
"{}: server is running on: {}; backend: {}",
|
|
71
|
+
self._application_name,
|
|
72
|
+
self._url,
|
|
73
|
+
self._backend,
|
|
74
|
+
)
|
|
75
|
+
try:
|
|
76
|
+
yield
|
|
77
|
+
finally:
|
|
78
|
+
await self.lifespan.stop()
|
|
79
|
+
self._log.info("server shutdown complete")
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
__all__ = ["LilyWhiteApplication"]
|