Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
86 lines
2.4 KiB
Python
86 lines
2.4 KiB
Python
"""Option 类型：显式表示"无结果"语义。
|
||
|
||
替代 ``T | None`` 表示"无结果"的隐式语义，遵循 §7.3"端口不得返回 null
|
||
表示'无结果'"。提供 ``Some[T]`` 与 ``Nothing`` 两个不可变值，调用方通过
|
||
``is_some()`` / ``is_nothing()`` / ``unwrap()`` / ``unwrap_or(default)``
|
||
方法安全访问。
|
||
|
||
关联约束：CON-015 / CON-019 / CON-021 / CON-027（被驱动端口不得以
|
||
``T | None`` 表示"无结果"）。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from typing import NoReturn, TypeVar
|
||
|
||
from yuxi.channels.contract.errors import InternalError
|
||
|
||
T = TypeVar("T")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Some[T]:
|
||
"""有值的 Option。
|
||
|
||
字段：
|
||
value: 被包装的实际值。
|
||
"""
|
||
|
||
value: T
|
||
|
||
def is_some(self) -> bool:
|
||
"""是否为有值状态。"""
|
||
return True
|
||
|
||
def is_nothing(self) -> bool:
|
||
"""是否为无值状态。"""
|
||
return False
|
||
|
||
def unwrap(self) -> T:
|
||
"""取出内部值。"""
|
||
return self.value
|
||
|
||
def unwrap_or(self, default: T) -> T:
|
||
"""取出内部值，无值时返回默认值（``Some`` 始终有值，故忽略 default）。"""
|
||
return self.value
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Nothing:
|
||
"""无值的 Option。
|
||
|
||
值相等语义：无字段 frozen dataclass，任意两个 ``Nothing`` 实例相等且
|
||
可哈希。用于替代 ``None`` 表示"无结果"，由端口在未查询到结果时返回。
|
||
"""
|
||
|
||
def is_some(self) -> bool:
|
||
"""是否为有值状态。"""
|
||
return False
|
||
|
||
def is_nothing(self) -> bool:
|
||
"""是否为无值状态。"""
|
||
return True
|
||
|
||
def unwrap(self) -> NoReturn:
|
||
"""取出内部值。
|
||
|
||
@raise InternalError ``Nothing`` 无内部值，在 ``Nothing`` 上调用
|
||
``unwrap()`` 属于编程误用，抛出契约层 ``InternalError``。
|
||
"""
|
||
raise InternalError(message="Cannot unwrap Nothing")
|
||
|
||
def unwrap_or[T](self, default: T) -> T:
|
||
"""取出内部值，无值时返回默认值。
|
||
|
||
@param default: 默认值。
|
||
@return 默认值。
|
||
"""
|
||
return default
|
||
|
||
|
||
# Option 类型别名：``Some[T] | Nothing``，供端口签名使用。
|
||
# 通过 PEP 695 ``type`` 语句声明泛型别名，``Option[str]`` 等下标用法
|
||
# 可被类型检查器识别为 ``Some[str] | Nothing``。
|
||
type Option[T] = Some[T] | Nothing
|