typedframes 0.14.0__py3-none-win_amd64.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.
- typedframes/__init__.py +56 -0
- typedframes/__main__.py +5 -0
- typedframes/_binary.py +57 -0
- typedframes/base_schema.py +171 -0
- typedframes/column.py +85 -0
- typedframes/column_group.py +95 -0
- typedframes/column_group_error.py +42 -0
- typedframes/column_set.py +100 -0
- typedframes/missing_dependency_error.py +17 -0
- typedframes/mypy.py +140 -0
- typedframes/pandera.py +79 -0
- typedframes/py.typed +0 -0
- typedframes/schema_algebra.py +101 -0
- typedframes-0.14.0.data/scripts/typedframes.exe +0 -0
- typedframes-0.14.0.dist-info/METADATA +1266 -0
- typedframes-0.14.0.dist-info/RECORD +19 -0
- typedframes-0.14.0.dist-info/WHEEL +4 -0
- typedframes-0.14.0.dist-info/licenses/LICENSE +21 -0
- typedframes-0.14.0.dist-info/sboms/typedframes_checker.cyclonedx.json +4542 -0
typedframes/__init__.py
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
r"""
|
|
2
|
+
typedframes - Type-safe DataFrame schemas for pandas and polars.
|
|
3
|
+
|
|
4
|
+
Provides schema definitions for DataFrames that enable:
|
|
5
|
+
- Static analysis of column access (via Rust linter)
|
|
6
|
+
- Documentation as code for DataFrame structures
|
|
7
|
+
- Optional runtime validation integration with third-party tools
|
|
8
|
+
|
|
9
|
+
Core Classes:
|
|
10
|
+
BaseSchema: Define DataFrame column schemas.
|
|
11
|
+
Column: Define a single column with type and optional alias.
|
|
12
|
+
ColumnSet: Define a group of columns matching a pattern.
|
|
13
|
+
ColumnGroup: Group multiple Columns/ColumnSets for convenient access.
|
|
14
|
+
|
|
15
|
+
Usage:
|
|
16
|
+
from typing import Annotated
|
|
17
|
+
import pandas as pd
|
|
18
|
+
import polars as pl
|
|
19
|
+
from typedframes import BaseSchema, Column, ColumnSet
|
|
20
|
+
|
|
21
|
+
class UserSchema(BaseSchema):
|
|
22
|
+
user_id = Column(type=int)
|
|
23
|
+
email = Column(type=str, alias="user_email")
|
|
24
|
+
scores = ColumnSet(members=r"score_\\d+", type=float, regex=True)
|
|
25
|
+
|
|
26
|
+
# Recommended: use Annotated for both pandas and polars
|
|
27
|
+
df: Annotated[pd.DataFrame, UserSchema] = pd.read_csv("users.csv")
|
|
28
|
+
df['user_id'] # ✓ Validated by checker
|
|
29
|
+
df[UserSchema.user_id.s] # ✓ Refactor-safe string access via descriptor
|
|
30
|
+
|
|
31
|
+
df: Annotated[pl.DataFrame, UserSchema] = pl.read_csv("users.csv")
|
|
32
|
+
df.filter(pl.col('user_id') > 10) # ✓ pl.col() validated by checker
|
|
33
|
+
df.filter(UserSchema.user_id.col > 10) # ✓ Refactor-safe polars expression
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
__version__ = "0.14.0"
|
|
37
|
+
|
|
38
|
+
from .base_schema import BaseSchema as BaseSchema
|
|
39
|
+
from .column import Column as Column
|
|
40
|
+
from .column_group import ColumnGroup as ColumnGroup
|
|
41
|
+
from .column_group_error import ColumnGroupError as ColumnGroupError
|
|
42
|
+
from .column_set import ColumnSet as ColumnSet
|
|
43
|
+
from .missing_dependency_error import MissingDependencyError as MissingDependencyError
|
|
44
|
+
from .schema_algebra import SchemaConflictError as SchemaConflictError
|
|
45
|
+
from .schema_algebra import combine_schemas as combine_schemas
|
|
46
|
+
|
|
47
|
+
__all__ = [
|
|
48
|
+
"BaseSchema",
|
|
49
|
+
"Column",
|
|
50
|
+
"ColumnGroup",
|
|
51
|
+
"ColumnGroupError",
|
|
52
|
+
"ColumnSet",
|
|
53
|
+
"MissingDependencyError",
|
|
54
|
+
"SchemaConflictError",
|
|
55
|
+
"combine_schemas",
|
|
56
|
+
]
|
typedframes/__main__.py
ADDED
typedframes/_binary.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Finding and running the `typedframes` executable that was installed alongside this package."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
import shutil
|
|
5
|
+
import subprocess
|
|
6
|
+
import sys
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from sysconfig import get_config_var, get_path, get_preferred_scheme
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class BinaryNotFoundError(FileNotFoundError):
|
|
12
|
+
"""Raised when the `typedframes` executable is not installed."""
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def find_binary() -> Path:
|
|
16
|
+
"""The `typedframes` executable: next to the interpreter's scripts, then the user's, then on PATH.
|
|
17
|
+
|
|
18
|
+
Raises:
|
|
19
|
+
BinaryNotFoundError: If none of those hold it, e.g. the package was installed without it.
|
|
20
|
+
"""
|
|
21
|
+
name = f"typedframes{get_config_var('EXE') or ''}"
|
|
22
|
+
scripts = Path(get_path("scripts")) / name
|
|
23
|
+
user_scripts = Path(get_path("scripts", scheme=get_preferred_scheme("user"))) / name
|
|
24
|
+
# `pip install --target` puts scripts in a `bin` directory beside the package.
|
|
25
|
+
target = Path(__file__).resolve().parents[1] / "bin" / name
|
|
26
|
+
for candidate in (scripts, user_scripts, target):
|
|
27
|
+
if candidate.is_file():
|
|
28
|
+
return candidate
|
|
29
|
+
on_path = shutil.which("typedframes")
|
|
30
|
+
if on_path is not None:
|
|
31
|
+
return Path(on_path)
|
|
32
|
+
msg = (
|
|
33
|
+
f"The typedframes executable was not found (looked for {scripts}). "
|
|
34
|
+
"Reinstall typedframes from a wheel, or build it from source with: uv run inv build"
|
|
35
|
+
)
|
|
36
|
+
raise BinaryNotFoundError(msg)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def run_binary(arguments: list[str], *, capture: bool = False) -> subprocess.CompletedProcess[str]:
|
|
40
|
+
"""Run the executable with `arguments`; with `capture`, its output is returned instead of shared.
|
|
41
|
+
|
|
42
|
+
Raises:
|
|
43
|
+
BinaryNotFoundError: If the executable is not installed.
|
|
44
|
+
"""
|
|
45
|
+
return subprocess.run([str(find_binary()), *arguments], capture_output=capture, text=True, check=False)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def main() -> None:
|
|
49
|
+
"""Entry point for `python -m typedframes`: the executable, with this process's arguments.
|
|
50
|
+
|
|
51
|
+
Where the platform allows it the executable takes this process's place, so no Python process
|
|
52
|
+
is left waiting; Windows has no such call, and runs it as a child instead.
|
|
53
|
+
"""
|
|
54
|
+
if sys.platform == "win32":
|
|
55
|
+
sys.exit(run_binary(sys.argv[1:]).returncode)
|
|
56
|
+
binary = str(find_binary())
|
|
57
|
+
os.execv(binary, [binary, *sys.argv[1:]])
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
"""Base schema class for defining DataFrame schemas."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from typing import TYPE_CHECKING, ClassVar
|
|
7
|
+
|
|
8
|
+
from .column import Column
|
|
9
|
+
from .column_group import ColumnGroup
|
|
10
|
+
from .column_set import ColumnSet
|
|
11
|
+
|
|
12
|
+
if TYPE_CHECKING:
|
|
13
|
+
import pandas as pd
|
|
14
|
+
import polars as pl
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class SchemaMeta(type):
|
|
18
|
+
"""Metaclass for BaseSchema that enables class-level + operator and MI conflict detection."""
|
|
19
|
+
|
|
20
|
+
def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict) -> SchemaMeta:
|
|
21
|
+
"""Create a new schema class, checking for column type conflicts across bases."""
|
|
22
|
+
cls = super().__new__(mcs, name, bases, namespace)
|
|
23
|
+
# Detect column type conflicts across multiple schema bases
|
|
24
|
+
seen_columns: dict[str, tuple[type, str]] = {}
|
|
25
|
+
for base in cls.__mro__:
|
|
26
|
+
if base is cls or not isinstance(base, SchemaMeta):
|
|
27
|
+
continue
|
|
28
|
+
for attr_val in base.__dict__.values():
|
|
29
|
+
if isinstance(attr_val, Column):
|
|
30
|
+
col_name = attr_val.column_name
|
|
31
|
+
if col_name in seen_columns:
|
|
32
|
+
existing_type, existing_source = seen_columns[col_name]
|
|
33
|
+
if attr_val.type != existing_type:
|
|
34
|
+
from .schema_algebra import SchemaConflictError
|
|
35
|
+
|
|
36
|
+
raise SchemaConflictError(
|
|
37
|
+
col_name, existing_type, existing_source, attr_val.type, base.__name__
|
|
38
|
+
)
|
|
39
|
+
else:
|
|
40
|
+
seen_columns[col_name] = (attr_val.type, base.__name__)
|
|
41
|
+
return cls # type: ignore[return-value]
|
|
42
|
+
|
|
43
|
+
def __add__(cls, other: type[BaseSchema]) -> type[BaseSchema]:
|
|
44
|
+
"""Combine two schema classes using the + operator."""
|
|
45
|
+
from .schema_algebra import combine_schemas
|
|
46
|
+
|
|
47
|
+
return combine_schemas(cls, other) # ty: ignore[invalid-argument-type]
|
|
48
|
+
|
|
49
|
+
def __radd__(cls, other: type[BaseSchema]) -> type[BaseSchema]:
|
|
50
|
+
"""Support reverse addition for schema combination."""
|
|
51
|
+
from .schema_algebra import combine_schemas
|
|
52
|
+
|
|
53
|
+
return combine_schemas(other, cls) # ty: ignore[invalid-argument-type]
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _collect_from_mro(cls: type, descriptor_type: type) -> dict:
|
|
57
|
+
"""Collect descriptors of a given type from the full MRO (child overrides parent)."""
|
|
58
|
+
result: dict = {}
|
|
59
|
+
for klass in reversed(cls.__mro__):
|
|
60
|
+
result.update({name: val for name, val in klass.__dict__.items() if isinstance(val, descriptor_type)})
|
|
61
|
+
return result
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class BaseSchema(metaclass=SchemaMeta):
|
|
65
|
+
r"""
|
|
66
|
+
Backend-agnostic schema definition for DataFrame validation.
|
|
67
|
+
|
|
68
|
+
Define your DataFrame schema once and use it for static analysis
|
|
69
|
+
with both pandas and polars.
|
|
70
|
+
|
|
71
|
+
Class Attributes:
|
|
72
|
+
enforce_columns: If True, validate that all defined columns exist.
|
|
73
|
+
allow_extra_columns: If True, allow columns not defined in schema.
|
|
74
|
+
|
|
75
|
+
Example:
|
|
76
|
+
class UserData(BaseSchema):
|
|
77
|
+
user_id = Column(type=int)
|
|
78
|
+
email = Column(type=str)
|
|
79
|
+
scores = ColumnSet(members=r"score_\\d+", type=float, regex=True)
|
|
80
|
+
|
|
81
|
+
# Use with type annotations for static analysis:
|
|
82
|
+
df: Annotated[pd.DataFrame, UserData] = pd.read_csv("data.csv")
|
|
83
|
+
df: Annotated[pl.DataFrame, UserData] = pl.read_csv("data.csv")
|
|
84
|
+
|
|
85
|
+
"""
|
|
86
|
+
|
|
87
|
+
_column_map: ClassVar[dict[str, Column] | None] = None
|
|
88
|
+
_column_set_map: ClassVar[dict[str, ColumnSet] | None] = None
|
|
89
|
+
_column_group_map: ClassVar[dict[str, ColumnGroup] | None] = None
|
|
90
|
+
|
|
91
|
+
enforce_columns: ClassVar[bool] = True
|
|
92
|
+
allow_extra_columns: ClassVar[bool] = True
|
|
93
|
+
|
|
94
|
+
@classmethod
|
|
95
|
+
def columns(cls) -> dict[str, Column]:
|
|
96
|
+
"""Return mapping of attribute names to Column definitions, including inherited."""
|
|
97
|
+
if "_column_map" not in cls.__dict__ or cls._column_map is None:
|
|
98
|
+
cls._column_map = _collect_from_mro(cls, Column)
|
|
99
|
+
return cls._column_map
|
|
100
|
+
|
|
101
|
+
@classmethod
|
|
102
|
+
def column_sets(cls) -> dict[str, ColumnSet]:
|
|
103
|
+
"""Return mapping of attribute names to ColumnSet definitions, including inherited."""
|
|
104
|
+
if "_column_set_map" not in cls.__dict__ or cls._column_set_map is None:
|
|
105
|
+
cls._column_set_map = _collect_from_mro(cls, ColumnSet)
|
|
106
|
+
return cls._column_set_map
|
|
107
|
+
|
|
108
|
+
@classmethod
|
|
109
|
+
def column_groups(cls) -> dict[str, ColumnGroup]:
|
|
110
|
+
"""Return mapping of attribute names to ColumnGroup definitions, including inherited."""
|
|
111
|
+
if "_column_group_map" not in cls.__dict__ or cls._column_group_map is None:
|
|
112
|
+
cls._column_group_map = _collect_from_mro(cls, ColumnGroup)
|
|
113
|
+
return cls._column_group_map
|
|
114
|
+
|
|
115
|
+
@classmethod
|
|
116
|
+
def all_column_names(cls) -> list[str]:
|
|
117
|
+
"""Return list of all explicitly defined column names (from Columns and non-regex ColumnSets)."""
|
|
118
|
+
names: list[str] = [col.column_name for col in cls.columns().values()]
|
|
119
|
+
|
|
120
|
+
for cs in cls.column_sets().values():
|
|
121
|
+
if not cs.regex and isinstance(cs.members, list):
|
|
122
|
+
names.extend(cs.members)
|
|
123
|
+
|
|
124
|
+
return names
|
|
125
|
+
|
|
126
|
+
@classmethod
|
|
127
|
+
def validate_columns(cls, df_columns: list[str]) -> list[str]:
|
|
128
|
+
"""
|
|
129
|
+
Validate DataFrame columns against schema.
|
|
130
|
+
|
|
131
|
+
Returns list of error messages (empty if valid).
|
|
132
|
+
"""
|
|
133
|
+
defined = set(cls.all_column_names())
|
|
134
|
+
errors: list[str] = [
|
|
135
|
+
f"Missing required column: {col.column_name}"
|
|
136
|
+
for col in cls.columns().values()
|
|
137
|
+
if col.column_name not in df_columns and cls.enforce_columns
|
|
138
|
+
]
|
|
139
|
+
|
|
140
|
+
if not cls.allow_extra_columns:
|
|
141
|
+
for col_name in df_columns:
|
|
142
|
+
if col_name not in defined:
|
|
143
|
+
is_matched = False
|
|
144
|
+
for cs in cls.column_sets().values():
|
|
145
|
+
if cs.regex and isinstance(cs.members, list) and any(re.match(p, col_name) for p in cs.members):
|
|
146
|
+
is_matched = True
|
|
147
|
+
break
|
|
148
|
+
if not is_matched:
|
|
149
|
+
errors.append(f"Unexpected column: {col_name}")
|
|
150
|
+
|
|
151
|
+
return errors
|
|
152
|
+
|
|
153
|
+
@classmethod
|
|
154
|
+
def from_pandas(cls, df: pd.DataFrame) -> pd.DataFrame:
|
|
155
|
+
"""
|
|
156
|
+
Validate and return a pandas DataFrame with schema metadata.
|
|
157
|
+
|
|
158
|
+
This is a simple passthrough for use with type annotations.
|
|
159
|
+
The linter performs static validation; this provides runtime metadata.
|
|
160
|
+
"""
|
|
161
|
+
return df
|
|
162
|
+
|
|
163
|
+
@classmethod
|
|
164
|
+
def from_polars(cls, df: pl.DataFrame) -> pl.DataFrame:
|
|
165
|
+
"""
|
|
166
|
+
Validate and return a polars DataFrame with schema metadata.
|
|
167
|
+
|
|
168
|
+
This is a simple passthrough for use with type annotations.
|
|
169
|
+
The linter performs static validation; this provides runtime metadata.
|
|
170
|
+
"""
|
|
171
|
+
return df
|
typedframes/column.py
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""Column descriptor for DataFrame schemas."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import TYPE_CHECKING, Any
|
|
7
|
+
|
|
8
|
+
if TYPE_CHECKING:
|
|
9
|
+
import polars as pl
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass
|
|
13
|
+
class Column:
|
|
14
|
+
"""
|
|
15
|
+
Represents a single column in a DataFrame schema.
|
|
16
|
+
|
|
17
|
+
Attributes:
|
|
18
|
+
type: The Python type of the column (e.g., int, str, float).
|
|
19
|
+
alias: Optional alternative name for the column in the actual DataFrame.
|
|
20
|
+
nullable: Whether the column allows null values.
|
|
21
|
+
description: Human-readable description of the column's purpose.
|
|
22
|
+
|
|
23
|
+
Example:
|
|
24
|
+
class UserData(BaseSchema):
|
|
25
|
+
user_id = Column(type=int)
|
|
26
|
+
email = Column(type=str, alias="user_email")
|
|
27
|
+
age = Column(type=int, nullable=True, description="User's age in years")
|
|
28
|
+
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
type: type = Any
|
|
32
|
+
alias: str | None = None
|
|
33
|
+
nullable: bool = False
|
|
34
|
+
description: str = ""
|
|
35
|
+
name: str = field(default="", init=False)
|
|
36
|
+
|
|
37
|
+
def __set_name__(self, owner: type, name: str) -> None:
|
|
38
|
+
"""Set the name attribute from the class attribute name."""
|
|
39
|
+
self.name = name
|
|
40
|
+
|
|
41
|
+
@property
|
|
42
|
+
def column_name(self) -> str:
|
|
43
|
+
"""Return the effective column name (alias if set, otherwise attribute name)."""
|
|
44
|
+
return self.alias or self.name
|
|
45
|
+
|
|
46
|
+
@property
|
|
47
|
+
def col(self) -> pl.Expr:
|
|
48
|
+
"""
|
|
49
|
+
Return a polars column expression for this column.
|
|
50
|
+
|
|
51
|
+
Useful for building polars queries with schema column references.
|
|
52
|
+
|
|
53
|
+
Example:
|
|
54
|
+
df.filter(UserSchema.age.col > 18)
|
|
55
|
+
df.select(UserSchema.email.col, UserSchema.user_id.col)
|
|
56
|
+
|
|
57
|
+
"""
|
|
58
|
+
try:
|
|
59
|
+
import polars as pl
|
|
60
|
+
except ImportError:
|
|
61
|
+
from .missing_dependency_error import MissingDependencyError
|
|
62
|
+
|
|
63
|
+
package = "polars"
|
|
64
|
+
raise MissingDependencyError(package, "Column.col") from None
|
|
65
|
+
|
|
66
|
+
return pl.col(self.column_name)
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
def s(self) -> str:
|
|
70
|
+
"""
|
|
71
|
+
Return the column name as a string for native pandas subscript access.
|
|
72
|
+
|
|
73
|
+
Provides refactor-safe column name access for plain pandas DataFrames.
|
|
74
|
+
Parallel to ``.col`` (polars expression) for pandas string access.
|
|
75
|
+
|
|
76
|
+
Example:
|
|
77
|
+
df[UserSchema.user_id.s] # pandas — works with plain pd.DataFrame
|
|
78
|
+
df.groupby(UserSchema.region.s) # pandas groupby
|
|
79
|
+
|
|
80
|
+
"""
|
|
81
|
+
return self.column_name
|
|
82
|
+
|
|
83
|
+
def __str__(self) -> str:
|
|
84
|
+
"""Return the column name as a string for use in subscript access."""
|
|
85
|
+
return self.column_name
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""ColumnGroup descriptor for DataFrame schemas."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import TYPE_CHECKING
|
|
7
|
+
|
|
8
|
+
from .column import Column
|
|
9
|
+
from .column_set import ColumnSet
|
|
10
|
+
|
|
11
|
+
if TYPE_CHECKING:
|
|
12
|
+
import polars as pl
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass
|
|
16
|
+
class ColumnGroup:
|
|
17
|
+
r"""
|
|
18
|
+
Groups multiple Columns and ColumnSets for convenient access.
|
|
19
|
+
|
|
20
|
+
Useful for organizing related columns that span multiple Column/ColumnSet
|
|
21
|
+
definitions, such as grouping all measurement columns together.
|
|
22
|
+
|
|
23
|
+
Attributes:
|
|
24
|
+
members: List of Column, ColumnSet, or nested ColumnGroup objects.
|
|
25
|
+
description: Human-readable description of the group's purpose.
|
|
26
|
+
|
|
27
|
+
Example:
|
|
28
|
+
class SensorData(BaseSchema):
|
|
29
|
+
timestamp = Column(type=str)
|
|
30
|
+
temperatures = ColumnSet(members=r"temp_\\d+", type=float, regex=True)
|
|
31
|
+
pressures = ColumnSet(members=r"pressure_\\d+", type=float, regex=True)
|
|
32
|
+
|
|
33
|
+
# Group for convenient access to all sensor data
|
|
34
|
+
all_sensors = ColumnGroup(members=[temperatures, pressures])
|
|
35
|
+
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
members: list[Column | ColumnSet | ColumnGroup]
|
|
39
|
+
description: str = ""
|
|
40
|
+
name: str = field(default="", init=False)
|
|
41
|
+
|
|
42
|
+
def __set_name__(self, owner: type, name: str) -> None:
|
|
43
|
+
"""Set the name attribute from the class attribute name."""
|
|
44
|
+
self.name = name
|
|
45
|
+
|
|
46
|
+
@property
|
|
47
|
+
def s(self) -> list[str]:
|
|
48
|
+
"""
|
|
49
|
+
Return all column names in this group as a list of strings.
|
|
50
|
+
|
|
51
|
+
Groups containing regex ``ColumnSet`` members raise ``ValueError`` because
|
|
52
|
+
matched column names are only known at runtime.
|
|
53
|
+
|
|
54
|
+
Returns:
|
|
55
|
+
Flat list of column name strings for all non-regex members.
|
|
56
|
+
|
|
57
|
+
Example:
|
|
58
|
+
df[SensorSchema.all_sensors.s] # pandas — works for non-regex groups
|
|
59
|
+
|
|
60
|
+
"""
|
|
61
|
+
result: list[str] = []
|
|
62
|
+
for member in self.members:
|
|
63
|
+
if isinstance(member, Column):
|
|
64
|
+
result.append(member.alias if isinstance(member.alias, str) else member.name)
|
|
65
|
+
elif isinstance(member, ColumnSet):
|
|
66
|
+
if member.regex:
|
|
67
|
+
msg = f"Cannot resolve regex ColumnSet '{member.name}': its matches are only known at runtime."
|
|
68
|
+
raise ValueError(msg)
|
|
69
|
+
result.extend(member.members)
|
|
70
|
+
elif isinstance(member, ColumnGroup):
|
|
71
|
+
result.extend(member.s)
|
|
72
|
+
return result
|
|
73
|
+
|
|
74
|
+
def cols(self) -> list[pl.Expr]:
|
|
75
|
+
"""
|
|
76
|
+
Return polars column expressions for all columns in this group.
|
|
77
|
+
|
|
78
|
+
Groups containing regex ``ColumnSet`` members raise ``ValueError``, as for ``.s``.
|
|
79
|
+
|
|
80
|
+
Returns:
|
|
81
|
+
List of polars column expressions.
|
|
82
|
+
|
|
83
|
+
Example:
|
|
84
|
+
df.select(SensorSchema.all_sensors.cols())
|
|
85
|
+
|
|
86
|
+
"""
|
|
87
|
+
try:
|
|
88
|
+
import polars as pl
|
|
89
|
+
except ImportError:
|
|
90
|
+
from .missing_dependency_error import MissingDependencyError
|
|
91
|
+
|
|
92
|
+
package = "polars"
|
|
93
|
+
raise MissingDependencyError(package, "ColumnGroup.cols") from None
|
|
94
|
+
|
|
95
|
+
return [pl.col(n) for n in self.s]
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Error for column conflicts between groups."""
|
|
2
|
+
|
|
3
|
+
from typing import TYPE_CHECKING
|
|
4
|
+
|
|
5
|
+
if TYPE_CHECKING:
|
|
6
|
+
from .column import Column
|
|
7
|
+
from .column_set import ColumnSet
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class ColumnGroupError(Exception):
|
|
11
|
+
"""Exception raised when a column is matched by multiple ColumnSets or Columns."""
|
|
12
|
+
|
|
13
|
+
def __init__(
|
|
14
|
+
self,
|
|
15
|
+
column: str,
|
|
16
|
+
first_match: "Column | ColumnSet | None",
|
|
17
|
+
second_match: "ColumnSet",
|
|
18
|
+
) -> None:
|
|
19
|
+
"""
|
|
20
|
+
Initialize the error.
|
|
21
|
+
|
|
22
|
+
Args:
|
|
23
|
+
column: The name of the column that matched multiple groups.
|
|
24
|
+
first_match: The first Column or ColumnSet that matched.
|
|
25
|
+
second_match: The second ColumnSet that matched.
|
|
26
|
+
|
|
27
|
+
"""
|
|
28
|
+
self._column = column
|
|
29
|
+
self._first_match = first_match
|
|
30
|
+
self._second_match = second_match
|
|
31
|
+
super().__init__(str(self))
|
|
32
|
+
|
|
33
|
+
def __str__(self) -> str:
|
|
34
|
+
"""Return a string representation of the error message."""
|
|
35
|
+
first_name = getattr(self._first_match, "name", str(self._first_match))
|
|
36
|
+
second_name = self._second_match.name
|
|
37
|
+
return f"Column '{self._column}' matched by both '{first_name}' and '{second_name}'."
|
|
38
|
+
|
|
39
|
+
@property
|
|
40
|
+
def column(self) -> str:
|
|
41
|
+
"""Return the name of the conflicting column."""
|
|
42
|
+
return self._column
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
"""ColumnSet descriptor for DataFrame schemas."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import TYPE_CHECKING, Any
|
|
7
|
+
|
|
8
|
+
if TYPE_CHECKING:
|
|
9
|
+
import polars as pl
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass
|
|
13
|
+
class ColumnSet:
|
|
14
|
+
r"""
|
|
15
|
+
Represents a set of columns matching a pattern or explicit list.
|
|
16
|
+
|
|
17
|
+
Used for grouping related columns that share a common type,
|
|
18
|
+
such as time series data or multi-dimensional measurements.
|
|
19
|
+
|
|
20
|
+
Attributes:
|
|
21
|
+
members: List of column names (or a single name as a string, which is normalized to a
|
|
22
|
+
single-element list). When regex=True, each string is treated as a regex pattern.
|
|
23
|
+
type: The Python type shared by all columns in the set.
|
|
24
|
+
regex: If True, members is treated as a regex pattern for matching column names.
|
|
25
|
+
description: Human-readable description of the column set's purpose.
|
|
26
|
+
|
|
27
|
+
Example:
|
|
28
|
+
class SensorData(BaseSchema):
|
|
29
|
+
# Explicit member list
|
|
30
|
+
temperatures = ColumnSet(members=["temp_1", "temp_2", "temp_3"], type=float)
|
|
31
|
+
|
|
32
|
+
# Regex pattern matching
|
|
33
|
+
pressures = ColumnSet(members=r"pressure_\\d+", type=float, regex=True)
|
|
34
|
+
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
members: list[str]
|
|
38
|
+
type: type = Any
|
|
39
|
+
regex: bool = False
|
|
40
|
+
description: str = ""
|
|
41
|
+
name: str = field(default="", init=False)
|
|
42
|
+
|
|
43
|
+
def __post_init__(self) -> None:
|
|
44
|
+
"""Normalize members to a list."""
|
|
45
|
+
if isinstance(self.members, str):
|
|
46
|
+
self.members = [self.members]
|
|
47
|
+
|
|
48
|
+
def __set_name__(self, owner: type, name: str) -> None:
|
|
49
|
+
"""Set the name attribute from the class attribute name."""
|
|
50
|
+
self.name = name
|
|
51
|
+
|
|
52
|
+
@property
|
|
53
|
+
def s(self) -> list[str]:
|
|
54
|
+
"""
|
|
55
|
+
Return the column names as a list of strings for native pandas subscript access.
|
|
56
|
+
|
|
57
|
+
For non-regex ColumnSets, returns the explicit member names. For regex
|
|
58
|
+
ColumnSets, raises ``ValueError`` because the matched column names are only
|
|
59
|
+
known at runtime.
|
|
60
|
+
|
|
61
|
+
Example:
|
|
62
|
+
df[SensorSchema.temperatures.s] # pandas — works for non-regex ColumnSets
|
|
63
|
+
|
|
64
|
+
"""
|
|
65
|
+
if self.regex:
|
|
66
|
+
msg = "Cannot get column names for regex ColumnSet: the matched columns are only known at runtime."
|
|
67
|
+
raise ValueError(msg)
|
|
68
|
+
return list(self.members)
|
|
69
|
+
|
|
70
|
+
def cols(self, matched_columns: list[str] | None = None) -> list[pl.Expr]:
|
|
71
|
+
"""
|
|
72
|
+
Return polars column expressions for all columns in this set.
|
|
73
|
+
|
|
74
|
+
Args:
|
|
75
|
+
matched_columns: Optional list of column names that matched this set.
|
|
76
|
+
If not provided, uses the explicit members list (not applicable for regex).
|
|
77
|
+
|
|
78
|
+
Returns:
|
|
79
|
+
List of polars column expressions.
|
|
80
|
+
|
|
81
|
+
Example:
|
|
82
|
+
df.select(SensorSchema.temperatures.cols())
|
|
83
|
+
|
|
84
|
+
"""
|
|
85
|
+
try:
|
|
86
|
+
import polars as pl
|
|
87
|
+
except ImportError:
|
|
88
|
+
from .missing_dependency_error import MissingDependencyError
|
|
89
|
+
|
|
90
|
+
package = "polars"
|
|
91
|
+
raise MissingDependencyError(package, "ColumnSet.cols") from None
|
|
92
|
+
|
|
93
|
+
if matched_columns is not None:
|
|
94
|
+
return [pl.col(c) for c in matched_columns]
|
|
95
|
+
|
|
96
|
+
if self.regex:
|
|
97
|
+
msg = "Cannot get column expressions for regex members without matched_columns"
|
|
98
|
+
raise ValueError(msg)
|
|
99
|
+
|
|
100
|
+
return [pl.col(c) for c in self.members]
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Error for missing optional dependencies."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class MissingDependencyError(ImportError):
|
|
5
|
+
"""Raised when an optional dependency is not installed."""
|
|
6
|
+
|
|
7
|
+
def __init__(self, package: str, feature: str) -> None:
|
|
8
|
+
"""Initialize with the missing package and feature that requires it.
|
|
9
|
+
|
|
10
|
+
Args:
|
|
11
|
+
package: The name of the missing package (e.g., "polars").
|
|
12
|
+
feature: The feature that requires this package (e.g., "Column.col").
|
|
13
|
+
|
|
14
|
+
"""
|
|
15
|
+
self.package = package
|
|
16
|
+
self.feature = feature
|
|
17
|
+
super().__init__(f"{package} is required for {feature}. Install it with: pip install typedframes[{package}]")
|