toms-fast 0.2.1__py3-none-any.whl

tomskit/utils/fields.py

@@ -0,0 +1,434 @@
+"""
+字段类，支持从异步数据源（如异步数据库查询）获取数据。
+
+基于 flask-restful 的 fields 实现，但所有方法都是异步的，以支持异步数据获取。
+"""
+import inspect
+from calendar import timegm
+from decimal import Decimal as MyDecimal, ROUND_HALF_EVEN
+from email.utils import formatdate
+
+__all__ = [
+    "String",
+    "FormattedString",
+    "DateTime",
+    "Float",
+    "Integer",
+    "Arbitrary",
+    "Nested",
+    "List",
+    "Raw",
+    "Boolean",
+    "Fixed",
+    "Price",
+    "MarshallingException",
+]
+
+
+class MarshallingException(Exception):
+    """
+    This is an encapsulating Exception in case of marshalling error.
+    """
+
+    def __init__(self, underlying_exception):
+        # just put the contextual representation of the error to hint on what
+        # went wrong without exposing internals
+        super().__init__(str(underlying_exception))
+
+
+def is_indexable_but_not_string(obj):
+    """检查对象是否可索引但不是字符串"""
+    return not isinstance(obj, str) and hasattr(obj, "__iter__")
+
+
+async def get_value(key, obj, default=None):
+    """Helper for pulling a keyed value off various types of objects.
+    
+    支持异步属性获取，如果属性是协程对象，会自动 await。
+    """
+    if isinstance(key, int):
+        return await _get_value_for_key(key, obj, default)
+    elif callable(key):
+        value = key(obj)
+        if inspect.isawaitable(value):
+            value = await value
+        # 只检查 None，不检查其他假值（如 0, False, ''）
+        if value is None:
+            return default
+        return value
+    else:
+        return await _get_value_for_keys(key.split('.'), obj, default)
+
+
+async def _get_value_for_keys(keys, obj, default):
+    """递归获取嵌套键的值"""
+    if len(keys) == 1:
+        return await _get_value_for_key(keys[0], obj, default)
+    else:
+        intermediate_obj = await _get_value_for_key(keys[0], obj, default)
+        if intermediate_obj is None:
+            return default
+        return await _get_value_for_keys(keys[1:], intermediate_obj, default)
+
+
+async def _get_value_for_key(key, obj, default):
+    """从对象中获取单个键的值，支持异步属性"""
+    if is_indexable_but_not_string(obj):
+        try:
+            value = obj[key]
+            if inspect.isawaitable(value):
+                value = await value
+            # 只检查 None，不检查其他假值（如 0, False, ''）
+            if value is None:
+                return default
+            return value
+        except (IndexError, TypeError, KeyError):
+            pass
+    
+    # 尝试从对象属性获取值
+    if hasattr(obj, key):
+        value = getattr(obj, key)
+        if inspect.isawaitable(value):
+            value = await value
+        return value
+    
+    # 如果属性不存在，返回 default
+    # 如果 default 是协程，也需要 await
+    if inspect.isawaitable(default):
+        return await default
+    return default
+
+
+async def to_marshallable_type(obj):
+    """Helper for converting an object to a dictionary only if it is not
+    dictionary already or an indexable object nor a simple type.
+    
+    支持异步的 __marshallable__ 方法。
+    """
+    if obj is None:
+        return None  # make it idempotent for None
+
+    if hasattr(obj, '__marshallable__'):
+        result = obj.__marshallable__()
+        # 如果 __marshallable__ 返回的是协程，需要 await
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    if hasattr(obj, '__getitem__'):
+        return obj  # it is indexable it is ok
+
+    return dict(obj.__dict__)
+
+
+class Raw:
+    """Raw provides a base field class from which others should extend. It
+    applies no formatting by default, and should only be used in cases where
+    data does not need to be formatted before being serialized. Fields should
+    throw a :class:`MarshallingException` in case of parsing problem.
+
+    :param default: The default value for the field, if no value is
+        specified.
+    :param attribute: If the public facing value differs from the internal
+        value, use this to retrieve a different attribute from the response
+        than the publicly named value.
+    """
+
+    def __init__(self, default=None, attribute=None):
+        self.attribute = attribute
+        self.default = default
+
+    async def format(self, value):
+        """Formats a field's value. No-op by default - field classes that
+        modify how the value of existing object keys should be presented should
+        override this and apply the appropriate formatting.
+
+        :param value: The value to format
+        :exception MarshallingException: In case of formatting problem
+
+        Ex::
+
+            class TitleCase(Raw):
+                async def format(self, value):
+                    return str(value).title()
+        """
+        return value
+
+    async def output(self, key, obj):
+        """Pulls the value for the given key from the object, applies the
+        field's formatting and returns the result. If the key is not found
+        in the object, returns the default value. Field classes that create
+        values which do not require the existence of the key in the object
+        should override this and return the desired value.
+
+        :exception MarshallingException: In case of formatting problem
+        """
+        value = await get_value(key if self.attribute is None else self.attribute, obj)
+
+        if value is None:
+            return self.default
+
+        return await self.format(value)
+
+
+class Nested(Raw):
+    """Allows you to nest one set of fields inside another.
+    See :ref:`nested-field` for more information
+
+    :param dict nested: The dictionary to nest
+    :param bool allow_null: Whether to return None instead of a dictionary
+        with null keys, if a nested dictionary has all-null keys
+    :param kwargs: If ``default`` keyword argument is present, a nested
+        dictionary will be marshaled as its value if nested dictionary is
+        all-null keys (e.g. lets you return an empty JSON object instead of
+        null)
+    """
+
+    def __init__(self, nested, allow_null=False, **kwargs):
+        self.nested = nested
+        self.allow_null = allow_null
+        super().__init__(**kwargs)
+
+    async def output(self, key, obj):
+        value = await get_value(key if self.attribute is None else self.attribute, obj)
+        if value is None:
+            if self.allow_null:
+                return None
+            elif self.default is not None:
+                return self.default
+
+        # 延迟导入以避免循环导入
+        from tomskit.utils.marshal_utils import marshal
+        return await marshal(value, self.nested)
+
+
+class List(Raw):
+    """
+    Field for marshalling lists of other fields.
+
+    See :ref:`list-field` for more information.
+
+    :param cls_or_instance: The field type the list will contain.
+    """
+
+    def __init__(self, cls_or_instance, **kwargs):
+        super().__init__(**kwargs)
+        error_msg = ("The type of the list elements must be a subclass of "
+                     "tomskit.utils.fields.Raw")
+        if isinstance(cls_or_instance, type):
+            if not issubclass(cls_or_instance, Raw):
+                raise MarshallingException(error_msg)
+            self.container = cls_or_instance()
+        else:
+            if not isinstance(cls_or_instance, Raw):
+                raise MarshallingException(error_msg)
+            self.container = cls_or_instance
+
+    async def format(self, value):
+        # Convert all instances in typed list to container type
+        if isinstance(value, set):
+            value = list(value)
+
+        results = []
+        for idx, val in enumerate(value):
+            item = val if (isinstance(val, dict)
+                          or (self.container.attribute
+                              and hasattr(val, self.container.attribute))
+                          ) and not isinstance(self.container, Nested) and type(self.container) is not Raw else value
+            output = await self.container.output(idx, item)
+            results.append(output)
+        return results
+
+    async def output(self, key, data):
+        value = await get_value(key if self.attribute is None else self.attribute, data)
+        # we cannot really test for external dict behavior
+        if is_indexable_but_not_string(value) and not isinstance(value, dict):
+            return await self.format(value)
+
+        if value is None:
+            return self.default
+
+        # 延迟导入以避免循环导入
+        from tomskit.utils.marshal_utils import marshal
+        return [await marshal(value, self.container.nested)]
+
+
+class String(Raw):
+    """
+    Marshal a value as a string. Uses ``str`` so values will
+    be converted to string.
+    """
+    async def format(self, value):
+        try:
+            return str(value)
+        except ValueError as ve:
+            raise MarshallingException(ve)
+
+
+class Integer(Raw):
+    """ Field for outputting an integer value.
+
+    :param int default: The default value for the field, if no value is
+        specified.
+    """
+    def __init__(self, default=0, **kwargs):
+        super().__init__(default=default, **kwargs)
+
+    async def format(self, value):
+        try:
+            if value is None:
+                return self.default
+            return int(value)
+        except ValueError as ve:
+            raise MarshallingException(ve)
+
+
+class Boolean(Raw):
+    """
+    Field for outputting a boolean value.
+
+    Empty collections such as ``""``, ``{}``, ``[]``, etc. will be converted to
+    ``False``.
+    """
+    async def format(self, value):
+        return bool(value)
+
+
+class FormattedString(Raw):
+    """
+    FormattedString is used to interpolate other values from
+    the response into this field. The syntax for the source string is
+    the same as the string :meth:`~str.format` method from the python
+    stdlib.
+
+    Ex::
+
+        fields = {
+            'name': fields.String(),
+            'greeting': fields.FormattedString("Hello {name}")
+        }
+        data = {
+            'name': 'Doug',
+        }
+        result = await marshal(data, fields)
+    """
+    def __init__(self, src_str):
+        """
+        :param string src_str: the string to format with the other
+        values from the response.
+        """
+        super().__init__()
+        self.src_str = str(src_str)
+
+    async def output(self, key, obj):
+        try:
+            data = await to_marshallable_type(obj)
+            if data is None:
+                data = {}
+            return self.src_str.format(**data)
+        except (TypeError, IndexError) as error:
+            raise MarshallingException(error)
+
+
+class Float(Raw):
+    """
+    A double as IEEE-754 double precision.
+    ex : 3.141592653589793 3.1415926535897933e-06 3.141592653589793e+24 nan inf
+    -inf
+    """
+
+    async def format(self, value):
+        try:
+            return float(value)
+        except ValueError as ve:
+            raise MarshallingException(ve)
+
+
+class Arbitrary(Raw):
+    """
+        A floating point number with an arbitrary precision
+          ex: 634271127864378216478362784632784678324.23432
+    """
+
+    async def format(self, value):
+        return str(MyDecimal(value))
+
+
+class DateTime(Raw):
+    """
+    Return a formatted datetime string in UTC. Supported formats are RFC 822
+    and ISO 8601.
+
+    See :func:`email.utils.formatdate` for more info on the RFC 822 format.
+
+    See :meth:`datetime.datetime.isoformat` for more info on the ISO 8601
+    format.
+
+    :param dt_format: ``'rfc822'`` or ``'iso8601'``
+    :type dt_format: str
+    """
+    def __init__(self, dt_format='rfc822', **kwargs):
+        super().__init__(**kwargs)
+        self.dt_format = dt_format
+
+    async def format(self, value):
+        try:
+            if self.dt_format == 'rfc822':
+                return _rfc822(value)
+            elif self.dt_format == 'iso8601':
+                return _iso8601(value)
+            else:
+                raise MarshallingException(
+                    f'Unsupported date format {self.dt_format}'
+                )
+        except AttributeError as ae:
+            raise MarshallingException(ae)
+
+ZERO = MyDecimal()
+
+
+class Fixed(Raw):
+    """
+    A decimal number with a fixed precision.
+    """
+    def __init__(self, decimals=5, **kwargs):
+        super().__init__(**kwargs)
+        self.precision = MyDecimal('0.' + '0' * (decimals - 1) + '1')
+
+    async def format(self, value):
+        dvalue = MyDecimal(value)
+        if not dvalue.is_normal() and dvalue != ZERO:
+            raise MarshallingException('Invalid Fixed precision number.')
+        return str(dvalue.quantize(self.precision, rounding=ROUND_HALF_EVEN))
+
+
+"""Alias for :class:`~fields.Fixed`"""
+Price = Fixed
+
+
+def _rfc822(dt):
+    """Turn a datetime object into a formatted date.
+
+    Example::
+
+        fields._rfc822(datetime(2011, 1, 1)) => "Sat, 01 Jan 2011 00:00:00 -0000"
+
+    :param dt: The datetime to transform
+    :type dt: datetime
+    :return: A RFC 822 formatted date string
+    """
+    return formatdate(timegm(dt.utctimetuple()))
+
+
+def _iso8601(dt):
+    """Turn a datetime object into an ISO8601 formatted date.
+
+    Example::
+
+        fields._iso8601(datetime(2012, 1, 1, 0, 0)) => "2012-01-01T00:00:00"
+
+    :param dt: The datetime to transform
+    :type dt: datetime
+    :return: A ISO 8601 formatted date string
+    """
+    return dt.isoformat()

tomskit/utils/marshal_utils.py

@@ -0,0 +1,137 @@
+"""
+marshal 函数，支持异步数据序列化。
+
+基于 flask-restful 的 marshal 实现，但所有操作都是异步的，以支持从异步数据源（如异步数据库查询）获取数据。
+"""
+import inspect
+from collections import OrderedDict
+from collections.abc import AsyncIterable
+from functools import wraps
+
+from fastapi.responses import JSONResponse
+
+from tomskit.utils.response_utils import unpack
+
+
+async def marshal(data, fields, envelope=None):
+    """接受原始数据（以字典、列表、对象的形式）和输出字段的字典，
+    并根据这些字段过滤数据。支持异步数据获取。
+
+    :param data: 实际的数据对象（可以是单个对象或对象列表）
+    :param fields: 包含输出字段的字典
+    :param envelope: 可选的键，用于包裹序列化的响应
+    """
+    def make(cls):
+        if isinstance(cls, type):
+            return cls()
+        return cls
+
+    if data is None:
+        return OrderedDict() if envelope is None else OrderedDict([(envelope, None)])
+    
+    # 处理列表和元组
+    if isinstance(data, (list, tuple)):
+        results = []
+        for item in data:
+            result = await marshal(item, fields)
+            results.append(result)
+        return OrderedDict([(envelope, results)]) if envelope else results
+
+    # 处理异步可迭代对象
+    elif isinstance(data, AsyncIterable):
+        results = []
+        async for item in data:
+            result = await marshal(item, fields)
+            results.append(result)
+        return OrderedDict([(envelope, results)]) if envelope else results
+
+    # 处理单个对象
+    items = OrderedDict()
+    for k, v in fields.items():
+        if isinstance(v, dict):
+            value = await marshal(data, v)
+        else:
+            field_instance = make(v)
+            if hasattr(field_instance, 'output'):
+                output = field_instance.output(k, data)
+                if inspect.isawaitable(output):
+                    value = await output
+                else:
+                    value = output
+            else:
+                raise ValueError(f"字段 '{k}' 不是有效的 Field 实例。")
+        items[k] = value
+
+    return OrderedDict([(envelope, items)]) if envelope else items
+
+
+class marshal_with:
+    """A decorator that apply marshalling to the return values of your methods.
+
+    see :meth:`marshal_utils.marshal`
+    """
+    def __init__(self, fields, envelope=None):
+        """
+        :param fields: a dict of whose keys will make up the final
+                       serialized response output
+        :param envelope: optional key that will be used to envelop the serialized
+                         response
+        """
+        self.fields = fields
+        self.envelope = envelope
+
+    def __call__(self, f):
+        @wraps(f)
+        async def wrapper(*args, **kwargs):
+            resp = await f(*args, **kwargs)
+            if isinstance(resp, tuple):
+                data, code, headers = unpack(resp)
+                content = await marshal(data, self.fields, self.envelope)
+                return JSONResponse(content=content, status_code=code, headers=headers)
+            elif isinstance(resp, JSONResponse):
+                return resp
+            else:
+                content = await marshal(resp, self.fields, self.envelope)
+                return JSONResponse(content=content)
+        return wrapper
+
+
+class marshal_with_field:
+    """
+    A decorator that formats the return values of your methods with a single field.
+
+    >>> from tomskit.utils import marshal_utils, fields
+    >>> @marshal_with_field(fields.List(fields.Integer))
+    ... async def get():
+    ...     return ['1', 2, 3.0]
+    ...
+    >>> await get()
+    [1, 2, 3]
+
+    see :meth:`marshal_utils.marshal_with`
+    """
+    def __init__(self, field):
+        """
+        :param field: a single field with which to marshal the output.
+        """
+        if isinstance(field, type):
+            self.field = field()
+        else:
+            self.field = field
+
+    def __call__(self, f):
+        @wraps(f)
+        async def wrapper(*args, **kwargs):
+            resp = await f(*args, **kwargs)
+
+            if isinstance(resp, tuple):
+                data, code, headers = unpack(resp)
+                content = await self.field.format(data)
+                return JSONResponse(content=content, status_code=code, headers=headers)
+            elif isinstance(resp, JSONResponse):
+                return resp
+            else:
+                content = await self.field.format(resp)
+                return JSONResponse(content=content)
+
+        return wrapper

tomskit/utils/response_utils.py

@@ -0,0 +1,13 @@
+
+def unpack(value):
+    """Return a three-tuple of (data, code, headers)"""
+    if not isinstance(value, tuple):
+        return value, 200, {}
+
+    if len(value) == 3:
+        return value
+    elif len(value) == 2:
+        data, code = value
+        return data, code, {}
+    else:
+        return value, 200, {}