什么是 SpaceWorld
SpaceWorld 是一个新一代的 Python CLI（命令行接口）框架，专为团队便捷开发而设计，要求 Python 3.12 及以上版本，并支持异步命令。它的核心设计理念是让命令行工具的编写尽可能简洁——开发者只需用普通的 Python 函数，加上装饰器，就能快速生成功能完备的命令行应用。
核心特性
SpaceWorld 具备以下几项关键特性：
最高速度：专为高负载应用优化，性能表现出色
高度灵活：支持自定义处理器、命令和模块
代码简洁：业务逻辑就是普通函数，框架自动处理命令行解析
**支持 *args 和 kwargs：灵活接收任意数量的参数
扩展类型注解：支持 Annotated、Literal、Union 等新式类型标注
内置验证器和转换器：可直接在类型注解中定义参数校验规则
安装
首先创建并激活虚拟环境，然后使用 pip 安装：
基本用法
最简单的例子
from spaceworld import run@rundef main(): print("Hello World")
保存为 main.py，在终端中运行：
$ python main.pyHello World$ python main.py --helpUsage: main [ARGS] [OPTIONS]None documentationOptions: --help - Displays the help on the command
只需要一个 @run 装饰器，普通函数就变成了命令行工具，而且自动生成了 --help 帮助文档。
带参数的命令
from spaceworld import run@rundef main(name: str): print(f"Hello {name}")
运行效果：
$ python main.pyERROR: Missing required argument: 'name'$ python main.py AliceHello Alice
函数参数的类型注解（name: str）被 SpaceWorld 自动识别为命令行参数。如果缺少必填参数，框架会给出清晰的错误提示。
带默认值的参数
from spaceworld import run@rundef main(name: str = "World"): print(f"Hello {name}")
运行效果：
$ python main.pyHello World$ python main.py AliceHello Alice
有默认值的参数变成可选参数，不传时使用默认值。
异步命令
SpaceWorld 原生支持异步函数，适合需要等待 I/O 操作的场景：
import asynciofrom spaceworld import run@runasync def main(second: int = 1): await asyncio.sleep(second) print(f"Hello in {second} second")
运行效果：
$ python main.py sleep 1# 等待 1 秒后输出Hello in 1 second$ python main.py sleep 5# 等待 5 秒后输出Hello in 5 second
async def 定义的函数被 @run 装饰后，框架会自动以异步方式调度执行。
参数验证
SpaceWorld 支持通过 Annotated 类型注解在参数上直接定义验证规则，无需额外编写校验代码：
from typing import Annotatedfrom spaceworld import run@rundef main( age: Annotated[ int, lambda x: x if x >= 18 else ValueError("The user must be over 18 years old") ]): print(f"Hello {age} year old")
运行效果：
$ python main.py 18Hello 18 year old$ python main.py 15ERROR: Invalid argument for 'age': Error in the Annotated validation for `15`:Arg: 15, Error: The user must be over 18 years old$ python main.py -1ERROR: Invalid argument for 'age': Error in the Annotated validation for `-1`:Arg: -1, Error: The user must be over 18 years old
Annotated 的第一个参数是基础类型（int），第二个参数是一个验证函数，接收输入值并返回有效值或抛出异常。SpaceWorld 会自动应用这些验证规则，并在失败时给出详细的错误信息。
多命令应用
SpaceWorld 支持在一个文件中定义多个子命令：
from spaceworld import run@rundef main(): """主入口""" pass@main.command()def greet(name: str = "World"): """打招呼""" print(f"Hello, {name}!")@main.command()def add(a: int, b: int): """两数相加""" print(f"{a} + {b} = {a + b}")
运行效果：
$ python main.py greet AliceHello, Alice!$ python main.py add 3 53 + 5 = 8
参数类型转换
SpaceWorld 会根据类型注解自动转换命令行参数（命令行参数默认是字符串）：
from spaceworld import run@rundef main( count: int, price: float, active: bool = True): """演示类型转换""" print(f"count: {count} (type: {type(count).__name__})") print(f"price: {price} (type: {type(price).__name__})") print(f"active: {active} (type: {type(active).__name__})")
运行效果：
$ python main.py 10 3.14 falsecount: 10 (type: int)price: 3.14 (type: float)active: False (type: bool)
流程图
下面是 SpaceWorld 应用从启动到命令执行的完整运行流程。
命令行参数解析流程
流程说明：
用户输入：在终端中键入 python main.py <args>
装饰器捕获：@run 装饰器拦截 main 函数，接管程序入口
签名解析：框架通过内省机制读取函数的参数名、类型注解和默认值
参数匹配：将命令行参数按位置与函数参数一一对应
默认值处理：未提供的参数若有默认值则自动填充，否则报错
验证校验：带有 Annotated 规则的参数会逐条执行验证逻辑
执行调度：根据函数是同步还是异步选择对应的调用方式
业务执行：运行函数体中的实际代码，输出结果
多命令路由流程
当使用 @main.command() 注册子命令后，框架会先检查第一个参数是否为已知的子命令名称；如果是则路由到对应的子命令处理函数，否则按照主命令的参数规则进行解析。
总结
SpaceWorld 的核心优势在于零样板代码：开发者只需关注业务逻辑，类型注解即接口定义，框架负责命令行解析、类型转换、验证检查和帮助文档生成。它特别适合需要快速构建 CLI 工具的团队项目，尤其是涉及异步 I/O 操作的场景。
编辑：余文彬
审校：余雨馨
10个月宝宝每天需要喝多少奶粉？
