kitora 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
kitora/__init__.py ADDED
File without changes
kitora/import_utils.py ADDED
@@ -0,0 +1,41 @@
1
+ from importlib import import_module
2
+
3
+
4
+ def import_attr(
5
+ attr_name: str,
6
+ module_name: str | None,
7
+ package: str | None,
8
+ ) -> object:
9
+ """Import an attribute from a module located in a package.
10
+
11
+ This utility function is used in custom `__getattr__` methods within `__init__.py`
12
+ files to dynamically import attributes.
13
+
14
+ Args:
15
+ attr_name: The name of the attribute to import.
16
+ module_name: The name of the module to import from.
17
+
18
+ If `None`, the attribute is imported from the package itself.
19
+ package: The name of the package where the module is located.
20
+
21
+ Returns:
22
+ The imported attribute.
23
+
24
+ Raises:
25
+ ImportError: If the module cannot be found.
26
+ AttributeError: If the attribute does not exist in the module or package.
27
+ """
28
+ if module_name == "__module__" or module_name is None:
29
+ try:
30
+ result = import_module(f".{attr_name}", package=package)
31
+ except ModuleNotFoundError:
32
+ msg = f"module '{package!r}' has no attribute {attr_name!r}"
33
+ raise AttributeError(msg) from None
34
+ else:
35
+ try:
36
+ module = import_module(f".{module_name}", package=package)
37
+ except ModuleNotFoundError as err:
38
+ msg = f"module '{package!r}.{module_name!r}' not found ({err})"
39
+ raise ImportError(msg) from None
40
+ result = getattr(module, attr_name)
41
+ return result
@@ -0,0 +1,23 @@
1
+ from typing import TYPE_CHECKING
2
+
3
+ from kitora.import_utils import import_attr
4
+
5
+ if TYPE_CHECKING:
6
+ from kitora.pandas.dataframe import dataframe_to_models
7
+
8
+ __all__ = ("dataframe_to_models",)
9
+
10
+ _dynamic_imports = {
11
+ "dataframe_to_models": "dataframe",
12
+ }
13
+
14
+
15
+ def __getattr__(attr_name: str) -> object:
16
+ module_name = _dynamic_imports.get(attr_name)
17
+ result = import_attr(attr_name, module_name, __spec__.parent)
18
+ globals()[attr_name] = result
19
+ return result
20
+
21
+
22
+ def __dir__() -> list[str]:
23
+ return list(__all__)
@@ -0,0 +1,132 @@
1
+ from typing import Any
2
+
3
+ import pandas as pd
4
+ from pandas.api.types import is_scalar
5
+ from pydantic import BaseModel
6
+ from pydantic.fields import FieldInfo
7
+
8
+ from kitora.pydantic.augmented_fields import _SourceMetadata
9
+
10
+ _MISSING = object()
11
+
12
+
13
+ def dataframe_to_models[T: BaseModel](
14
+ df: pd.DataFrame,
15
+ model_cls: type[T],
16
+ *,
17
+ extra_fields: dict[str, Any] | None = None,
18
+ strict: bool = True,
19
+ ) -> list[T]:
20
+ """将 pandas DataFrame 的每一行映射为一个 Pydantic 模型实例。
21
+
22
+ - 对模型的每个字段,按 `SourceField(source=...)` 声明的顺序查找候选列,再查找字段同名的列。
23
+ 取第一个存在的列,无论值是否为空。当候选列和同名列都不存在时,才按模型字段名从 `extra_fields` 取值。
24
+
25
+ - 如果取到的值为 `None` 或 pandas 标量缺失值,则将字段值设为 `None` 且跳过 `transform` 转换。
26
+ 如果配置了 `transform`,则先调用该函数转换取到的值,再交给 Pydantic 校验。
27
+
28
+ - 每行数据以模型**字段名**为键传给 `model_cls.model_validate()`,顶层模型**必须**接受按字段名输入的数据。
29
+ 如果字段声明了校验别名,可在模型上设置 `ConfigDict(validate_by_name=True)`。嵌套字典的键由对应子模型按自身配置解析。
30
+
31
+ Args:
32
+ df: 来源 pandas DataFrame,列名必须唯一。
33
+ model_cls: 具有命名字段的 Pydantic 模型类。顶层 `RootModel` 不在支持范围内。
34
+ 每个字段至多声明一个 `SourceField`;如有多个候选来源,应在同一个 `SourceField` 中通过 `source` 元组指定。
35
+ extra_fields: 以模型字段名为键的补充值,所有行共用。仅在找不到来源列时使用。
36
+ strict: 是否要求每个字段都有来源,此参数仅控制来源检查。为 True 时,缺少来源即报错。
37
+ 为 False 时,只有声明了 `SourceField(required=True)` 的字段要求必须有来源;
38
+ 其他缺少来源的字段会从输入中省略,由 Pydantic 应用默认值或报告必填字段缺失。
39
+
40
+ Returns:
41
+ 按 DataFrame 原始行序排列的 `model_cls` 实例列表,每行对应一个实例。没有数据行时返回空列表。
42
+
43
+ Raises:
44
+ ValueError: DataFrame 列名重复、字段缺少要求的来源,或 `transform` 执行失败。
45
+ pydantic.ValidationError: 映射后的行数据未通过模型校验。
46
+ """
47
+
48
+ if not df.columns.is_unique:
49
+ raise ValueError("DataFrame column names must be unique.")
50
+
51
+ results: list[T] = []
52
+ for row in df.itertuples(index=False, name=None):
53
+ record = dict(zip(df.columns, row, strict=True))
54
+ payload: dict[str, Any] = {}
55
+ for field_name, field_info in model_cls.model_fields.items():
56
+ value = _parse_field_value(
57
+ record,
58
+ field_name,
59
+ field_info,
60
+ extra_fields if extra_fields is not None else {},
61
+ strict=strict,
62
+ )
63
+ if value is not _MISSING:
64
+ payload[field_name] = value
65
+ results.append(model_cls.model_validate(payload))
66
+ return results
67
+
68
+
69
+ def _parse_field_value(
70
+ record: dict[str, Any],
71
+ field_name: str,
72
+ field_info: FieldInfo,
73
+ extra_fields: dict[str, Any],
74
+ *,
75
+ strict: bool,
76
+ ) -> Any:
77
+ metadata = next(
78
+ (item for item in field_info.metadata if isinstance(item, _SourceMetadata)),
79
+ _SourceMetadata(),
80
+ )
81
+
82
+ source_candidates = _build_source_candidates(metadata.source, field_name)
83
+
84
+ found = False
85
+ value = None
86
+ for source_candidate in source_candidates:
87
+ if source_candidate in record:
88
+ found = True
89
+ value = record[source_candidate]
90
+ break
91
+ if not found and field_name in extra_fields:
92
+ found = True
93
+ value = extra_fields[field_name]
94
+
95
+ if not found:
96
+ if strict or metadata.required:
97
+ raise ValueError(f"Missing source column for {field_name}, candidates are {source_candidates}")
98
+ return _MISSING
99
+
100
+ value = _normalize_pandas_value(value)
101
+ if value is None:
102
+ return None
103
+ if callable(metadata.transform):
104
+ try:
105
+ value = metadata.transform(value)
106
+ except Exception as e:
107
+ raise ValueError(f"Transform failed for {field_name}, value is {value!r}") from e
108
+ return value
109
+
110
+
111
+ def _build_source_candidates(source: tuple[str, ...] | None, field_name: str) -> list[str]:
112
+ if source is None:
113
+ return [field_name]
114
+
115
+ return [*source, field_name]
116
+
117
+
118
+ def _normalize_pandas_value(value: Any) -> Any:
119
+ if value is None:
120
+ return None
121
+
122
+ if not is_scalar(value):
123
+ # 只对标量检查是否为 pandas None 值
124
+ return value
125
+
126
+ try:
127
+ if pd.isna(value):
128
+ return None
129
+ except (TypeError, ValueError):
130
+ pass
131
+
132
+ return value
kitora/py.typed ADDED
File without changes
@@ -0,0 +1,23 @@
1
+ from typing import TYPE_CHECKING
2
+
3
+ from kitora.import_utils import import_attr
4
+
5
+ if TYPE_CHECKING:
6
+ from kitora.pydantic.augmented_fields import SourceField
7
+
8
+ __all__ = ("SourceField",)
9
+
10
+ _dynamic_imports = {
11
+ "SourceField": "augmented_fields",
12
+ }
13
+
14
+
15
+ def __getattr__(attr_name: str) -> object:
16
+ module_name = _dynamic_imports.get(attr_name)
17
+ result = import_attr(attr_name, module_name, __spec__.parent)
18
+ globals()[attr_name] = result
19
+ return result
20
+
21
+
22
+ def __dir__() -> list[str]:
23
+ return list(__all__)
@@ -0,0 +1,56 @@
1
+ from collections.abc import Callable
2
+ from dataclasses import dataclass
3
+ from typing import Annotated, Any, cast
4
+
5
+ from pydantic import Field
6
+ from pydantic.fields import FieldInfo
7
+
8
+
9
+ @dataclass(frozen=True)
10
+ class _SourceMetadata:
11
+ source: tuple[str, ...] | None = None
12
+ required: bool = False
13
+ transform: Callable[[Any], Any] | None = None
14
+
15
+
16
+ def SourceField(
17
+ *,
18
+ source: str | tuple[str, ...] | None = None,
19
+ required: bool = False,
20
+ transform: Callable[[Any], Any] | None = None,
21
+ **kwargs: Any,
22
+ ) -> Any:
23
+ """配置 Pydantic 模型字段,在 `pydantic.Field` 的基础上可额外配置来源映射和数据转换规则。
24
+
25
+ - 字段的默认值、别名、校验约束和描述等配置由 `pydantic.Field` 处理。
26
+ - `source`、`required` 和 `transform` 作为附加元数据,供映射器读取,例如 `kitora.pandas.dataframe_to_models`。
27
+
28
+ ***每个模型字段应只声明一个 SourceField。如有多个候选来源,请通过 source 元组按优先级指定。***
29
+
30
+ Args:
31
+ source: 外部数据中的来源名称。可传入单个名称,或按查找优先级排列的名称元组。None 表示未指定来源名称。
32
+ required: 映射时是否必须找到数据来源。字段本身是否必填由 Pydantic 的字段声明决定。
33
+ transform: 对来源值执行转换的函数,接收一个值并返回转换结果。None 表示未指定转换函数。
34
+ **kwargs: 传给 `pydantic.Field` 的关键字参数,例如 `default`、`alias`、`description` 等等。
35
+
36
+ Returns:
37
+ 包含 Pydantic 字段配置和来源映射元数据的 `FieldInfo` 对象。
38
+ """
39
+ metadata = _SourceMetadata(
40
+ source=_normalize_source(source),
41
+ required=required,
42
+ transform=transform,
43
+ )
44
+ return FieldInfo.from_annotated_attribute(
45
+ cast(type[Any], Annotated[Any, metadata]),
46
+ Field(**kwargs),
47
+ )
48
+
49
+
50
+ def _normalize_source(source: str | tuple[str, ...] | None) -> tuple[str, ...] | None:
51
+ if source is None:
52
+ return None
53
+ elif isinstance(source, str):
54
+ return (source,)
55
+ else:
56
+ return source
@@ -0,0 +1,24 @@
1
+ Metadata-Version: 2.4
2
+ Name: kitora
3
+ Version: 1.0.0
4
+ Summary: A personal toolkit for everyday Python
5
+ Keywords: pandas,pydantic,dataframe
6
+ Author: wangmu
7
+ Author-email: wangmu <wangmu8889@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Requires-Dist: pandas>=3.1.1
11
+ Requires-Dist: pydantic>=2.14.3
12
+ Requires-Python: >=3.12
13
+ Project-URL: Repository, https://github.com/wangmu0115/Kitora
14
+ Project-URL: Issues, https://github.com/wangmu0115/Kitora/issues
15
+ Description-Content-Type: text/markdown
16
+
17
+ # Kitora
18
+ Kitora — A personal toolkit for everyday Python.
19
+
20
+ 运行单元测试(uv 会自动安装开发依赖):
21
+
22
+ ```bash
23
+ uv run pytest
24
+ ```
@@ -0,0 +1,11 @@
1
+ kitora/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
2
+ kitora/import_utils.py,sha256=UcJg3FjJ-IU9x_MuybIAbhDc91ompvg1rijnpF2dwNM,1428
3
+ kitora/pandas/__init__.py,sha256=1AJuaVfnvKwLGTTxINfOmUDeUGs7LC18AYOCrWFGSBQ,525
4
+ kitora/pandas/dataframe.py,sha256=TktzEZvYk7VEBuhTevxjJ3-IKVWG5gO06rBvcjCfdpI,4931
5
+ kitora/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ kitora/pydantic/__init__.py,sha256=YwctrrX1NHX6ZyP6NKyqwBZDTg0_oKuzZNL_7yZNNjU,517
7
+ kitora/pydantic/augmented_fields.py,sha256=n2vGy8OaIEspyRWl4iUrcUX7liuf7WdYAyNKTyYtcJc,2147
8
+ kitora-1.0.0.dist-info/licenses/LICENSE,sha256=j3FAuuprqfO7u_TrxVCHmsG4y9UMSb7aHddXTvWWy_w,1063
9
+ kitora-1.0.0.dist-info/WHEEL,sha256=_d8F1e7SqtoW6CDj4Gi8lFC26a_7I17R7zPLCKTp4Fg,81
10
+ kitora-1.0.0.dist-info/METADATA,sha256=_pkXmoVwvniGkuWIAbGoJ4S9ux9jfLCd_Yp-DdUv0N4,638
11
+ kitora-1.0.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.12.15
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wangmu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.