lib-x17-fintech 2.1.3__py3-none-any.whl

xfintech/fabric/column/tests/test_class_info_all.py

@@ -0,0 +1,207 @@
+import pytest
+
+from xfintech.fabric.column.info import ColumnInfo, ColumnKind
+
+
+def test_columninfo_basic_init():
+    col = ColumnInfo(
+        name="price",
+        kind="Float",
+        desc=" 股票价格 ",
+        meta={"unit": "CNY"},
+    )
+    assert col.name == "price"
+    assert col.kind == ColumnKind.FLOAT
+    assert col.desc == "股票价格"
+    assert col.meta == {"unit": "CNY"}
+
+
+def test_columninfo_name_must_be_valid():
+    with pytest.raises(ValueError):
+        ColumnInfo(name="1invalid")
+
+
+def test_columninfo_name_is_lowercase():
+    col = ColumnInfo(name="PriceHigh")
+    assert col.name == "pricehigh"
+
+
+def test_columninfo_kind_from_datakind_instance():
+    col = ColumnInfo(name="qty", kind=ColumnKind.INTEGER)
+    assert col.kind == ColumnKind.INTEGER
+    assert col.name == "qty"
+    assert col.meta is None
+
+
+def test_columninfo_kind_from_str_case_insensitive():
+    col = ColumnInfo(name="qty", kind="integer")
+    assert col.kind == ColumnKind.INTEGER
+    assert col.name == "qty"
+
+    col2 = ColumnInfo(name="qty", kind="InTeGeR")
+    assert col2.kind == ColumnKind.INTEGER
+    assert col2.name == "qty"
+
+
+def test_columninfo_invalid_kind():
+    col = ColumnInfo(name="x", kind="NOT_A_TYPE")
+    assert col.kind == ColumnKind.STRING
+    assert col.desc == ""
+    assert col.meta is None
+
+
+def test_columninfo_default_kind_string():
+    col = ColumnInfo(name="remark")
+    assert col.kind == ColumnKind.STRING
+    assert col.meta is None
+
+
+def test_columninfo_desc_strip():
+    col = ColumnInfo(
+        name="remark",
+        desc="  Something Here   ",
+    )
+    assert col.desc == "Something Here"
+    assert col.meta is None
+
+
+def test_columninfo_desc_empty_when_none():
+    col = ColumnInfo(name="remark", desc=None)
+    assert col.desc == ""
+    assert col.meta is None
+
+
+def test_columninfo_meta_bytes_to_str():
+    col = ColumnInfo(
+        name="flag",
+        meta={
+            b"bin": b"yes",
+            "code": b"ok",
+        },
+    )
+    assert col.meta == {"bin": "yes", "code": "ok"}
+    assert col.desc == ""
+
+
+def test_columninfo_meta_str_normal():
+    col = ColumnInfo(name="flag", meta={"x": 1})
+    assert col.meta == {"x": 1}
+    assert col.desc == ""
+
+
+def test_columninfo_update_kind_desc_meta():
+    col = ColumnInfo(
+        name="price",
+        kind="float",
+        desc="old",
+        meta={"unit": "CNY"},
+    )
+    col.update(
+        kind="integer",
+        desc="new-desc",
+        meta={"precision": 2},
+    )
+    assert col.kind == ColumnKind.INTEGER
+    assert col.desc == "new-desc"
+    assert col.meta == {"unit": "CNY", "precision": 2}
+    assert col.name == "price"
+
+
+def test_columninfo_add_methods():
+    col = ColumnInfo(name="level")
+    col.add_desc("some desc")
+    assert col.desc == "some desc"
+
+    col.add_meta("k", "v")
+    assert col.meta["k"] == "v"
+
+    col.add_kind("Boolean")
+    assert col.kind == ColumnKind.BOOLEAN
+
+
+def test_full_columninfo_to_dict_and_describe():
+    col = ColumnInfo(
+        name="amount",
+        kind="Float",
+        desc="amt",
+        meta={"unit": "usd"},
+    )
+    d1 = col.to_dict()
+    assert d1["name"] == "amount"
+    assert d1["kind"] == "Float"
+    assert d1["desc"] == "amt"
+    assert d1["meta"] == {"unit": "usd"}
+
+    d2 = col.describe()
+    assert d2["name"] == "amount"
+    assert d2["kind"] == "Float"
+    assert d2["desc"] == "amt"
+    assert d2["meta"] == {"unit": "usd"}
+
+
+def test_partial_columninfo_to_dict_and_describe():
+    col2 = ColumnInfo(
+        name="flag",
+        kind="Boolean",
+    )
+    d3 = col2.to_dict()
+    assert d3["name"] == "flag"
+    assert d3["kind"] == "Boolean"
+    assert d3["desc"] == ""
+    assert d3["meta"] is None
+
+    d4 = col2.describe()
+    assert d4["name"] == "flag"
+    assert d4["kind"] == "Boolean"
+    assert "desc" not in d4
+    assert "meta" not in d4
+
+
+def test_columninfo_str_and_repr():
+    col = ColumnInfo(name="price", kind="Float")
+    s = str(col)
+    assert "price: Float" in s
+
+    r = repr(col)
+    assert "name" in r
+    assert "price" in r
+    assert "Float" in r
+
+
+def test_columninfo_identifier_is_deterministic():
+    col1 = ColumnInfo(
+        name="amount",
+        kind="Float",
+        desc="amt",
+        meta={"unit": "usd"},
+    )
+    col2 = ColumnInfo(
+        name="amount",
+        kind="Float",
+        desc="amt",
+        meta={"unit": "usd"},
+    )
+    assert col1.identifier == col2.identifier
+
+
+def test_columninfo_identifier_not_change_with_meta():
+    col1 = ColumnInfo(
+        name="amount",
+        kind="Float",
+        desc="amt",
+        meta={"unit": "usd"},
+    )
+    col2 = ColumnInfo(
+        name="amount",
+        kind="Float",
+        desc="amt",
+        meta={"unit": "eur"},
+    )
+    col3 = ColumnInfo(
+        name="volume",
+        kind="Float",
+        desc="amt",
+        meta={"unit": "eur"},
+    )
+    assert col1.identifier == col2.identifier
+    assert col1.identifier != col3.identifier

xfintech/fabric/column/tests/test_class_kind_all.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from xfintech.fabric.column.kind import ColumnKind
+
+
+def test_datakind_members_exist():
+    assert ColumnKind.INTEGER.value == "Integer"
+    assert ColumnKind.FLOAT.value == "Float"
+    assert ColumnKind.STRING.value == "String"
+    assert ColumnKind.BOOLEAN.value == "Boolean"
+    assert ColumnKind.DATETIME.value == "Datetime"
+    assert ColumnKind.CATEGORICAL.value == "Categorical"
+    assert ColumnKind.DATE.value == "Date"
+
+
+def test_from_str_basic_cases():
+    assert ColumnKind.from_str("Integer") == ColumnKind.INTEGER
+    assert ColumnKind.from_str("Float") == ColumnKind.FLOAT
+    assert ColumnKind.from_str("String") == ColumnKind.STRING
+    assert ColumnKind.from_str("Boolean") == ColumnKind.BOOLEAN
+    assert ColumnKind.from_str("Datetime") == ColumnKind.DATETIME
+    assert ColumnKind.from_str("Categorical") == ColumnKind.CATEGORICAL
+
+
+def test_from_str_case_insensitive():
+    assert ColumnKind.from_str("integer") == ColumnKind.INTEGER
+    assert ColumnKind.from_str("FLOAT") == ColumnKind.FLOAT
+    assert ColumnKind.from_str("sTrInG") == ColumnKind.STRING
+    assert ColumnKind.from_str("boolean") == ColumnKind.BOOLEAN
+    assert ColumnKind.from_str("DATETIME") == ColumnKind.DATETIME
+    assert ColumnKind.from_str("cAtEgOrIcAl") == ColumnKind.CATEGORICAL
+
+
+def test_from_str_unknown_returns_unknown():
+    assert ColumnKind.from_str("SomethingElse") == ColumnKind.STRING
+    assert ColumnKind.from_str("") == ColumnKind.STRING
+    assert ColumnKind.from_str("???") == ColumnKind.STRING
+
+
+def test_str_representation():
+    assert str(ColumnKind.INTEGER) == "Integer"
+    assert str(ColumnKind.STRING) == "String"
+    assert str(ColumnKind.DATE) == "Date"
+
+
+def test_repr_representation():
+    assert repr(ColumnKind.INTEGER) == "ColumnKind.INTEGER"
+    assert repr(ColumnKind.CATEGORICAL) == "ColumnKind.CATEGORICAL"
+
+
+def test_equality_with_string():
+    assert ColumnKind.INTEGER == "Integer"
+    assert ColumnKind.FLOAT == "float"
+    assert ColumnKind.STRING != "Boolean"
+    assert ColumnKind.DATETIME != "datetime2"
+    assert ColumnKind.CATEGORICAL == "CATEGORICAL"
+
+
+def test_inequality_with_string():
+    assert ColumnKind.INTEGER != "Float"
+    assert ColumnKind.BOOLEAN != "boolean2"
+    assert ColumnKind.DATE != "DateTime"
+
+
+def test_equality_with_enum():
+    assert ColumnKind.INTEGER == ColumnKind.INTEGER
+    assert ColumnKind.FLOAT != ColumnKind.STRING
+    assert ColumnKind.DATE == ColumnKind.DATE
+
+
+def test_inequality_with_enum():
+    assert ColumnKind.INTEGER != ColumnKind.FLOAT
+    assert ColumnKind.BOOLEAN != ColumnKind.DATETIME
+    assert ColumnKind.CATEGORICAL != ColumnKind.DATE
+
+
+def test_missing_method():
+    assert ColumnKind("integer") == ColumnKind.INTEGER
+    assert ColumnKind("FLOAT") == ColumnKind.FLOAT
+    assert ColumnKind("unknown_value") == ColumnKind.STRING

xfintech/fabric/table/__init__.py

@@ -0,0 +1,5 @@
+from .info import TableInfo
+
+__all__ = [
+    "TableInfo",
+]

xfintech/fabric/table/info.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+from xfintech.fabric.column.info import ColumnInfo
+from xfintech.fabric.column.kind import ColumnKind
+
+
+class TableInfo:
+    """
+    描述:
+    - 表信息。
+
+    参数:
+    - name: str, optional, 表名称。 默认为空字符串。
+    - desc: str, optional, 表描述信息。 默认为空字符串。
+    - meta: Dict[str, Any], optional, 表元数据。 默认为None。
+    - columns: List[ColumnInfo], optional, 列字段信息列表。 默认为空。
+
+    属性:
+    - name: str, 表名称，统一为小写。
+    - desc: str, 表描述信息。
+    - meta: Dict[str, Any], 表元数据。
+    - columns: Dict[str, ColumnInfo], 列字段信息字典，键为列名称（小写）。
+
+    方法:
+    - from_dict(data): 从字典创建 TableInfo 实例。
+    - get_column(name): 根据列名称获取 ColumnInfo 实例。
+    - remove_column(name): 根据列名称移除 ColumnInfo 实例。
+    - add_column(column): 添加 ColumnInfo 实例。
+    - update_column(name, new, kind, desc, meta): 更新列字段信息。
+    - rename_column(old, new): 重命名列字段。
+    - list_columns(): 列出所有 ColumnInfo 实例。
+    - describe(): 返回表信息的描述字典。
+    - to_dict(): 返回表信息的字典表示。
+
+    例子:
+    ```python
+        from xfintech.fabric.table.info import TableInfo
+        from xfintech.fabric.column.info import ColumnInfo
+        from xfintech.fabric.column.kind import ColumnKind
+
+        table = TableInfo(
+            desc="日线行情表",
+            meta={"source": "tushare"},
+            columns=[
+                ColumnInfo(
+                    name="price",
+                    kind="Float",
+                    desc="收盘价",
+                ),
+                ColumnInfo(
+                    name="volume",
+                    kind=ColumnKind.INTEGER,
+                    desc="成交量",
+                    meta={"unit": "shares"},
+                ),
+            ],
+        )
+        print(table.describe())
+    ```
+    """
+
+    _NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+    ) -> "TableInfo":
+        return cls(
+            name=data.get("name"),
+            desc=data.get("desc"),
+            meta=data.get("meta"),
+            columns=data.get("columns"),
+        )
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        desc: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        columns: Optional[List[ColumnInfo | Dict[str, Any]]] = None,
+    ):
+        self.name = self._resolve_name(name)
+        self.desc = self._resolve_desc(desc)
+        self.meta = self._resolve_meta(meta)
+        self.columns = self._resolve_columns(columns)
+
+    def _resolve_name(
+        self,
+        value: Optional[str],
+    ) -> str:
+        if not value:
+            return ""
+        else:
+            value = value.strip()
+            if not self._NAME_PATTERN.match(value):
+                raise ValueError(f"Invalid table name: {value}")
+            else:
+                return value.lower()
+
+    def _resolve_desc(
+        self,
+        value: Optional[str],
+    ) -> Optional[str]:
+        if value is None:
+            return ""
+        else:
+            return value.strip()
+
+    def _resolve_meta(
+        self,
+        meta: Optional[Dict[str, Any]],
+    ) -> Optional[Dict[str, Any]]:
+        if meta is None:
+            return None
+        resolved: Dict[str, Any] = {}
+        for k, v in meta.items():
+            if isinstance(v, bytes):
+                v = v.decode("utf8")
+            if isinstance(k, bytes):
+                k = k.decode("utf8")
+            resolved[k] = v
+        return resolved
+
+    def _resolve_columns(
+        self,
+        columns: Optional[List[ColumnInfo | Dict[str, Any]]],
+    ) -> Dict[str, ColumnInfo]:
+        if columns is None:
+            return {}
+
+        resolved: Dict[str, ColumnInfo] = {}
+        for item in columns:
+            if isinstance(item, ColumnInfo):
+                resolved[item.name] = item
+            elif isinstance(item, dict):
+                col = ColumnInfo.from_dict(item)
+                resolved[col.name] = col
+            else:
+                raise TypeError(f"Invalid column type: {type(item)}")
+        return resolved
+
+    @property
+    def identifier(self) -> str:
+        result = {}
+        result["name"] = self.name
+        result["desc"] = self.desc
+        result["columns"] = []
+        values = sorted(
+            self.columns.values(),
+            key=lambda c: c.name,
+        )
+        for col in values:
+            result["columns"].append(
+                {
+                    "name": col.name,
+                    "kind": col.kind.value,
+                }
+            )
+        dna = json.dumps(
+            result,
+            sort_keys=True,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+        return hashlib.sha256(dna.encode("utf-8")).hexdigest()
+
+    def __str__(self) -> str:
+        return self.columns.__str__()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name={self.name})"
+
+    def get_column(
+        self,
+        name: str,
+    ) -> Optional[ColumnInfo]:
+        return self.columns.get(name.lower())
+
+    def remove_column(
+        self,
+        name: str,
+    ) -> "TableInfo":
+        key = name.lower()
+        if key in self.columns:
+            del self.columns[key]
+        return self
+
+    def add_column(
+        self,
+        column: ColumnInfo | Dict[str, Any],
+    ) -> "TableInfo":
+        if isinstance(column, dict):
+            column = ColumnInfo.from_dict(column)
+        self.columns[column.name] = column
+        return self
+
+    def update_column(
+        self,
+        name: str,
+        new: Optional[str] = None,
+        kind: Optional[ColumnKind | str] = None,
+        desc: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> "TableInfo":
+        oldkey = name.lower()
+        if oldkey in self.columns:
+            self.columns[oldkey].update(
+                kind=kind,
+                desc=desc,
+                meta=meta,
+            )
+            if new is not None:
+                self.rename_column(
+                    old=name,
+                    new=new,
+                )
+        return self
+
+    def rename_column(
+        self,
+        old: str,
+        new: str,
+    ) -> "TableInfo":
+        oldkey = old.lower()
+        newkey = new.lower()
+        if oldkey in self.columns:
+            self.columns[oldkey].update(name=new)
+            self.columns[newkey] = self.columns[oldkey]
+            del self.columns[oldkey]
+        return self
+
+    def list_columns(self) -> List[ColumnInfo]:
+        return list(self.columns.values())
+
+    def list_column_names(self) -> List[str]:
+        return list(self.columns.keys())
+
+    def describe(self) -> Dict[str, Any]:
+        result = {}
+        if self.name:
+            result["name"] = self.name
+        if self.desc:
+            result["desc"] = self.desc
+        if self.meta:
+            result["meta"] = self.meta
+        if self.columns:
+            result["columns"] = [c.describe() for c in self.list_columns()]
+        return result
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "identifier": self.identifier,
+            "name": self.name,
+            "desc": self.desc,
+            "meta": self.meta,
+            "columns": [c.to_dict() for c in self.list_columns()],
+        }