Kris
b88c0ae29e
新增完整的 channels 限界上下文模块，包含契约层、领域核心层、应用服务、管道编排、插件体系、基础设施组合根等全层级代码，新增飞书与微信 iLink 渠道插件基础结构，补充各类 DTO、端口协议与领域服务实现。
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
|