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.
Files changed (46) hide show
  1. lilywhite-0.1.0/LICENSE +21 -0
  2. lilywhite-0.1.0/PKG-INFO +232 -0
  3. lilywhite-0.1.0/README.md +207 -0
  4. lilywhite-0.1.0/lilywhite/__init__.py +19 -0
  5. lilywhite-0.1.0/lilywhite/__main__.py +61 -0
  6. lilywhite-0.1.0/lilywhite/app/__init__.py +7 -0
  7. lilywhite-0.1.0/lilywhite/app/application.py +82 -0
  8. lilywhite-0.1.0/lilywhite/app/container.py +359 -0
  9. lilywhite-0.1.0/lilywhite/app/discovery.py +83 -0
  10. lilywhite-0.1.0/lilywhite/app/exception_hooks.py +66 -0
  11. lilywhite-0.1.0/lilywhite/app/http.py +41 -0
  12. lilywhite-0.1.0/lilywhite/app/lifespan.py +107 -0
  13. lilywhite-0.1.0/lilywhite/app/main.py +143 -0
  14. lilywhite-0.1.0/lilywhite/app/runtime.py +65 -0
  15. lilywhite-0.1.0/lilywhite/banner.py +38 -0
  16. lilywhite-0.1.0/lilywhite/config.py +153 -0
  17. lilywhite-0.1.0/lilywhite/controller/__init__.py +5 -0
  18. lilywhite-0.1.0/lilywhite/controller/middleware/__init__.py +1 -0
  19. lilywhite-0.1.0/lilywhite/controller/middleware/metrics.py +71 -0
  20. lilywhite-0.1.0/lilywhite/controller/operations.py +51 -0
  21. lilywhite-0.1.0/lilywhite/controller/registry.py +47 -0
  22. lilywhite-0.1.0/lilywhite/controller/result.py +171 -0
  23. lilywhite-0.1.0/lilywhite/domain/__init__.py +1 -0
  24. lilywhite-0.1.0/lilywhite/domain/json.py +53 -0
  25. lilywhite-0.1.0/lilywhite/health.py +92 -0
  26. lilywhite-0.1.0/lilywhite/lifecycle.py +19 -0
  27. lilywhite-0.1.0/lilywhite/logger.py +193 -0
  28. lilywhite-0.1.0/lilywhite/metrics.py +131 -0
  29. lilywhite-0.1.0/lilywhite/observability/__init__.py +5 -0
  30. lilywhite-0.1.0/lilywhite/observability/log_stream.py +186 -0
  31. lilywhite-0.1.0/lilywhite/services/__init__.py +1 -0
  32. lilywhite-0.1.0/lilywhite/services/health.py +32 -0
  33. lilywhite-0.1.0/lilywhite/services/log.py +35 -0
  34. lilywhite-0.1.0/lilywhite/services/registry.py +59 -0
  35. lilywhite-0.1.0/lilywhite/services/result.py +43 -0
  36. lilywhite-0.1.0/lilywhite/storage/__init__.py +5 -0
  37. lilywhite-0.1.0/lilywhite/storage/memory/__init__.py +1 -0
  38. lilywhite-0.1.0/lilywhite/storage/registry.py +49 -0
  39. lilywhite-0.1.0/lilywhite/utils/__init__.py +1 -0
  40. lilywhite-0.1.0/lilywhite/utils/clock.py +34 -0
  41. lilywhite-0.1.0/lilywhite/utils/component.py +70 -0
  42. lilywhite-0.1.0/lilywhite/utils/random.py +26 -0
  43. lilywhite-0.1.0/lilywhite/utils/registry.py +76 -0
  44. lilywhite-0.1.0/lilywhite/utils/tasks.py +96 -0
  45. lilywhite-0.1.0/pyproject.toml +128 -0
  46. lilywhite-0.1.0/pyproject.toml.orig +85 -0
@@ -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.
@@ -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,7 @@
1
+ """应用装配公开接口。"""
2
+
3
+ from .application import LilyWhiteApplication
4
+ from .discovery import discover_controllers
5
+ from .main import LilywhiteMain, run
6
+
7
+ __all__ = ["LilyWhiteApplication", "LilywhiteMain", "discover_controllers", "run"]
@@ -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"]