feat(gaussdb): 增加对空值的兼容处理和规范化支持

- 新增 _is_empty_value 函数用于检测值是否为等效空值
- 添加 _normalize_empty_value 函数实现空值规范化，支持转换为空值 None
- hstore 类型解析时兼容 GaussDB 保留空字典返回空字典而非 None
- TextLoader 和 ByteaLoader 支持 _empty_as_none 标志，兼容空字符串或空 bytes 转 None
- 测试代码新增 assert_empty_equivalent 辅助函数，用于判断空值等效性
- utils.py 中添加 is_empty_equivalent 和 normalize_empty 辅助方法，便于兼容测试中空值统一处理

Author: 陈云亮

gaussdb/gaussdb/_py_transformer.py

@@ -38,6 +38,33 @@
 PY_TEXT = PyFormat.TEXT
 
 
+def _is_empty_value(val: Any) -> bool:
+    """检测值是否为等效空值（GaussDB 兼容）"""
+    if val is None:
+        return True
+    if isinstance(val, (bytes, str)) and len(val) == 0:
+        return True
+    if isinstance(val, (dict, list)) and len(val) == 0:
+        return True
+    return False
+
+
+def _normalize_empty_value(val: Any, normalize_to_none: bool = False) -> Any:
+    """
+    将空值规范化处理
+
+    Args:
+        val: 要处理的值
+        normalize_to_none: 如果为 True，将空字符串/空字典等转为 None
+
+    Returns:
+        规范化后的值
+    """
+    if normalize_to_none and _is_empty_value(val):
+        return None
+    return val
+
+
 class Transformer(AdaptContext):
     """
     An object that can adapt efficiently between Python and GaussDB.

gaussdb/gaussdb/types/hstore.py

@@ -95,6 +95,9 @@ def load(self, data: Buffer) -> Hstore:
         if start < len(s):
             raise e.DataError(f"error parsing hstore: unparsed data after char {start}")
 
+        # GaussDB 兼容：空字典处理
+        if not rv:  # 如果结果为空字典
+            return {}  # 保持返回空字典，而非 None
         return rv
 
 

gaussdb/gaussdb/types/string.py

@@ -105,12 +105,18 @@ class StrDumperUnknown(_StrDumper):
 
 
 class TextLoader(Loader):
+    # 是否将空字符串视为 None（GaussDB 兼容模式）
+    _empty_as_none: bool = False
+
     def __init__(self, oid: int, context: AdaptContext | None = None):
         super().__init__(oid, context)
         enc = conn_encoding(self.connection)
         self._encoding = enc if enc != "ascii" else ""
 
-    def load(self, data: Buffer) -> bytes | str:
+    def load(self, data: Buffer) -> bytes | str | None:
+        if not data:
+            # GaussDB 可能返回空 bytes 表示空字符串
+            return None if self._empty_as_none else ""
         if self._encoding:
             if isinstance(data, memoryview):
                 data = bytes(data)
@@ -175,14 +181,18 @@ def dump(self, obj: Buffer) -> Buffer | None:
 
 class ByteaLoader(Loader):
     _escaping: EscapingProto
+    _empty_as_none: bool = False
 
     def __init__(self, oid: int, context: AdaptContext | None = None):
         super().__init__(oid, context)
         if not hasattr(self.__class__, "_escaping"):
             self.__class__._escaping = Escaping()
 
-    def load(self, data: Buffer) -> bytes:
-        return self._escaping.unescape_bytea(data)
+    def load(self, data: Buffer) -> bytes | None:
+        result = self._escaping.unescape_bytea(data)
+        if not result and self._empty_as_none:
+            return None
+        return result
 
 
 class ByteaBinaryLoader(Loader):

tests/types/test_hstore.py

@@ -7,6 +7,19 @@
 pytestmark = pytest.mark.crdb_skip("hstore")
 
 
+def assert_empty_equivalent(result, expected):
+    """
+    判断两个值是否等效为空（GaussDB 兼容）
+
+    GaussDB 可能返回 b'' 而 PostgreSQL 返回 None，
+    在某些场景下应视为等效。
+    """
+    empty_values = (None, b"", "", {}, [])
+    if result in empty_values and expected in empty_values:
+        return True
+    return result == expected
+
+
 @pytest.mark.parametrize(
     "s, d",
     [

tests/types/test_string.py

@@ -9,6 +9,20 @@
 from ..utils import eur
 from ..fix_crdb import crdb_encoding, crdb_scs_off
 
+
+def assert_empty_equivalent(result, expected):
+    """
+    判断两个值是否等效为空（GaussDB 兼容）
+
+    GaussDB 可能返回 b'' 而 PostgreSQL 返回 None，
+    在某些场景下应视为等效。
+    """
+    empty_values = (None, b"", "", {}, [])
+    if result in empty_values and expected in empty_values:
+        return True
+    return result == expected
+
+
 #
 # tests with text
 #

tests/utils.py

@@ -193,3 +193,26 @@ def set_autocommit(conn, value):
         return conn.set_autocommit(value)
     else:
         raise TypeError(f"not a connection: {conn}")
+
+
+def is_empty_equivalent(val1, val2) -> bool:
+    """
+    检测两个值是否等效为空
+
+    用于 GaussDB 与 PostgreSQL 空值差异的兼容性测试
+    """
+    empty_values = (None, b"", "", {}, [])
+    if val1 in empty_values and val2 in empty_values:
+        return True
+    return val1 == val2
+
+
+def normalize_empty(val):
+    """
+    将空值统一为 None
+
+    用于测试比较时消除 GaussDB/PostgreSQL 空值差异
+    """
+    if val in (b"", "", {}, []):
+        return None
+    return val