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.
@@ -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
+ ]
@@ -0,0 +1,5 @@
1
+ """`python -m typedframes` runs the `typedframes` command line."""
2
+
3
+ from typedframes._binary import main
4
+
5
+ main()
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}]")