v2.8.1: clear output dir for gen_openapi with --split, specify encoding (utf-8 by default) in env file reading, optimize file path and name handling in save() method, orm.Schema support using pk list in serialize() with orders, fix type resolve for many included field with concrete lookup

Author: voidZXL

docs/en/community/release.md

@@ -7,9 +7,9 @@ Release Date:  2025/9/10
 ### New features
 
 * API support **Server-Sent Events (SSE)**: [Use SSE in API](../../guide/api-route#server-sent-events)
-* Clien support handling Server-Sent Events (SSE) response:  [Handle SSE Response](../../guide/client#server-sent-events)
+* Client support handling Server-Sent Events (SSE) response:  [Handle SSE Response](../../guide/client#handle-server-sent-events-sse)
 * `@api` decorator added `timeout` parameter to specifiy the timeout for API function processing time or Client request timeout.
-* Added HTTP cache plugin: `api.Cache`: can handle HTTP caching like `Last-Modifed` / `Etag` automatically
+* Added HTTP cache plugin: `api.Cache`: can handle HTTP caching like `Last-Modified` / `Etag` automatically
 * Added search parameter `orm.Search`, support various search mode for multiple model fields: [Search Param](../../guide/schema-query/#search-param)
 * `orm.Schema` support defining request context variables (such as current request user / IP) and query request context fields by passing the current request object to `context` param of the serialize methods: [Use context vars in query function](../../guide/schema-query/#relational-query-function)
 * `meta gen_openapi` support `--split` parameter that spliting the API document in seperate files by endpoint, convenient for AI tools to parse and read

docs/zh/community/release.md

@@ -1,6 +1,6 @@
 # 版本发布记录
 
-## v2.8
+## v2.8.0
 
 发布时间：2025/9/10
 
@@ -9,7 +9,7 @@
 * API 接口支持 Server-Sent Events (SSE) 事件流响应： [API 中实现 SSE](../../guide/api-route#server-sent-events)
 * Client 客户端支持处理  Server-Sent Events (SSE) 等流式响应： [处理 SSE 响应](../../guide/client#server-sent-events)
 * `@api` 装饰器新增 `timeout` 参数，用于为 API 类的处理函数指定超时时间或为 Client 类的请求函数指定请求超时
-* 新增 HTTP 缓存插件 `api.Cache`：可以自动处理 Last-Modifed / Etag 等 HTTP 缓存机制
+* 新增 HTTP 缓存插件 `api.Cache`：可以自动处理 Last-Modified / Etag 等 HTTP 缓存机制
 * 新增搜索参数 `orm.Search`, 可以支持多种搜索模式对多个模型字段进行搜索匹配
 * `orm.Schema` 支持在查询函数中定义请求上下文参数（如当前请求用户 / IP），在序列化时通过 `context` 参数传当前请求对象实现请求上下文字段的查询
 * `meta gen_openapi` 命令支持 `--split` 参数，可以将 API 文档按照接口输出到独立的文件中，每个接口文档文件都包含接口的完整参数与响应定义，更方便 AI 工具解析读取

tests/test_1_orm/test_orm_schemas.py

@@ -1,3 +1,5 @@
+import utype.utils.exceptions
+
 from utilmeta.core import orm
 import pytest
 from django.db import models
@@ -19,6 +21,19 @@ def test_incorrect_related_model(self):
             class UserSchema(orm.Schema[User]):
                 followers: List[ContentSchema]
 
+    def test_multiple_single_field_type(self):
+        from app.models import User
+
+        class UserTestSchema(orm.Schema[User]):
+            follower_names = orm.Field('followers.username')
+
+        ft = UserTestSchema.__parser__.get_field('follower_names').type
+        assert getattr(ft, '__origin__', None) == list
+        assert ft([1, 2]) == ['1', '2']
+
+        with pytest.raises(utype.utils.exceptions.ParseError):
+            ft(['a' * 30])
+
     def test_non_exists_fields(self):
         from app.models import User, Article
 

tests/test_1_orm/test_schema_query.py

@@ -391,16 +391,32 @@ async def test_async_init_users_with_sync_query(self, service, db_using):
         assert user.top_2_articles[0].author_tag["name"] == "alice"
         assert user.top_2_articles[0].views == 103
 
+    def test_serialize_orders(self, service, db_using):
+        from app.schema import ArticleSchema
+        articles_1 = ArticleSchema.serialize(
+            [1, 2, 3], context=orm.QueryContext(using=db_using)
+        )
+        articles_2 = ArticleSchema.serialize(
+            [3, 2, 1], context=orm.QueryContext(using=db_using)
+        )
+        articles_3 = ArticleSchema.serialize(
+            [2, 3, 1], context=orm.QueryContext(using=db_using)
+        )
+        assert [a.pk for a in articles_1] == [1, 2, 3]
+        assert [a.pk for a in articles_2] == [3, 2, 1]
+        assert [a.pk for a in articles_3] == [2, 3, 1]
+
     @pytest.mark.asyncio
     async def test_async_serialize_articles(self, service, db_using):
         await self.refresh_db(db_using)
         from app.schema import ArticleSchema
         from app.models import Article
         articles = await ArticleSchema.aserialize(
-            [1, 2], context=orm.QueryContext(using=db_using)
+            [1, 2, 3], context=orm.QueryContext(using=db_using)
         )
-        assert len(articles) == 2
-        assert {a.pk for a in articles} == {1, 2}
+        assert [a.pk for a in articles] == [1, 2, 3]
+        # test pk order is equal to input list
+
         articles = await ArticleSchema.aserialize(
             Article.objects.filter(
                 slug='big-shot'

utilmeta/__init__.py

@@ -1,7 +1,7 @@
 __website__ = "https://utilmeta.com"
 __homepage__ = "https://utilmeta.com/py"
 __author__ = "Xulin Zhou (@voidZXL)"
-__version__ = "2.8.0"
+__version__ = "2.8.1"
 
 
 def version_info() -> str:

utilmeta/bin/meta.py

@@ -176,7 +176,7 @@ def gen_openapi(
             else:
                 to = f'openapi.{suffix}'
         if split:
-            path = OpenAPI.split_to(openapi, to, format=format)
+            path = OpenAPI.split_to(openapi, to, format=format, clear_dir=True)
         else:
             path = OpenAPI.save_to(openapi, to)
         print(f"OpenAPI document generated at {path}")

utilmeta/conf/env.py

@@ -18,12 +18,14 @@ def __init__(
         sys_env: Union[bool, str] = None,
         ref: str = None,
         file: str = None,
+        encoding: str = 'utf-8',
     ):
         self._data = data or {}
         self._sys_env = bool(sys_env)
         self._sys_env_prefix = sys_env if isinstance(sys_env, str) else ""
         self._ref = ref
         self._file = file
+        self._encoding = encoding
         for items in (
             self._load_from_ref(),
             self._load_from_file(),
@@ -78,17 +80,17 @@ def _load_from_file(self) -> Mapping:
                 self._file = rel_file
 
         if self._file.endswith(".json"):
-            return json.load(open(self._file, "r"))
+            return json.load(open(self._file, "r", encoding=self._encoding))
 
         if self._file.endswith(".yml") or self._file.endswith(".yaml"):
             from utilmeta.utils import requires
 
             requires(yaml="pyyaml")
             import yaml
 
-            return yaml.safe_load(open(self._file, "r"))
+            return yaml.safe_load(open(self._file, "r", encoding=self._encoding))
 
-        content = open(self._file, "r").read()
+        content = open(self._file, "r", encoding=self._encoding).read()
         data = {}
         for line in content.splitlines():
             if not line.strip():

utilmeta/core/api/specs/openapi.py

@@ -38,7 +38,7 @@
 import json
 import re
 import copy
-
+from pathlib import Path
 
 if TYPE_CHECKING:
     from utilmeta import UtilMeta
@@ -128,6 +128,18 @@ def normalize_dict(data: dict, key_orders: list):
     return sorted_dict
 
 
+def remove_files(directory, suffixes):
+    directory = Path(directory)
+    for suffix in suffixes:
+        for file in directory.glob(f"*{suffix}"):
+            if file.is_file():
+                try:
+                    file.unlink()
+                except Exception as e:
+                    print(f"Failed to delete {file}: {e}")
+                    continue
+
+
 class OpenAPIGenerator(JsonSchemaGenerator):
     DEFAULT_REF_PREFIX = "#/components/schemas/"
 
@@ -726,12 +738,19 @@ def _resolve_ref(cls, obj, root, visited=None):
             return obj
 
     @classmethod
-    def split_to(cls, openapi: dict, directory: str, format: str = 'json', compressed: bool = False):
+    def split_to(cls, openapi: dict, directory: str, format: str = 'json',
+                 compressed: bool = False,
+                 clear_dir: bool = False
+                 ):
         if not isinstance(openapi, OpenAPISchema):
             try:
                 openapi = OpenAPISchema(openapi)
             except Exception as e:
                 raise e.__class__(f'Invalid openapi schema: {openapi}, raised error: {e}') from e
+
+        if clear_dir and os.path.exists(directory):
+            remove_files(directory, suffixes=['.json'] if format == 'json' else ['.yml', '.yaml'])
+
         os.makedirs(directory, exist_ok=True)
 
         for path, methods in openapi.paths.items():

utilmeta/core/file/backends/base.py

@@ -56,19 +56,33 @@ def filename(self):
     def filepath(self):
         return None
 
-    def save(self, path: str, name: str = None):
-        file_path = path
-        name = name or self.filename
-        if name:
-            if not os.path.exists(file_path):
-                os.makedirs(file_path, exist_ok=True)
+    def _get_file_path(self, path: str, name: str = None):
+        file_path = path or ''
+        # 1. path exist:
+        #       is dir: as dir
+        #       not dir: as target file
+
+        if os.path.exists(file_path):
             if os.path.isdir(file_path):
-                file_path = os.path.join(file_path, name)
+                name = name or self.filename
+                if name:
+                    file_path = os.path.join(file_path, name)
+                else:
+                    raise PermissionError(
+                        f"Attempt to write file to directory: {file_path}"
+                    )
         else:
-            if os.path.isdir(file_path):
-                raise PermissionError(
-                    f"Attempt to write file to directory: {file_path}"
-                )
+            if name:
+                os.makedirs(file_path, exist_ok=True)
+                file_path = os.path.join(file_path, name)
+            else:
+                base_path = os.path.dirname(file_path)
+                # make sure base dir exists
+                os.makedirs(base_path, exist_ok=True)
+        return file_path
+
+    def save(self, path: str, name: str = None):
+        file_path = self._get_file_path(path, name=name)
         with open(file_path, "wb") as fp:
             if self.seekable:
                 self.object.seek(0)
@@ -80,14 +94,7 @@ def save(self, path: str, name: str = None):
         return file_path
 
     async def asave(self, path: str, name: str = None):
-        file_path = path
-        name = name or self.filename
-        if name:
-            if not os.path.exists(file_path):
-                os.makedirs(file_path, exist_ok=True)
-            if os.path.isdir(file_path):
-                file_path = os.path.join(file_path, name)
-
+        file_path = self._get_file_path(path, name=name)
         with open(file_path, "wb") as fp:
             if self.seekable:
                 r = self.object.seek(0)

utilmeta/core/file/base.py

@@ -95,10 +95,12 @@ def seekable(self):
         return self.adaptor.seekable
 
     def save(self, path: str, name: str = None):
-        return self.adaptor.save(path, name or self.filename)
+        # not pass adaptor.filename as name
+        # in case user want to just save to the path
+        return self.adaptor.save(path, name or self._filename)
 
     async def asave(self, path: str, name: str = None):
-        return await self.adaptor.asave(path, name or self.filename)
+        return await self.adaptor.asave(path, name or self._filename)
 
     def __iter__(self):
         return iter(self.file)