u-toolkit 0.1.0__py3-none-any.whl

u_toolkit/__init__.py

@@ -0,0 +1,9 @@
+def get(obj: dict, key: str, fallback=None):
+    items = key.split(".", 1)
+    if len(items) > 1:
+        for i in items:
+            return get(obj, i, fallback)
+    elif items:
+        return obj.get(key, fallback)
+
+    return fallback

u_toolkit/alias_generators.py

@@ -0,0 +1,49 @@
+from typing import TypeVarTuple, overload
+
+from pydantic import alias_generators
+from pydantic.fields import ComputedFieldInfo, FieldInfo
+
+
+Ts = TypeVarTuple("Ts")
+
+
+@overload
+def to_camel(string: str, _: ComputedFieldInfo | FieldInfo) -> str: ...
+
+
+@overload
+def to_camel(string: str) -> str: ...
+
+
+def to_camel(string: str, *_, **__):
+    if string.isupper():
+        return string
+    return alias_generators.to_camel(string)
+
+
+@overload
+def to_snake(string: str, _: ComputedFieldInfo | FieldInfo) -> str: ...
+
+
+@overload
+def to_snake(string: str) -> str: ...
+
+
+def to_snake(string: str, *_, **__):
+    if string.isupper():
+        return string
+    return alias_generators.to_snake(string)
+
+
+@overload
+def to_pascal(string: str, _: ComputedFieldInfo | FieldInfo) -> str: ...
+
+
+@overload
+def to_pascal(string: str) -> str: ...
+
+
+def to_pascal(string: str, *_, **__):
+    if string.isupper():
+        return string
+    return alias_generators.to_pascal(string)

u_toolkit/datetime.py

@@ -0,0 +1,30 @@
+from datetime import UTC, datetime
+
+
+def to_utc(dt: datetime, /) -> datetime:
+    """转成 UTC 时间
+
+    :param dt: 时间
+    :return: UTC 时间
+    """
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=UTC)
+    return dt.astimezone(UTC)
+
+
+def to_naive(dt: datetime, /) -> datetime:
+    """去除时区标识
+
+    :param v: 时间
+    :return: 不带时区标识的时间
+    """
+    return dt.replace(tzinfo=None)
+
+
+def to_utc_naive(dt: datetime, /) -> datetime:
+    """将时间转换成不带时区标识的 UTC 时间
+
+    :param v: 时间
+    :return: 不带时区标识的 UTC 时间
+    """
+    return to_naive(to_utc(dt))

u_toolkit/decorators.py

@@ -0,0 +1,46 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import Generic, NamedTuple, TypeVar
+
+from u_toolkit.signature import list_parameters, update_parameters
+
+
+_FnT = TypeVar("_FnT", bound=Callable)
+
+_T = TypeVar("_T")
+
+
+class DefineMethodParams(NamedTuple, Generic[_T, _FnT]):
+    method_class: type[_T]
+    method_name: str
+    method: _FnT
+
+
+class DefineMethodDecorator(Generic[_T, _FnT]):
+    def __init__(self, fn: _FnT):
+        self.fn = fn
+        self.name = fn.__name__
+
+    def register_method(self, params: DefineMethodParams[_T, _FnT]): ...
+
+    def __set_name__(self, owner_class: type, name: str):
+        self.register_method(DefineMethodParams(owner_class, name, self.fn))
+
+    def __get__(self, instance: _T, owner_class: type[_T]):
+        update_parameters(self.fn, *list_parameters(self.fn)[1:])
+
+        @wraps(self.fn)
+        def wrapper(*args, **kwargs):
+            return self.fn(instance, *args, **kwargs)
+
+        return wrapper
+
+
+def define_method_handler(
+    handle: Callable[[DefineMethodParams[_T, _FnT]], None],
+):
+    class Decorator(DefineMethodDecorator):
+        def register_method(self, params: DefineMethodParams):
+            handle(params)
+
+    return Decorator

u_toolkit/enum.py

@@ -0,0 +1,43 @@
+from enum import StrEnum, auto
+
+from .alias_generators import to_camel, to_pascal, to_snake
+
+
+__all__ = [
+    "CamelEnum",
+    "NameEnum",
+    "PascalEnum",
+    "SnakeEnum",
+    "TitleEnum",
+    "auto",
+]
+
+
+class NameEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name, *_, **__) -> str:
+        return name
+
+
+class PascalEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name, *_, **__) -> str:
+        return to_pascal(name)
+
+
+class CamelEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name, *_, **__) -> str:
+        return to_camel(name)
+
+
+class SnakeEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name, *_, **__) -> str:
+        return to_snake(name)
+
+
+class TitleEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name, *_, **__) -> str:
+        return name.replace("_", " ").title()

u_toolkit/fastapi/cbv.py

@@ -0,0 +1,342 @@
+import inspect
+import re
+from collections.abc import Callable
+from enum import Enum, StrEnum, auto
+from functools import partial, update_wrapper, wraps
+from typing import Any, Literal, NamedTuple, Protocol, Self, TypeVar, cast
+
+from fastapi import APIRouter, Depends
+from pydantic.alias_generators import to_snake
+
+from u_toolkit.decorators import DefineMethodParams, define_method_handler
+from u_toolkit.fastapi.helpers import get_depend_from_annotation, is_depend
+from u_toolkit.fastapi.responses import Response, build_responses
+from u_toolkit.helpers import is_annotated
+from u_toolkit.merge import deep_merge_dict
+from u_toolkit.signature import update_parameters, with_parameter
+
+
+class EndpointsClassInterface(Protocol):
+    dependencies: tuple | None = None
+    responses: tuple[Response, ...] | None = None
+    prefix: str | None = None
+    tags: tuple[str | Enum, ...] | None = None
+    deprecated: bool | None = None
+
+    @classmethod
+    def build_self(cls) -> Self: ...
+
+
+_T = TypeVar("_T")
+EndpointsClassInterfaceT = TypeVar(
+    "EndpointsClassInterfaceT",
+    bound=EndpointsClassInterface,
+)
+
+
+LiteralUpperMethods = Literal[
+    "GET",
+    "POST",
+    "PATCH",
+    "PUT",
+    "DELETE",
+    "OPTIONS",
+    "HEAD",
+    "TRACE",
+]
+LiteralLowerMethods = Literal[
+    "get",
+    "post",
+    "patch",
+    "put",
+    "delete",
+    "options",
+    "head",
+    "trace",
+]
+
+
+class Methods(StrEnum):
+    GET = auto()
+    POST = auto()
+    PATCH = auto()
+    PUT = auto()
+    DELETE = auto()
+    OPTIONS = auto()
+    HEAD = auto()
+    TRACE = auto()
+
+
+METHOD_PATTERNS = {
+    method: re.compile(f"^{method}", re.IGNORECASE) for method in Methods
+}
+
+_FnName = str
+
+
+class EndpointInfo(NamedTuple):
+    fn: Callable
+    original_name: str
+    method: Methods
+    method_pattern: re.Pattern
+    path: str
+
+
+def get_method(name: str):
+    for method, method_pattern in METHOD_PATTERNS.items():
+        if method_pattern.search(name):
+            return method, method_pattern
+    return None
+
+
+def valid_endpoint(name: str):
+    if get_method(name) is None:
+        raise ValueError("Invalid endpoint function.")
+
+
+def iter_endpoints(cls: type[_T]):
+    prefix = "/"
+
+    if not cls.__name__.startswith("_"):
+        prefix += f"{to_snake(cls.__name__)}"
+
+    for name, fn in inspect.getmembers(
+        cls,
+        lambda arg: inspect.ismethoddescriptor(arg) or inspect.isfunction(arg),
+    ):
+        paths = [prefix]
+
+        if method := get_method(name):
+            path = method[1].sub(name, "").replace("__", "/")
+            if path:
+                paths.append(path)
+
+            yield EndpointInfo(
+                fn=fn,
+                original_name=name,
+                path="/".join(paths),
+                method=method[0],
+                method_pattern=method[1],
+            )
+
+
+def iter_dependencies(cls: type[_T]):
+    _split = re.compile(r"\s+|:|=")
+    dependencies: dict = dict(inspect.getmembers(cls, is_depend))
+    for name, type_ in inspect.get_annotations(cls).items():
+        if is_annotated(type_):
+            dependency = get_depend_from_annotation(type_)
+            dependencies[name] = dependency
+
+    for line in inspect.getsource(cls).split("\n"):
+        token: str = _split.split(line.strip(), 1)[0]
+        for name, dep in dependencies.items():
+            if name == token:
+                yield token, dep
+
+
+_CBVEndpointParamName = Literal[
+    "tags",
+    "dependencies",
+    "responses",
+    "response_model",
+    "status",
+    "deprecated",
+    "methods",
+]
+
+
+class CBV:
+    def __init__(self, router: APIRouter | None = None) -> None:
+        self.router = router or APIRouter()
+
+        self._state: dict[
+            type[EndpointsClassInterface],
+            dict[_FnName, dict[_CBVEndpointParamName, Any]],
+        ] = {}
+
+        self._initialed_state: dict[
+            type[EndpointsClassInterface], EndpointsClassInterface
+        ] = {}
+
+    def create_route(
+        self,
+        *,
+        cls: type[EndpointsClassInterfaceT],
+        path: str,
+        method: Methods | LiteralUpperMethods | LiteralLowerMethods,
+        method_name: str,
+    ):
+        class_tags = list(cls.tags) if cls.tags else []
+        endpoint_tags: list[str | Enum] = (
+            self._state[cls][method_name].get("tags") or []
+        )
+        tags = class_tags + endpoint_tags
+
+        class_dependencies = list(cls.dependencies) if cls.dependencies else []
+        endpoint_dependencies = (
+            self._state[cls][method_name].get("dependencies") or []
+        )
+        dependencies = class_dependencies + endpoint_dependencies
+
+        class_responses = cls.responses or []
+        endpoint_responses = (
+            self._state[cls][method_name].get("responses") or []
+        )
+        responses = build_responses(*class_responses, *endpoint_responses)
+
+        status_code = self._state[cls][method_name].get("status")
+
+        deprecated = self._state[cls][method_name].get(
+            "deprecated", cls.deprecated
+        )
+
+        response_model = self._state[cls][method_name].get("response_model")
+
+        endpoint_methods = self._state[cls][method_name].get("methods") or [
+            method
+        ]
+
+        return self.router.api_route(
+            path,
+            methods=endpoint_methods,
+            tags=tags,
+            dependencies=dependencies,
+            response_model=response_model,
+            responses=responses,
+            status_code=status_code,
+            deprecated=deprecated,
+        )
+
+    def info(
+        self,
+        *,
+        methods: list[Methods | LiteralUpperMethods | LiteralLowerMethods]
+        | None = None,
+        tags: list[str | Enum] | None = None,
+        dependencies: list | None = None,
+        responses: list[Response] | None = None,
+        response_model: Any | None = None,
+        status: int | None = None,
+        deprecated: bool | None = None,
+    ):
+        state = self._state
+        initial_state = self._initial_state
+        data: dict[_CBVEndpointParamName, Any] = {
+            "methods": methods,
+            "tags": tags,
+            "dependencies": dependencies,
+            "responses": responses,
+            "response_model": response_model,
+            "status": status,
+            "deprecated": deprecated,
+        }
+
+        def handle(params: DefineMethodParams):
+            initial_state(params.method_class)
+            deep_merge_dict(
+                state,
+                {params.method_class: {params.method_name: data}},
+            )
+
+        return define_method_handler(handle)
+
+    def _initial_state(self, cls: type[_T]) -> EndpointsClassInterface:
+        if result := self._initialed_state.get(cls):  # type: ignore
+            return result
+
+        self._update_cls(cls)
+        n_cls = cast(type[EndpointsClassInterface], cls)
+
+        default_data = {}
+        for endpoint in iter_endpoints(n_cls):
+            default_data[endpoint.original_name] = {}
+
+        self._state.setdefault(n_cls, default_data)
+        result = self._build_cls(n_cls)
+        self._initialed_state[n_cls] = result
+        return result
+
+    def _update_cls(self, cls: type[_T]):
+        for extra_name in EndpointsClassInterface.__annotations__:
+            if not hasattr(cls, extra_name):
+                setattr(cls, extra_name, None)
+
+            # TODO: 加个如果存在属性, 校验属性类型是否是预期的
+
+    def _build_cls(self, cls: type[_T]) -> _T:
+        if inspect.isfunction(cls.__init__) and hasattr(cls, "build_self"):
+            return cast(type[EndpointsClassInterface], cls).build_self()  # type: ignore
+        return cls()
+
+    def __create_class_dependencies_injector(
+        self, cls: type[EndpointsClassInterfaceT]
+    ):
+        """将类的依赖添加到函数实例上
+
+        ```python
+        @cbv
+        class A:
+            a = Depends(lambda: id(object()))
+
+            def get(self):
+                # 使得每次 self.a 可以访问到当前请求的依赖
+                print(self.a)
+        ```
+        """
+
+        def collect_cls_dependencies(**kwargs):
+            return kwargs
+
+        parameters = [
+            inspect.Parameter(
+                name=name,
+                kind=inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=dep,
+            )
+            for name, dep in iter_dependencies(cls)
+        ]
+        update_parameters(collect_cls_dependencies, *parameters)
+
+        def decorator(method: Callable):
+            sign_fn = partial(method)
+            update_wrapper(sign_fn, method)
+
+            parameters, *_ = with_parameter(
+                method,
+                name=collect_cls_dependencies.__name__,
+                default=Depends(collect_cls_dependencies),
+            )
+            update_parameters(sign_fn, *parameters)
+
+            @wraps(sign_fn)
+            def wrapper(*args, **kwargs):
+                instance = self._build_cls(cls)
+                dependencies = kwargs.pop(collect_cls_dependencies.__name__)
+                for dep_name, dep_value in dependencies.items():
+                    setattr(instance, dep_name, dep_value)
+                fn = getattr(instance, method.__name__)
+                return fn(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def __call__(self, cls: type[_T]) -> type[_T]:
+        instance = self._initial_state(cls)
+        cls_ = cast(type[EndpointsClassInterface], cls)
+
+        decorator = self.__create_class_dependencies_injector(cls_)
+
+        for endpoint_info in iter_endpoints(cls):
+            route = self.create_route(
+                cls=cast(type[EndpointsClassInterface], cls),
+                path=endpoint_info.path,
+                method=endpoint_info.method,
+                method_name=endpoint_info.original_name,
+            )
+            method = getattr(instance, endpoint_info.original_name)
+            endpoint = decorator(method)
+            route(endpoint)
+
+        return cls

u_toolkit/fastapi/config.py

@@ -0,0 +1,9 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class FastAPISettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTAPI_",
+        env_file=(".env", ".env.prod", ".env.dev", ".env.test"),
+        extra="ignore",
+    )

u_toolkit/fastapi/exception.py

@@ -0,0 +1,115 @@
+from collections.abc import Callable, Sequence
+from typing import Generic, Literal, Protocol, cast
+
+from fastapi import status
+from pydantic import BaseModel, create_model
+
+from u_toolkit.pydantic.type_vars import BaseModelT
+
+
+class WrapperError(BaseModel, Generic[BaseModelT]):  # type: ignore
+    @classmethod
+    def create(
+        cls: type["WrapperError[BaseModelT]"],
+        model: BaseModelT,
+    ) -> "WrapperError[BaseModelT]":
+        raise NotImplementedError
+
+
+class EndpointError(WrapperError, Generic[BaseModelT]):
+    error: BaseModelT
+
+    @classmethod
+    def create(cls, model: BaseModelT):
+        return cls(error=model)
+
+
+class HTTPErrorInterface(Protocol):
+    status: int
+
+    @classmethod
+    def response_class(cls) -> type[BaseModel]: ...
+
+
+class NamedHTTPError(Exception, Generic[BaseModelT]):
+    status: int = status.HTTP_400_BAD_REQUEST
+    code: str | None = None
+    targets: Sequence[str] | None = None
+    target_transform: Callable[[str], str] | None = None
+    message: str | None = None
+    wrapper_class: type[WrapperError[BaseModelT]] | None = EndpointError
+
+    @classmethod
+    def error_name(cls):
+        return cls.__name__.removesuffix("Error")
+
+    @classmethod
+    def model_class(cls) -> type[BaseModelT]:
+        type_ = cls.error_name()
+        error_code = cls.code or type_
+        kwargs = {
+            "code": (Literal[error_code], ...),
+            "message": (Literal[cls.message] if cls.message else str, ...),
+        }
+        if cls.targets:
+            kwargs["target"] = (Literal[*cls.transformed_targets()], ...)
+
+        return cast(type[BaseModelT], create_model(f"{type_}Model", **kwargs))
+
+    @classmethod
+    def error_code(cls):
+        return cls.code or cls.error_name()
+
+    @classmethod
+    def transformed_targets(cls) -> list[str]:
+        if cls.targets:
+            result = []
+            for i in cls.targets:
+                if cls.target_transform:
+                    result.append(cls.target_transform(i))
+                else:
+                    result.append(i)
+            return result
+        return []
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        target: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        kwargs = {
+            "code": self.error_code(),
+            "message": message,
+        }
+
+        if target:
+            if self.target_transform:
+                target = self.target_transform(target)
+            kwargs["target"] = target
+            kwargs["message"] = kwargs["message"].format(target=target)
+
+        self.model = self.model_class()(**kwargs)
+        self.data: BaseModel = (
+            self.wrapper_class.create(self.model)
+            if self.wrapper_class is not None
+            else self.model
+        )
+
+        self.headers = headers
+
+    def __str__(self) -> str:
+        return f"{self.status}: {self.data.error.code}"  # type: ignore
+
+    def __repr__(self) -> str:
+        return f"{self.model_class: str(self.error)}"
+
+    @classmethod
+    def response_class(cls):
+        model = cls.model_class()
+        return cls.wrapper_class if cls.wrapper_class is not None else model
+
+    @classmethod
+    def response_schema(cls):
+        return {cls.status: {"model": cls.response_class()}}

u_toolkit/fastapi/helpers.py

@@ -0,0 +1,18 @@
+from typing import Annotated, Any, get_args
+
+from fastapi.params import Depends
+
+
+def is_depend(value: Any):
+    return isinstance(value, Depends)
+
+
+def get_depend_from_annotation(annotation: Annotated):
+    args = list(get_args(annotation))
+    # 因为 FastAPI 好像也是取最后的依赖运行的, 所以这里也将参数反转
+    args.reverse()
+    for arg in args:
+        if is_depend(arg):
+            return arg
+
+    raise ValueError

u_toolkit/fastapi/lifespan.py

@@ -0,0 +1,67 @@
+import asyncio
+from collections.abc import Awaitable, Callable, Coroutine
+from contextlib import (
+    AbstractAsyncContextManager,
+    AbstractContextManager,
+    AsyncExitStack,
+    asynccontextmanager,
+)
+from typing import TypeVar
+
+from fastapi import FastAPI
+
+
+Hook = Callable[
+    [FastAPI],
+    Awaitable[None] | Coroutine[None, None, None] | None,
+]
+
+HookT = TypeVar("HookT", bound=Hook)
+
+ContextManager = Callable[
+    [FastAPI],
+    AbstractContextManager | AbstractAsyncContextManager,
+]
+
+ContextManagerT = TypeVar("ContextManagerT", bound=ContextManager)
+
+
+class Lifespan:
+    def __init__(self) -> None:
+        self._startup_hooks: list[Hook] = []
+        self._shutdown_hooks: list[Hook] = []
+        self._context_managers: list[ContextManager] = []
+
+    def on_startup(self, fn: HookT) -> HookT:
+        self._startup_hooks.append(fn)
+        return fn
+
+    def on_shutdown(self, fn: HookT) -> HookT:
+        self._shutdown_hooks.append(fn)
+        return fn
+
+    def on_context(self, fn: ContextManagerT) -> ContextManagerT:
+        self._context_managers.append(fn)
+        return fn
+
+    @asynccontextmanager
+    async def __call__(self, _app: FastAPI):
+        for hook in self._startup_hooks:
+            ret = hook(_app)
+            if asyncio.iscoroutine(ret):
+                await ret
+
+        async with AsyncExitStack() as stack:
+            for ctx in self._context_managers:
+                i = ctx(_app)
+                if isinstance(i, AbstractContextManager):
+                    stack.enter_context(i)
+                elif isinstance(i, AbstractAsyncContextManager):
+                    await stack.enter_async_context(i)
+
+            yield
+
+        for hook in self._shutdown_hooks:
+            ret = hook(_app)
+            if asyncio.iscoroutine(ret):
+                await ret

u_toolkit/fastapi/pagination.py

@@ -0,0 +1,79 @@
+from collections.abc import Sequence
+from math import ceil
+from typing import Annotated, Generic, overload
+
+from fastapi import Depends, Query
+from pydantic import BaseModel, Field, NonNegativeInt, PositiveInt
+from sqlalchemy import MappingResult, ScalarResult
+
+from u_toolkit.pydantic.type_vars import BaseModelT
+from u_toolkit.sqlalchemy.type_vars import DeclarativeBaseT
+
+
+class Page(BaseModel, Generic[BaseModelT]):
+    page_size: PositiveInt = Field(description="page size")
+    page_no: PositiveInt = Field(description="page number")
+
+    page_count: NonNegativeInt = Field(description="page count")
+    count: NonNegativeInt = Field(description="result count")
+
+    results: list[BaseModelT] = Field(description="results")
+
+
+class PageParamsModel(BaseModel):
+    page_size: int = Query(
+        50,
+        ge=1,
+        le=100,
+        description="page size",
+    )
+    page_no: PositiveInt = Query(
+        1,
+        description="page number",
+    )
+
+
+PageParams = Annotated[PageParamsModel, Depends()]
+
+
+@overload
+def page(
+    model_class: type[BaseModelT],
+    pagination: PageParamsModel,
+    count: int,
+    results: ScalarResult[DeclarativeBaseT],
+) -> Page[BaseModelT]: ...
+
+
+@overload
+def page(
+    model_class: type[BaseModelT],
+    pagination: PageParamsModel,
+    count: int,
+    results: MappingResult,
+) -> Page[BaseModelT]: ...
+
+
+@overload
+def page(
+    model_class: type[BaseModelT],
+    pagination: PageParamsModel,
+    count: int,
+    results: Sequence[DeclarativeBaseT],
+) -> Page[BaseModelT]: ...
+
+
+def page(
+    model_class: type[BaseModelT],
+    pagination: PageParamsModel,
+    count: int,
+    results,
+) -> Page[BaseModelT]:
+    results_ = [model_class.model_validate(i) for i in results]
+    return Page(
+        page_size=pagination.page_size,
+        page_no=pagination.page_no,
+        page_count=ceil(count / pagination.page_size),
+        count=count,
+        results=results_,  # type: ignore
+    )

u_toolkit/fastapi/responses.py

@@ -0,0 +1,66 @@
+from pydantic import BaseModel
+
+from u_toolkit.merge import deep_merge_dict
+
+from .exception import HTTPErrorInterface
+
+
+def _merge_responses(
+    target: dict,
+    source: dict,
+):
+    for status, response in target.items():
+        model_class = response.get("model")
+        if status in source:
+            source_model_class = source[status].get("model")
+            if source_model_class is not None:
+                target[status]["model"] = model_class | source_model_class
+
+    for status, response in source.items():
+        if status not in target:
+            target[status] = response
+
+
+def error_responses(*errors: type[HTTPErrorInterface]):
+    source = {}
+
+    for e in errors:
+        model_class = e.response_class()
+        if e.status in source:
+            current: type[BaseModel] = source[e.status]["model"]
+
+            source[e.status] = {"model": current | model_class}
+        else:
+            deep_merge_dict(source, {e.status: {"model": model_class}})
+    return source
+
+
+Response = (
+    tuple[int, type[BaseModel]]
+    | dict[int, type[BaseModel]]
+    | int
+    | type[HTTPErrorInterface]
+)
+
+
+def build_responses(*responses: Response):
+    result = {}
+    errors: list[type[HTTPErrorInterface]] = []
+
+    for arg in responses:
+        status = None
+        response = {}
+        if isinstance(arg, tuple):
+            status, response = arg
+        elif isinstance(arg, dict):
+            for status_, response_ in arg.items():
+                result[status_] = {"model": response_}
+        elif isinstance(arg, int):
+            status = arg
+        else:
+            errors.append(arg)
+
+        result[status] = {"model": response}
+
+    _merge_responses(result, error_responses(*errors))
+    return result

u_toolkit/function.py

@@ -0,0 +1,12 @@
+from collections.abc import Callable
+
+
+def get_name(fn: Callable, /):
+    return fn.__name__
+
+
+def add_document(fn: Callable, document: str, /):
+    if fn.__doc__ is None:
+        fn.__doc__ = document
+    else:
+        fn.__doc__ += f"\n\n{document}"

u_toolkit/helpers.py

@@ -0,0 +1,5 @@
+from typing import Annotated, get_origin
+
+
+def is_annotated(target):
+    return get_origin(target) is Annotated

u_toolkit/logger.py

@@ -0,0 +1,11 @@
+from u_toolkit.enum import NameEnum, auto
+
+
+class LogLevel(NameEnum):
+    TRACE = auto()
+    DEBUG = auto()
+    INFO = auto()
+    SUCCESS = auto()
+    WARNING = auto()
+    ERROR = auto()
+    CRITICAL = auto()

u_toolkit/merge.py

@@ -0,0 +1,31 @@
+from collections.abc import Mapping
+
+
+def deep_merge_dict(
+    target: dict,
+    source: Mapping,
+):
+    """深层合并两个字典
+
+    :param target: 存放合并内容的字典
+    :param source: 来源, 因为不会修改, 所以只读映射就可以
+    :param exclude_keys: 需要排除的 keys
+    """
+
+    for ok, ov in source.items():
+        v = target.get(ok)
+        # 如果两边都是映射类型, 就可以合并
+        if isinstance(v, dict) and isinstance(ov, Mapping):
+            deep_merge_dict(v, ov)
+        # 如果当前值允许进行相加的操作
+        # 并且不是字符串和数字
+        # 并且旧字典与当前值类型相同
+        elif (
+            hasattr(v, "__add__")
+            and not isinstance(v, str | int)
+            and type(v) is type(ov)
+        ):
+            target[ok] = v + ov
+        # 否则使用有效的值
+        else:
+            target[ok] = v or ov

u_toolkit/path.py

@@ -0,0 +1,4 @@
+def path(*subpath) -> str:
+    return "/" + "/".join(
+        f"{i}".removeprefix("/").removesuffix("/") for i in subpath
+    )

u_toolkit/pydantic/fields.py

@@ -0,0 +1,24 @@
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import Field, PlainSerializer
+
+from u_toolkit.datetime import to_naive, to_utc, to_utc_naive
+
+
+DBSmallInt = Annotated[int, Field(ge=-32768, le=32767)]
+DBInt = Annotated[int, Field(ge=-2147483648, le=2147483647)]
+DBBigInt = Annotated[
+    int, Field(ge=-9223372036854775808, le=9223372036854775807)
+]
+DBSmallSerial = Annotated[int, Field(ge=1, le=32767)]
+DBIntSerial = Annotated[int, Field(ge=1, le=2147483647)]
+DBBigintSerial = Annotated[int, Field(ge=1, le=9223372036854775807)]
+
+
+# 去除时区信息
+NaiveDatetime = Annotated[datetime, PlainSerializer(to_naive)]
+# 将时区转成 UTC
+UTCDateTime = Annotated[datetime, PlainSerializer(to_utc)]
+# 将时间转成 UTC, 并且去除时区信息
+UTCNaiveDateTime = Annotated[datetime, PlainSerializer(to_utc_naive)]

u_toolkit/pydantic/models.py

@@ -0,0 +1,41 @@
+from datetime import datetime
+from typing import Annotated, Any
+
+from pydantic import BaseModel, ConfigDict, WrapSerializer
+
+from u_toolkit.alias_generators import to_camel
+from u_toolkit.datetime import to_utc
+
+from .type_vars import BaseModelT
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+class CamelModel(Model):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+        field_title_generator=to_camel,
+    )
+
+
+def convert_to_utc(value: Any, handler, info) -> dict[str, datetime]:
+    # Note that `helper` can actually help serialize the `value` for
+    # further custom serialization in case it's a subclass.
+    partial_result = handler(value, info)
+    if info.mode == "json":
+        return {
+            k: to_utc(datetime.fromisoformat(v))
+            for k, v in partial_result.items()
+        }
+
+    return {k: to_utc(v) for k, v in partial_result.items()}
+
+
+ConvertToUTCModel = Annotated[BaseModelT, WrapSerializer(convert_to_utc)]

u_toolkit/pydantic/type_vars.py

@@ -0,0 +1,6 @@
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+
+BaseModelT = TypeVar("BaseModelT", bound=BaseModel)

u_toolkit/signature.py

@@ -0,0 +1,74 @@
+import inspect
+from collections.abc import Callable, Sequence
+from functools import partial
+from typing import Annotated, Any, overload
+
+
+def list_parameters(fn: Callable, /) -> list[inspect.Parameter]:
+    signature = inspect.signature(fn)
+    return list(signature.parameters.values())
+
+
+@overload
+def with_parameter(
+    fn: Callable, *, name: str, annotation: type | Annotated
+) -> tuple[list[inspect.Parameter], inspect.Parameter, int]: ...
+@overload
+def with_parameter(
+    fn: Callable, *, name: str, default: Any
+) -> tuple[list[inspect.Parameter], inspect.Parameter, int]: ...
+@overload
+def with_parameter(
+    fn: Callable, *, name: str, annotation: type | Annotated, default: Any
+) -> tuple[list[inspect.Parameter], inspect.Parameter, int]: ...
+
+
+def with_parameter(
+    fn: Callable,
+    *,
+    name: str,
+    annotation: type | Annotated | None = None,
+    default: Any = None,
+) -> tuple[list[inspect.Parameter], inspect.Parameter, int]:
+    kwargs = {}
+    if annotation is not None:
+        kwargs["annotation"] = annotation
+    if default is not None:
+        kwargs["default"] = default
+
+    parameters = list_parameters(fn)
+    parameter = inspect.Parameter(
+        name=name, kind=inspect.Parameter.KEYWORD_ONLY, **kwargs
+    )
+    index = -1
+    if parameters and parameters[index].kind == inspect.Parameter.VAR_KEYWORD:
+        parameters.insert(index, parameter)
+        index = -2
+    else:
+        parameters.append(parameter)
+
+    return parameters, parameter, index
+
+
+def update_signature(
+    fn: Callable,
+    *,
+    parameters: Sequence[inspect.Parameter] | None = None,
+    return_annotation: type | None = None,
+):
+    signature = inspect.signature(fn)
+    kwargs = {}
+    if parameters:
+        kwargs["parameters"] = parameters
+    if return_annotation:
+        kwargs["return_annotation"] = return_annotation
+
+    fn.__signature__ = signature.replace(**kwargs)  # type: ignore
+
+
+def update_parameters(fn: Callable, *parameters: inspect.Parameter):
+    update_signature(fn, parameters=parameters)
+
+
+def update_return_annotation(fn: Callable, return_annotation: type, /):
+    update_signature(fn, return_annotation=return_annotation)

u_toolkit/sqlalchemy/function.py

@@ -0,0 +1,12 @@
+import sqlalchemy as sa
+from sqlalchemy.orm import DeclarativeBase, QueryableAttribute
+
+
+def json_object_build(
+    label: str,
+    table: type[DeclarativeBase],
+    *attrs: QueryableAttribute | sa.Column,
+):
+    return sa.func.json_build_object(
+        *[sa.text(f"'{i.key}', {table.__tablename__}.{i.key}") for i in attrs]
+    ).label(label)

u_toolkit/sqlalchemy/orm/fields.py

@@ -0,0 +1,20 @@
+from functools import partial
+from typing import Annotated
+from uuid import UUID, uuid4
+
+from sqlalchemy import BIGINT
+from sqlalchemy.orm import mapped_column
+
+
+primary_key_column = partial(mapped_column, primary_key=True, sort_order=-9999)
+
+IntPrimaryKey = Annotated[int, primary_key_column()]
+BigIntPrimaryKey = Annotated[int, primary_key_column(BIGINT)]
+
+_auto_pk = partial(primary_key_column, autoincrement=True)
+
+AutoIntPrimaryKey = Annotated[int, _auto_pk()]
+AutoBigIntPrimaryKey = Annotated[int, _auto_pk(BIGINT)]
+
+
+UUID4PrimaryKey = Annotated[UUID, primary_key_column(default=uuid4)]

u_toolkit/sqlalchemy/orm/models.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+
+from pydantic.alias_generators import to_snake
+from sqlalchemy import func
+from sqlalchemy.orm import Mapped, declared_attr, mapped_column
+
+
+class TablenameMixin:
+    # 当继承该类时, 会自动将表名转为 snake 名称形式
+    @declared_attr.directive
+    @classmethod
+    def __tablename__(cls) -> str:
+        return f"{to_snake(cls.__name__)}_tb"
+
+
+class TimeStampMixin:
+    # 当继承该类时, 会给表添加创建时间和更新时间字段
+    created_at: Mapped[datetime] = mapped_column(
+        server_default=func.now(), sort_order=9998
+    )
+    updated_at: Mapped[datetime | None] = mapped_column(
+        onupdate=func.now(), sort_order=9999
+    )

u_toolkit/sqlalchemy/table_info.py

@@ -0,0 +1,17 @@
+import sqlalchemy as sa
+from pydantic import TypeAdapter
+
+from .type_vars import DeclarativeBaseT
+
+
+class TableInfo:
+    def __init__(self, table: type[DeclarativeBaseT]) -> None:
+        self.table = table
+        self.columns = sa.inspect(table).c
+        self.adapters = {
+            i.name: (
+                TypeAdapter(i.type.python_type),
+                i.type.python_type,
+            )
+            for i in self.columns
+        }

u_toolkit/sqlalchemy/type_vars.py

@@ -0,0 +1,6 @@
+from typing import TypeVar
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+DeclarativeBaseT = TypeVar("DeclarativeBaseT", bound=DeclarativeBase)

u_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: u-toolkit
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.11.3
+Provides-Extra: fastapi
+Requires-Dist: pydantic-settings>=2.9.1; extra == 'fastapi'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0.40; extra == 'sqlalchemy'

u_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+u_toolkit/__init__.py,sha256=7f_bFg1UERA4gyh3HjCAjOZo2cBUgElpwgX5x-Xk2WA,238
+u_toolkit/alias_generators.py,sha256=KmPL1ViGJjptONffZUAX4ENvkldrwDylm_Ly5RYE8b4,963
+u_toolkit/datetime.py,sha256=GOG0xa6yKeqvFXJkImK5Pt7wsPXnHMlNKju8deniGJ4,644
+u_toolkit/decorators.py,sha256=i6dCahV4AHQPwpW48Q55vxMYvcq8GC1noq1SpVE-xjE,1229
+u_toolkit/enum.py,sha256=2yWmK8V1q0P5S3ltBED-TF2H09BmRbsBuqu3Th3G1NE,862
+u_toolkit/function.py,sha256=GAE6TIm5jpemUiNUPjzk7pIHrxwSSX7sHl1V5E735dE,252
+u_toolkit/helpers.py,sha256=K3FCz93K1nT4o7gWKVpMKy3k3BnirTPCSb8F8EFUrWk,112
+u_toolkit/logger.py,sha256=NOmdR24QfSuo1EMnetyFioa8pA8OYceYTlQ4qiQcBdE,209
+u_toolkit/merge.py,sha256=kHrloud-nPti5j48zkdvaiy4mIJYqOVguixAjWC46kE,924
+u_toolkit/object.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u_toolkit/path.py,sha256=IkyIHcU9hKBCOZfF30FrKf4CfL-MH91fjeYF9EY7eos,128
+u_toolkit/signature.py,sha256=jjIhyqTV3XL_tjPeA4l8dFnF5TybHd4AHF_g_2G2uAg,2168
+u_toolkit/fastapi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u_toolkit/fastapi/cbv.py,sha256=fuZCe6An75D3ernxFk6BLta_27VpoXvxBgwhToiCMIA,9940
+u_toolkit/fastapi/config.py,sha256=kGpokR9XXr1KxMA1GVKYkCdKwqIQAIwOJ-v6sGbqzAQ,267
+u_toolkit/fastapi/exception.py,sha256=5E4wAJYwp0RJ4SEBVkchOgrgfwCgniQ8Mtg1O5sWUXE,3288
+u_toolkit/fastapi/helpers.py,sha256=BCMMLxa1c6BMA_rKq-hCi0iyEjrR3Z5rPMeTvgaVJB0,447
+u_toolkit/fastapi/lifespan.py,sha256=W1TwWymW7xtmntx59QBC4LQ6xQr3L7yuMMGj4U8hhTQ,1813
+u_toolkit/fastapi/pagination.py,sha256=yOgEDUT04m_mZ0cPliuDbUHLFnmxGAmr5PyZlwfjT_s,1940
+u_toolkit/fastapi/responses.py,sha256=ZxxFCQpahS1I0ilB-XYW6_cqq1Qscu950iMauq7Oi5E,1740
+u_toolkit/pydantic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u_toolkit/pydantic/fields.py,sha256=9I8Jwek_oNn_niI98ZWaSPEUYIl5mw24YgbnpcEtgZk,839
+u_toolkit/pydantic/models.py,sha256=Dqp3HnPlUU7ZpfBbYbERfcrLUb2CBJKHySRvM1Rv3HE,1101
+u_toolkit/pydantic/type_vars.py,sha256=XBB3r2SipHOIeyCIuhaBwUDuIfm-M8aI3Gg8rx2uT_A,113
+u_toolkit/sqlalchemy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u_toolkit/sqlalchemy/fields.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u_toolkit/sqlalchemy/function.py,sha256=DRkszvqDfl-BKBW9IcYeN665pgDYlwWiC3DOCjBnxGY,345
+u_toolkit/sqlalchemy/table_info.py,sha256=EjY2Vxbw2c6TUGBf3NeJl1BB2Tnn9NfaFikUx9I3BBk,441
+u_toolkit/sqlalchemy/type_vars.py,sha256=m2VeV41CBIK_1QX3w2kgz-n556sILAGZ-Kaz3TDDDIY,143
+u_toolkit/sqlalchemy/orm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+u_toolkit/sqlalchemy/orm/fields.py,sha256=3zoYil23I6YLtc_59aHDt9w5l1NBTkePT9AfXI3DMiY,593
+u_toolkit/sqlalchemy/orm/models.py,sha256=V8vf4ps3phAmwxyaFYK7pw8Igz7h097o4QBjKB0gwC8,705
+u_toolkit-0.1.0.dist-info/METADATA,sha256=bVnbba44m98h7Pemhx8jpKivqb0w3458KX84204IkF8,312
+u_toolkit-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+u_toolkit-0.1.0.dist-info/entry_points.txt,sha256=hTfAYCd5vvRiqgnJk2eBsoRIiIVB9pK8WZm3Q3jjKFU,45
+u_toolkit-0.1.0.dist-info/RECORD,,

u_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

u_toolkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+u-toolkit = u_toolkit:main