欢迎来到 typelib

Python的类型工具包

typelib 提供了一个合理、非侵入性、适用于生产的工具包，用于在运行时利用Python的类型注解。

快速入门

安装

poetry add 'typelib[json]'

携带您自己的模型

我们不在乎你的数据模型是如何实现的 - 你可以使用 [dataclasses][], [TypedDict][typing.TypedDict], [NamedTuple][typing.NamedTuple]，一个普通的集合，一个自定义类，或者任何其他建模库。只要你的类型在运行时有效，我们就会支持它。

如何以及在哪里

如何：高级API

我们有一个简单的、高级API，应该可以处理大多数生产用例。

from __future__ import annotations

import dataclasses
import datetime
import decimal


import typelib

@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)
class BusinessModel:
    op: str
    value: decimal.Decimal
    id: int | None = None
    created_at: datetime.datetime | None = None
    

codec = typelib.codec(BusinessModel)
instance = codec.decode(b'{"op":"add","value":"1.0"}')
print(instance)
#> BusinessModel(op='add', value=decimal.Decimal('1.0'), id=None, created_at=None)
encoded = codec.encode(instance)
print(encoded)
#> b'{"op":"add","value":"1.0","id":null,"created_at":null}'

/// tip 想要了解更多？请查看我们的 [API参考][typelib] 以了解高级API。

在哪里：代码的边缘

你可以在代码的“边缘”集成这个库 - 例如，在应用程序与客户端或你的应用程序与数据存储之间的集成点。

from __future__ import annotations

import dataclasses
import datetime
import decimal
import operator
import random

import typelib


class ClientRPC:
    def __init__(self):
        self.codec = typelib.codec(BusinessModel)

    def call(self, inp: bytes) -> bytes:
        model = self.receive(inp)
        done = self.op(model)
        return self.send(done)

    @staticmethod
    def op(model: BusinessModel) -> BusinessModel:
        op = getattr(operator, model.op)
        return dataclasses.replace(
            model,
            value=op(model.value, model.value),
            id=random.getrandbits(64),
            created_at=datetime.datetime.now(tz=datetime.UTC)
        )

    def send(self, model: BusinessModel) -> bytes:
        return self.codec.encode(model)

    def receive(self, data: bytes) -> BusinessModel:
        return self.codec.decode(data)


@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)
class BusinessModel:
    op: str
    value: decimal.Decimal
    id: int | None = None
    created_at: datetime.datetime | None = None

在哪里：代码层之间

你可以集成这个库，以简化类型之间的转换。

from __future__ import annotations

import dataclasses
import datetime
import decimal
import typing as t


import typelib

@dataclasses.dataclass(slots=True, weakref_slot=True, kw_only=True)
class BusinessModel:
    op: str
    value: decimal.Decimal
    id: int | None = None
    created_at: datetime.datetime | None = None
    

class ClientRepr(t.TypedDict):
    op: str
    value: str
    id: str | None
    created_at: datetime.datetime | None


business_codec = typelib.codec(BusinessModel)
client_codec = typelib.codec(ClientRepr)
# Initialize your business model directly from your input.
instance = business_codec.decode(
   b'{"op":"add","value":"1.0","id":"10","created_at":"1970-01-01T00:00:00+0000}'
)
print(instance)
#> BusinessModel(op='add', value=Decimal('1.0'), id=10, created_at=datetime.datetime(1970, 1, 1, 0, 0, fold=1, tzinfo=Timezone('UTC')))
# Encode your business model into the format defined by your ClientRepr.
encoded = client_codec.encode(instance)
print(encoded)
#> b'{"op":"add","value":"1.0","id":"10","created_at":"1970-01-01T00:00:00+00:00"}'

/// tip 只要传入的实例具有相同的所需字段重叠，就不需要初始化ClientRepr实例来利用其编解码器。

1. 重叠字段中的值可以转换为目标类型。
2. 重叠字段中的值可以转换为目标类型。

为什么选择 typelib

typelib 提供了一个 简单、无侵入性API，使生产应用程序中的日常数据处理变得简单可靠。

我们提供

1. 根据类型注解进行数据序列化和反序列化的API。
2. 提供与通过网络序列化和反序列化集成的API。
3. 提供对Python类型的细粒度、高性能运行时内省。
4. 提供未来兼容性，以支持新兴的类型注解语法。

我们不要求

1. 从自定义基类继承。
2. 使用自定义类装饰器。
3. 依赖于生成的代码。

它如何工作

typelib 的实现是运行时类型分析器中独特的 - 我们使用迭代、图基解析器来构建由注解表示的类型的有预测性和静态排序。我们将我们的类型解析算法独立于我们的序列化和反序列化逻辑实现为一个简单的迭代循环，这使得逻辑易于推理。

/// tip 在这里阅读详细讨论 here。