lush-stdx 0.1.0__tar.gz

lush_stdx-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.3
+Name: lush-stdx
+Version: 0.1.0
+Summary: see README.md
+Author: straydragon
+Requires-Dist: pydantic>=2.11.0,<3.0.0
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# lush-stdx
+
+一些我经常复用的标准库小工具. 没有大而全的野心,只要它们还能保持“小”,就放这里.
+
+## 例子
+
+```python
+from lush_stdx.langx import OptionT
+from lush_stdx.urllibx import url_update_params
+
+box = OptionT("hello")
+assert box.unwrap() == "hello"
+
+url = url_update_params("https://example.com?a=1", {"b": "2"})
+assert url == "https://example.com?a=1&b=2"
+```
+
+## 开发
+
+```bash
+uv sync -p 3.10 --frozen
+uv run -p 3.10 pytest
+```

lush_stdx-0.1.0/README.md

@@ -0,0 +1,23 @@
+# lush-stdx
+
+一些我经常复用的标准库小工具. 没有大而全的野心,只要它们还能保持“小”,就放这里.
+
+## 例子
+
+```python
+from lush_stdx.langx import OptionT
+from lush_stdx.urllibx import url_update_params
+
+box = OptionT("hello")
+assert box.unwrap() == "hello"
+
+url = url_update_params("https://example.com?a=1", {"b": "2"})
+assert url == "https://example.com?a=1&b=2"
+```
+
+## 开发
+
+```bash
+uv sync -p 3.10 --frozen
+uv run -p 3.10 pytest
+```

lush_stdx-0.1.0/pyproject.toml

@@ -0,0 +1,239 @@
+[project]
+name = "lush-stdx"
+version = "0.1.0"
+description = "see README.md"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "straydragon" }]
+dependencies = [
+    "pydantic>=2.11.0,<3.0.0",
+    "typing-extensions>=4.7.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = [
+    "freezegun>=1.5.5",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+    "pytest-cov>=6.2.1",
+]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib --cov=lush_stdx --cov-report=term-missing"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
+
+[tool.ruff]
+line-length = 140
+indent-width = 4
+target-version = "py310"
+
+[tool.ruff.lint]
+fixable = ["F401", "ALL"]
+unfixable = []
+
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+select = ["ALL"]
+ignore = [
+    # === 代码质量与复杂性 ===
+    "C901",    # 函数复杂度过高,影响可读性
+    "PLR0912", # 函数分支过多,建议重构
+    "PLR0913", # 函数参数过多,难以维护
+    "PLR0915", # 函数语句过多,建议拆分
+    "PLR0911", # 函数返回语句过多,逻辑复杂
+    "PLR2004", # 使用魔术数值,建议使用常量
+    "SIM108",  # 更倾向于使用ifelse表达式,而不是if/else语句
+
+    # === 类型注解 ===
+    "ANN002", # 函数*args参数缺少类型注解
+    "ANN003", # 函数**kwargs参数缺少类型注解
+    "ANN401", # 使用Any类型,建议使用具体类型
+
+    # === 函数参数设计 ===
+    "FBT001", # 布尔类型位置参数,易混淆
+    "FBT002", # 布尔默认值位置参数,易误用
+    "N805",   # 与pydantic field_validator冲突(cls->self X), 先忽略, 后面再处理
+
+    # === 异常处理 ===
+    "BLE001", # 捕获所有异常,隐藏问题
+    "TRY003", # 异常消息应在类中定义
+    "TRY004", # 类型检查应抛出TypeError
+
+    # === 代码简化 ===
+    "SIM102", # 可折叠的if语句,简化代码
+
+    # === 格式规范 ===
+    "COM812", # 缺少尾随逗号,影响diff
+    "E501",   # 行长度过长,影响可读性
+
+    # === 日志记录 ===
+    "G004", # 日志使用f-string,影响性能
+
+    # === 类型检查优化 ===
+    "TC001", # 仅用于类型检查的导入,优化性能
+    "TC002", # 仅用于类型检查的导入,优化性能
+    "TC003", # 仅用于类型检查的导入,优化性能
+
+    # === 代码清理 ===
+    "ERA001", # 注释掉的代码,应删除
+
+    # === 私有成员访问 ===
+    "SLF001", # 访问私有成员,破坏封装
+
+    # === 日期时间处理 ===
+    "DTZ001", # datetime缺少时区信息
+    "DTZ005", # datetime.now()缺少时区
+
+    # === 调试代码 ===
+    "T201", # print语句调试代码,生产环境禁用
+
+    # === T O D O管理 ===
+    "TD002", # 缺少作者信息
+    "TD003", # 缺少问题链接
+
+    # === 其他 ===
+    "D",  # 文档字符串相关规则
+    "EM", # 错误消息相关规则
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    # === 测试代码质量 ===
+    "B011",    # assert False应改为raise AssertionError
+    "B008",    # 函数调用作为默认参数
+    "ARG001",  # 未使用的函数参数
+    "ARG002",  # 未使用的方法参数
+    "ARG005",  # lambda中未使用的参数
+    "F841",    # 未使用的变量
+    "B018",    # 无用的表达式
+    "N806",    # 函数中非小写变量名
+    "W293",    # 空行包含空格
+    "N802",    # 函数名不规范
+    "PERF401", # 性能相关
+    "PT",      # assert 相关
+
+    # === 测试安全相关 ===
+    "S101", # assert语句(测试中使用)
+    "S105", # 硬编码密码字符串
+    "S201", # Flask debug=True
+    "S301", # 可疑的pickle使用
+    "S311", # 非加密安全的随机数
+
+    # === 测试异常处理 ===
+    "BLE001", # 捕获所有异常
+    "B017",   # assertRaises捕获Exception
+    "PT011",  # pytest.raises缺少match参数
+    "PT017",  # except中的assert语句
+    "EM101",  # 异常中的原始字符串
+
+    # === 测试代码复杂度 ===
+    "C901",    # 函数复杂度过高
+    "PLR2004", # 魔术数值
+
+    # === 测试导入相关 ===
+    "PLC0415", # 函数内import语句
+    "ANN",     # 类型注解(测试中宽松)
+    "TC",      # 类型检查的导入
+
+    # === 测试参数设计 ===
+    "FBT001", # 布尔类型位置参数
+    "FBT002", # 布尔默认值位置参数
+    "FBT003", # 布尔位置参数调用
+
+    # === 测试异常处理 ===
+    "TRY003", # 异常消息定义
+
+    # === 测试代码简化 ===
+    "SIM117", # 多个连续的with语句
+
+    # === 测试格式规范 ===
+    "E501", # 行长度过长
+
+    # === 测试日志处理 ===
+    "G004", # 日志使用f-string
+
+    # === 测试调试代码 ===
+    "T201", # print语句
+
+    # === 测试文档相关 ===
+    "D", # 文档字符串
+
+    # === 测试私有访问 ===
+    "SLF001", # 私有成员访问
+
+    # === 测试Unicode ===
+    "RUF001", # 模糊的Unicode字符
+
+    # === 测试路径处理 ===
+    "PTH", # pathlib相关规则
+
+    # === 测试日期时间 ===
+    "DTZ001", # datetime缺少时区
+    "DTZ005", # datetime.now()缺少时区
+
+    # === 测试代码清理 ===
+    "ERA001", # 注释掉的代码
+
+    "RUF",
+]
+"**/*.ipynb" = ["ALL"]
+"**/notebooks/marino/*.py" = ["ALL"]
+
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+# ============================================================================
+# basedpyright 配置 - 独立包配置
+# ============================================================================
+[tool.basedpyright]
+pythonVersion = "3.10"
+
+reportUnannotatedClassAttribute = "none"
+reportUnreachable = "none"
+reportUnnecessaryIsInstance = "none"
+reportAny = "none"
+reportExplicitAny = "none"
+reportConstantRedefinition = "none"
+reportUnnecessaryComparison = "none"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+reportUnusedCallResult = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportExplicitAny = "none"
+reportAny = "none"
+reportUnusedParameter = false
+reportUnusedVariable = false
+reportMissingTypeArgument = false
+reportArgumentType = false
+reportOptionalMemberAccess = false
+reportAttributeAccessIssue = "none"
+reportGeneralTypeIssues = false
+reportCallIssue = false
+reportReturnType = false
+reportPrivateUsage = false
+reportUnusedClass = false
+
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src"

lush_stdx-0.1.0/src/lush_stdx/__init__.py

@@ -0,0 +1,6 @@
+"""lush-stdx: 标准工具集 (enumx/functoolx/itertoolsx/timex/langx)."""
+
+from . import enumx, langx, timex
+from .langx import OptionT
+
+__all__ = ["OptionT", "enumx", "langx", "timex"]

lush_stdx-0.1.0/src/lush_stdx/enumx/__init__.py

@@ -0,0 +1,191 @@
+import dataclasses
+import enum
+from typing import Any
+
+from pydantic import GetJsonSchemaHandler
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import ValidationError as PydanticValidationError
+from pydantic_core import core_schema
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class XMetaInfo:
+    description: str = ""
+    display_text: str = ""
+
+
+class MetaInfoIntEnum(enum.IntEnum):
+    """
+    IntEnum with XMetaInfo
+
+    Most of behavior like IntEnum, and you can use ._x_meta to get the pre-defined XMetaInfo
+    """
+
+    def __new__(cls, value: int, meta: XMetaInfo) -> "MetaInfoIntEnum":
+        obj = int.__new__(cls, value)
+        obj._value_ = value
+        obj._x_meta = meta  # pyright: ignore[reportAttributeAccessIssue ]
+        return obj
+
+    @classmethod
+    def to_db_field_comment(cls) -> str:
+        return " ".join([f"{i.value}: {i.x_meta.description}" for i in cls])
+
+    @property
+    def x_meta(self) -> XMetaInfo:
+        return self._x_meta  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType,reportUnknownVariableType ]
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> core_schema.CoreSchema:
+        base_schema = handler(source_type)
+
+        def wrap_validator(value: Any, validator: core_schema.ValidatorFunctionWrapHandler) -> enum.Enum:
+            if isinstance(value, cls):
+                return validator(value)
+
+            original_value = value
+
+            if isinstance(value, str):
+                try:
+                    value = int(value)
+                except (ValueError, TypeError) as exc:
+                    raise ValueError(f"'{original_value}' is not a valid member of {cls.__name__}") from exc
+
+            try:
+                return validator(value)
+            except (PydanticValidationError, TypeError, ValueError) as exc:
+                raise ValueError(f"'{original_value}' is not a valid value for {cls.__name__}") from exc
+
+        schema = core_schema.no_info_wrap_validator_function(wrap_validator, base_schema)
+        schema["serialization"] = core_schema.plain_serializer_function_ser_schema(lambda x: x.value if hasattr(x, "value") else x)
+        return schema
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler) -> JsonSchemaValue:
+        json_schema = handler(core_schema)
+        json_schema = handler.resolve_ref_schema(json_schema)
+
+        descriptions = [f"* `{member.value}`: {member._x_meta.description}" for member in cls]  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType]
+        schema_description = "枚举值:\n\n" + "\n".join(descriptions)
+
+        # 为 MetaInfoIntEnum 明确设置为 integer 类型(不支持 string)
+        json_schema.update(
+            type="integer",
+            description=schema_description,
+            enum=[member.value for member in cls],
+            **{
+                "x-enum-module": cls.__module__,
+                "x-enum-class": cls.__qualname__,
+            },
+        )
+        return json_schema
+
+
+class MetaInfoStrEnum(str, enum.Enum):
+    """
+    StrEnum with XMetaInfo
+
+    Most of behavior like StrEnum, and you can use ._x_meta to get the pre-defined XMetaInfo
+    """
+
+    def __new__(cls, value: str, meta: XMetaInfo) -> "MetaInfoStrEnum":
+        obj = str.__new__(cls, value)
+        obj._value_ = value
+        obj._x_meta = meta  # pyright: ignore[reportAttributeAccessIssue ]
+        return obj
+
+    def __str__(self) -> str:  # pyright: ignore[reportImplicitOverride]
+        return self.value
+
+    @classmethod
+    def to_db_field_comment(cls) -> str:
+        return " ".join([f"{i.value}: {i.x_meta.description}" for i in cls])
+
+    @property
+    def x_meta(self) -> XMetaInfo:
+        return self._x_meta  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType,reportUnknownVariableType ]
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> core_schema.CoreSchema:
+        base_schema = handler(source_type)
+
+        def wrap_validator(value: Any, validator: core_schema.ValidatorFunctionWrapHandler) -> enum.Enum:
+            if isinstance(value, cls):
+                return validator(value)
+
+            if isinstance(value, str):
+                try:
+                    return validator(cls(value))
+                except ValueError:
+                    try:
+                        member = cls[value.upper()]
+                    except KeyError as exc:
+                        raise ValueError(f"'{value}' is not a valid value or name for {cls.__name__}") from exc
+                    return validator(member)
+
+            raise ValueError(f"Input for {cls.__name__} must be a string.")
+
+        schema = core_schema.no_info_wrap_validator_function(wrap_validator, base_schema)
+        schema["serialization"] = core_schema.plain_serializer_function_ser_schema(lambda x: x.value if hasattr(x, "value") else x)
+        return schema
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler) -> JsonSchemaValue:
+        json_schema = handler(core_schema)
+        json_schema = handler.resolve_ref_schema(json_schema)
+
+        descriptions = [f"* `{member.value}`: {member._x_meta.description}" for member in cls]  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType]
+        schema_description = "枚举值:\n\n" + "\n".join(descriptions)
+
+        # 为 MetaInfoStrEnum 明确设置为 string 类型
+        json_schema.update(
+            type="string",
+            description=schema_description,
+            enum=[member.value for member in cls],
+            **{
+                "x-enum-module": cls.__module__,
+                "x-enum-class": cls.__qualname__,
+            },
+        )
+        return json_schema
+
+
+class EnumField:
+    """
+    EnumField is a field (descriptor) that can be used to validate and serialize enum values.
+
+    It will automatically convert the value to the enum member, and you can use ._x_meta to get the pre-defined XMetaInfo
+    """
+
+    def __init__(self, enum_cls: type[enum.Enum]) -> None:
+        if not issubclass(enum_cls, enum.Enum):
+            raise TypeError("enum_cls must be subclass of enum.Enum")
+        self.enum_cls = enum_cls
+        self.private_name = None
+
+    def __set_name__(self, owner: Any, name: str) -> None:
+        self.private_name = f"_{name}"
+
+    def __get__(self, instance: Any, owner: Any) -> Any:
+        if instance is None:
+            return self
+        if self.private_name is None:
+            return None
+        return getattr(instance, self.private_name, None)
+
+    def __set__(self, instance: Any, value: Any) -> None:
+        if value is None:
+            setattr(instance, self.private_name, None)  # pyright: ignore[reportArgumentType]
+            return
+
+        try:
+            member = self.enum_cls(value)
+        except ValueError:
+            try:
+                if not isinstance(value, str):
+                    raise KeyError  # noqa: TRY301
+                member = self.enum_cls[value.upper()]
+            except KeyError:
+                raise ValueError(f"'{value}' is not a valid member, value or name for {self.enum_cls.__name__}") from None
+
+        setattr(instance, self.private_name, member)  # pyright: ignore[reportArgumentType]

lush_stdx-0.1.0/src/lush_stdx/enumx/compact.py

@@ -0,0 +1,44 @@
+import sys
+from enum import Enum
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum  # pragma: no cover
+else:
+    # copied from https://github.com/python/cpython/blob/1ae900424b3c888d2b2cc97e6ef780717813d658/Lib/enum.py#L1365
+    class ReprEnum(Enum):
+        """
+        Only changes the repr(), leaving str() and format() to the mixed-in type.
+        """
+
+    class StrEnum(str, ReprEnum):
+        """
+        Enum where members are also (and must be) strings
+        """
+
+        def __new__(cls, *values: str) -> "StrEnum":
+            "values must already be of type `str`"
+            if len(values) > 3:
+                raise TypeError(f"too many arguments for str(): {values!r}")
+            if len(values) == 1:
+                # it must be a string
+                if not isinstance(values[0], str):
+                    raise TypeError(f"{values[0]!r} is not a string")
+            if len(values) >= 2:
+                # check that encoding argument is a string
+                if not isinstance(values[1], str):
+                    raise TypeError(f"encoding must be a string, not {values[1]!r}")
+            if len(values) == 3:
+                # check that errors argument is a string
+                if not isinstance(values[2], str):
+                    raise TypeError(f"errors must be a string, not {values[2]!r}")
+            value = str(*values)
+            member = str.__new__(cls, value)
+            member._value_ = value
+            return member
+
+        @staticmethod
+        def _generate_next_value_(name: str, _start: int, _count: int, _last_values: list[str]) -> str:  # pyright: ignore[reportIncompatibleMethodOverride, reportImplicitOverride]
+            """
+            Return the lower-cased version of the member name.
+            """
+            return name.lower()

lush_stdx-0.1.0/src/lush_stdx/functoolx.py

@@ -0,0 +1,65 @@
+import time
+from collections.abc import Callable
+from functools import lru_cache, wraps
+from typing import Any, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+ONE_SECOND = 1
+ONE_MINUTE = 60
+ONE_HOUR = 60 * ONE_MINUTE
+ONE_DAY = 24 * ONE_HOUR
+ONE_WEEK = 7 * ONE_DAY
+
+
+def ttl_lru_cache(ttl: int, max_size: int = 128) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """带TTL(生存时间)的LRU缓存装饰器.
+
+    将 LRU(最近最少使用) 与 TTL(生存时间) 组合:
+    - 限制缓存容量,超限时淘汰最近最少使用的条目
+    - 在指定 TTL 时间片变化后,自动视为新的缓存键,从而实现过期
+
+    设计说明:
+    - 当 ``ttl <= 0`` 时,退化为纯 LRU 缓存(永不过期)
+    - 注意: Python 的 ``functools.lru_cache`` 默认不区分 ``1`` 与 ``1.0`` 的键.
+      本实现同样遵循该行为,默认会将 ``1`` 与 ``1.0`` 视为同一键.
+      若你需要区分,建议在调用时自行规范参数类型(例如显式转换为 ``str`` 或引入类型标签).
+
+    Args:
+        ttl: 生存时间(秒).``ttl<=0`` 表示永不过期
+        max_size: LRU 最大容量
+
+    Returns:
+        装饰器函数
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        # 为了保证 kwargs 顺序无关,我们将其转换为有序元组(sorted by key)
+        @lru_cache(maxsize=max_size, typed=False)
+        def cached_func(
+            _pos_args: tuple[Any, ...],
+            _kw_items: tuple[tuple[str, Any], ...],
+            _ttl_slice: int,
+        ) -> R:
+            return func(*_pos_args, **dict(_kw_items))
+
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # 计算时间分片: ttl>0 时按间隔划分,否则固定为 0
+            ttl_slice = int(time.time() // ttl) if ttl > 0 else 0
+            kw_items = tuple(sorted(kwargs.items()))
+            return cached_func(tuple(args), kw_items, ttl_slice)
+
+        def cache_clear() -> None:
+            cached_func.cache_clear()
+
+        def cache_info() -> Any:
+            return cached_func.cache_info()
+
+        wrapper.cache_clear = cache_clear  # pyright: ignore[reportAttributeAccessIssue]
+        wrapper.cache_info = cache_info  # pyright: ignore[reportAttributeAccessIssue]
+        return wrapper
+
+    return decorator

lush_stdx-0.1.0/src/lush_stdx/itertoolsx.py

@@ -0,0 +1,209 @@
+import itertools
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Iterable, Iterator, Sequence
+from typing import Protocol, TypeVar
+
+T = TypeVar("T")
+V = TypeVar("V")
+
+
+def filtered_in_sql_values(
+    values: Iterable[V] | None,
+    target_type_as: Callable[[V], T] = lambda x: x,
+) -> list[T]:
+    if not values:
+        return []
+
+    items: list[T] = []
+    seen = set[T]()
+
+    for item in values:
+        if item is None or item == "":
+            continue
+        try:
+            converted_value = target_type_as(item)
+            if converted_value not in seen:
+                seen.add(converted_value)
+                items.append(converted_value)
+        except (ValueError, TypeError):
+            continue
+
+    return items
+
+
+class IterPageFetchFunc(Protocol[T]):
+    async def __call__(self, *, offset: int, limit: int) -> list[T]: ...
+
+
+async def iter_page(
+    fetch_func: IterPageFetchFunc[T],
+    offset: int = 0,
+    limit: int = 100,
+    n_max_iters_or_none_limit: int | None = None,
+) -> AsyncIterator[list[T]]:
+    """
+    异步生成器, 分页请求数据并逐页 yield.
+
+    这个函数会不断调用用户提供的异步函数, 每次递增 offset,
+    逐页 yield 返回的数据, 直到没有更多数据或达到最大迭代次数限制.
+
+    Args:
+        fetch_func: 异步函数, 接受 offset 和 limit 关键字参数, 返回数据列表
+        offset: 起始偏移量, 默认为 0
+        limit: 每页大小, 默认为 100
+        n_max_iters_or_none_limit: 最大迭代次数, None 表示无限制, 默认为 None
+
+    Yields:
+        每一页的数据列表
+
+    Examples:
+        async def fetch_users(*, offset: int, limit: int) -> list[User]:
+            # 实现分页查询逻辑
+            pass
+
+        # 逐页处理用户数据
+        async for page in iter_page(fetch_users, limit=50):
+            process_page(page)
+    """
+    current_offset = offset
+    n_max_iters = int(n_max_iters_or_none_limit) if n_max_iters_or_none_limit is not None else None
+
+    while True:
+        if n_max_iters is not None:
+            if n_max_iters <= 0:
+                break
+            n_max_iters -= 1
+
+        paged_items = await fetch_func(offset=current_offset, limit=limit)
+
+        if not paged_items:
+            break
+
+        yield paged_items
+
+        if len(paged_items) < limit:
+            break
+
+        current_offset += limit
+
+
+def chunks(itr: Iterable[T], batch_size: int = 500) -> Iterator[list[T]]:
+    """将一个可迭代对象分割成指定大小的多个块 (chunks).
+
+    这个函数是一个生成器,它会懒加载地从输入的可迭代对象中
+    读取数据,并每次生成一个列表形式的数据块.这种实现方式对于
+    处理大型数据集非常高效,因为它不会一次性将所有数据加载到内存中.
+
+    Examples:
+        >>> my_list = list(range(10))
+        >>> for chunk in chunks(my_list, 4):
+        ...     print(chunk)
+        [0, 1, 2, 3]
+        [4, 5, 6, 7]
+        [8, 9]
+
+    """
+    if not isinstance(batch_size, int) or batch_size <= 0:
+        raise ValueError("batch_size 必须是一个正整数")
+
+    # 将可迭代对象转换为迭代器,以确保我们可以在其上持续调用 next()
+    it = iter(itr)
+    while True:
+        # 使用 islice 高效地获取下一个块,避免创建中间列表
+        chunk = list(itertools.islice(it, batch_size))
+        if not chunk:
+            # 当 islice 返回一个空列表时,表示原始迭代器已耗尽
+            return
+        yield chunk
+
+
+async def async_chunks(
+    aitr: AsyncIterable[T],
+    batch_size: int = 500,
+) -> AsyncIterator[list[T]]:
+    """将一个异步可迭代对象分割成指定大小的多个块 (chunks).
+
+    这个函数是一个异步生成器,它会从输入的异步可迭代对象中
+    异步地读取数据,并每次生成一个列表形式的数据块.这对于处理
+    异步数据流(例如,从数据库或网络 API 获取的数据)非常有用.
+
+    Examples:
+        ```python
+        import asyncio
+
+
+        async def async_generator():
+            for i in range(10):
+                yield i
+                await asyncio.sleep(0.01)
+
+
+        async def main():
+            async for chunk in async_chunks(async_generator(), 4):
+                print(chunk)
+
+
+        # 运行 `asyncio.run(main())` 将会输出:
+        # [0, 1, 2, 3]
+        # [4, 5, 6, 7]
+        # [8, 9]
+        ```
+    """
+    if not isinstance(batch_size, int) or batch_size <= 0:
+        raise ValueError("batch_size 必须是一个正整数")
+
+    batch: list[T] = []
+    ait = aiter(aitr)
+    async for item in ait:
+        batch.append(item)
+        if len(batch) >= batch_size:
+            yield batch
+            batch = []
+
+    if batch:
+        yield batch
+
+
+ItemT = TypeVar("ItemT")
+
+OffsetPaginationResult = tuple[Sequence[ItemT], int | None]
+
+
+def get_paged_items_and_cursor(
+    query_results: Sequence[ItemT],
+    offset: int,
+    size: int,
+) -> OffsetPaginationResult[ItemT]:
+    """
+    基于查询结果处理分页逻辑的辅助函数
+
+    用户需要自己调用查询函数,传入 size + 1 作为 limit,然后将结果传给这个函数处理
+
+    Args:
+        query_results: 查询结果,应该是用 size + 1 查询得到的
+        offset: 当前页的偏移量
+        size: 用户请求的页面大小
+
+    Returns:
+        tuple[list[ItemT], int | None]: (数据列表, 下一页offset或None)
+
+    Example:
+        ```python
+        # 用户自己控制查询调用
+        raw_results = await my_dal.page_users(
+            limit=size + 1,  # 关键:使用 size + 1
+            offset=offset,
+            status="active",
+            keyword="张",
+        )
+
+        # 处理分页逻辑
+        items, next_offset = get_paged_items_and_cursor(raw_results, offset, size)
+
+        return {"items": items, "next_offset": next_offset, "has_next": next_offset is not None}
+        ```
+    """
+    if len(query_results) <= size:
+        # 没有下一页,返回所有结果
+        return query_results, None
+    # 有下一页,截取前size个元素
+    return query_results[:size], offset + size

lush_stdx-0.1.0/src/lush_stdx/langx/__init__.py

@@ -0,0 +1,5 @@
+"""语言特性扩展."""
+
+from .optional import OptionT
+
+__all__ = ["OptionT"]

lush_stdx-0.1.0/src/lush_stdx/langx/optional.py

@@ -0,0 +1,55 @@
+"""语言特性扩展: OptionT 可选值容器."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from typing_extensions import override
+
+__all__ = ["OptionT"]
+
+T = TypeVar("T")
+
+
+class OptionT(Generic[T]):
+    """高性能可选值包装器 (类似 Rust 的 ``Option[T]``)."""
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: T | None = None) -> None:
+        self._value = value
+
+    def unwrap(self) -> T:
+        if self._value is None:
+            raise ValueError("OptionT value is None. Check with 'if box:' before calling .unwrap()")
+        return self._value
+
+    def unwrap_or(self, default: T) -> T:
+        return self._value if self._value is not None else default
+
+    def is_some(self) -> bool:
+        return self._value is not None
+
+    def is_none(self) -> bool:
+        return self._value is None
+
+    def __bool__(self) -> bool:
+        return self._value is not None
+
+    @override
+    def __repr__(self) -> str:
+        return f"OptionT({self._value!r})" if self._value is not None else "OptionT(None)"
+
+    @override
+    def __str__(self) -> str:
+        return str(self._value) if self._value is not None else "None"
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, OptionT):
+            return False
+        return self._value == other._value  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
+
+    @override
+    def __hash__(self) -> int:
+        return hash(self._value)

lush_stdx-0.1.0/src/lush_stdx/timex/__init__.py

@@ -0,0 +1,63 @@
+"""时间工具函数合集.
+
+原位于 ``lush-timex`` 包, 现并入 ``lush-stdx`` 便于统一维护.
+"""
+
+from __future__ import annotations
+
+import datetime
+from zoneinfo import ZoneInfo
+
+__all__ = [
+    "TZ_SHANGHAI",
+    "datetime_to_str",
+    "datetime_to_timestamp",
+    "str_to_datetime",
+    "timestamp_to_datetime",
+]
+
+
+def datetime_to_timestamp(dt: datetime.datetime) -> int:
+    """将 ``datetime`` 对象转换为毫秒级时间戳."""
+
+    return int(dt.timestamp() * 1000)
+
+
+def datetime_to_str(dt: datetime.datetime) -> str:
+    """格式化 ``datetime`` 为 ``YYYY-MM-DD HH:MM:SS`` 字符串."""
+
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def str_to_datetime(d: datetime.datetime | datetime.date | str | None) -> datetime.datetime | None:
+    """将字符串/日期转换为 ``datetime``."""
+
+    if not d:
+        return None
+    if isinstance(d, datetime.datetime):
+        return d
+    if isinstance(d, datetime.date):
+        return datetime.datetime(d.year, d.month, d.day)
+    try:
+        return datetime.datetime.strptime(d, "%Y-%m-%d %H:%M:%S")  # noqa: DTZ007
+    except ValueError:
+        try:
+            return datetime.datetime.strptime(d, "%Y-%m-%d %H:%M:%S.%f")  # noqa: DTZ007
+        except ValueError:
+            try:
+                return datetime.datetime.strptime(d, "%Y-%m-%d")  # noqa: DTZ007
+            except ValueError:
+                return datetime.datetime.strptime(d, "%Y-%m-%d %H:%M")  # noqa: DTZ007
+
+
+TZ_SHANGHAI = ZoneInfo("Asia/Shanghai")
+"""默认时区: 上海."""
+
+
+def timestamp_to_datetime(
+    ts_seconds: float,
+    tzinfo: ZoneInfo | None = TZ_SHANGHAI,
+) -> datetime.datetime:
+    """将秒级时间戳转换为指定时区的 ``datetime``."""
+
+    return datetime.datetime.fromtimestamp(ts_seconds, tzinfo)

lush_stdx-0.1.0/src/lush_stdx/urllibx.py

@@ -0,0 +1,15 @@
+from urllib.parse import parse_qs, parse_qsl, urlencode, urlparse, urlunparse
+
+
+def url_update_params(url: str, params: dict[str, str]) -> str:
+    url_parts = list(urlparse(url))
+    query = dict(parse_qsl(url_parts[4]))
+    query.update(params)
+    url_parts[4] = urlencode(query)
+    return urlunparse(url_parts)
+
+
+def extract_query_param(url_like: str) -> dict[str, list[str]]:
+    parsed_url = urlparse(url_like)
+    query_str = parsed_url.query
+    return parse_qs(query_str)