typedload项目支持的数据类型详解

概述

typedload是一个强大的Python类型转换库，它能够将Python原生数据结构（如字典、列表等）转换为具有严格类型定义的Python对象。本文将详细介绍typedload支持的各种数据类型及其使用方式，帮助开发者更好地理解和使用这个库。

基础类型支持

typedload默认支持以下基础类型：

• int
• bool
• float
• str
• NoneType

这些类型是构建复杂数据结构的基础，typedload默认会对它们进行基本类型转换：

# 自动类型转换示例
typedload.load(1, float)  # 输出: 1.0
typedload.load(1, str)    # 输出: '1'

可以通过设置basiccast=False来禁用这种自动转换行为：

typedload.load(1, float, basiccast=False)  # 抛出TypedloadValueError异常

开发者还可以自定义基础类型集合：

typedload.load(1, bytes, basictypes={bytes, int})  # 输出: b'\x00'

复合类型支持

1. 列表(List)处理

typedload可以将任何可迭代对象转换为指定类型的列表：

typedload.load([1.1, 2, '3'], List[int])  # 输出: [1, 2, 3]

2. 元组(Tuple)处理

元组支持两种形式：

• 固定长度元组：Tuple[int, float]
• 可变长度元组：Tuple[int, ...]

typedload.load([1, 2, 3], Tuple[int, float])  # 输出: (1, 2.0)
typedload.load([1, 2, 3], Tuple[int, ...])   # 输出: (1, 2, 3)

3. 字典(Dict)处理

typedload可以确保字典键值对的类型正确：

typedload.load({1: '1'}, Dict[int, Path])  # 输出: {1: PosixPath('1')}

对象类型支持

typedload支持多种Python对象类型：

1. NamedTuple

class Point2d(NamedTuple):
    x: float
    y: float

typedload.load({'x': 1, 'y': 1}, Point2d)  # 输出: Point2d(x=1.0, y=1.0)

2. dataclass

@dataclass
class Solid:
    vertex: List[Point3d] = field(default_factory=list)
    total: int = field(init=False)

3. attrs类

@attr.s
class Polygon:
    vertex: List[Point2d] = attr.ib(factory=list)

typedload会自动处理这些对象的构造和属性赋值，并支持failonextra参数来检查多余字段。

特殊类型处理

1. 枚举(Enum)

class Flags(Enum):
    NOVAL = 0
    YESVAL = 1

typedload.load(1, Flags)  # 输出: <Flags.YESVAL: 1>

2. 字面量(Literal)

typedload.load(2, Literal[1, 2, 3])  # 成功
typedload.load(4, Literal[1, 2, 3])  # 失败

3. 类型联合(Union)

typedload.load(3, Optional[int])  # 输出: 3
typedload.load(None, Optional[int])  # 输出: None

对于复杂的Union类型，可以使用uniondebugconflict=True来检测潜在的类型冲突。

4. TypedDict

class A(TypedDict):
    val: str

typedload.load({'val': 3}, A)  # 输出: {'val': '3'}

5. 集合(Set/Frozenset)

typedload.load([1, 4, 99], set[float])  # 输出: {1.0, 4.0, 99.0}

路径和网络地址处理

typedload内置支持多种路径和网络地址类型：

1. pathlib.Path

typedload.load('/tmp/file.txt', Path)  # 输出: PosixPath('/tmp/file.txt')

2. ipaddress相关类型

typedload.load('10.1.1.3', IPv4Address)  # 输出: IPv4Address('10.1.1.3')

日期时间处理

typedload支持多种日期时间类型：

1. datetime.date/datetime.time/datetime.datetime

支持ISO 8601格式字符串或整数列表作为输入：

# ISO格式
typedload.load("2023-01-01", date)

# 整数列表格式(已弃用)
typedload.load([2023, 1, 1], date)

2. datetime.timedelta

表示为秒数的浮点数。

高级特性

1. 前向引用(Forward References)

typedload通过类型名称缓存机制支持前向引用：

a: 'ObjA' = ObjA()  # 前向引用

2. attrs转换器(Converters)

typedload会尊重attrs字段的converter函数：

@attr.s
class A:
    x: int = attr.ib(converter=str)  # 忽略int类型提示，使用converter

typedload.load({'x': [1]}, A)  # 输出: A(x='[1]')

3. NewType支持

T = NewType('T', str)
typedload.load('ciao', T)  # 输出: 'ciao'

总结

typedload提供了全面的Python类型系统支持，从基础类型到复杂对象，都能进行严格的类型检查和转换。通过合理配置各种参数，开发者可以在灵活性和严格性之间找到平衡，构建健壮的类型安全应用。

对于需要处理复杂数据结构的项目，typedload的类型转换能力可以大大简化数据验证和转换的工作量，是Python类型系统应用的强大工具。