dataframely.columns.struct module

class dataframely.columns.struct.Struct(inner: dict[str, Column], *, nullable: bool | None = None, primary_key: bool = False, check: Callable[[Expr], Expr] | Sequence[Callable[[Expr], Expr]] | Mapping[str, Callable[[Expr], Expr]] | None = None, alias: str | None = None, metadata: dict[str, Any] | None = None)

Bases: Column

A struct column.

Attributes:

col

Obtain a Polars column expression for the column.

dtype

The polars dtype equivalent of this column definition’s data type.

name

Get the name of the column in a schema.

pyarrow_dtype

The pyarrow dtype equivalent of this column data type.

Methods

as_dict(expr)	Turn the column definition into a dictionary.
from_dict(data)	Read the column definition from a dictionary.
matches(other, expr)	Check whether this column semantically matches another column.
pyarrow_field(name)	Obtain the pyarrow field of this column definition.
sample(generator[, n])	Sample random elements adhering to the constraints of this column.
sqlalchemy_column(name, dialect)	Obtain the SQL column specification of this column definition.
sqlalchemy_dtype(dialect)	The sqlalchemy dtype equivalent of this column data type.
validate_dtype(dtype)	Validate if the polars data type satisfies the column definition.
validation_rules(expr)	A set of rules evaluating whether a data frame column satisfies the column's constraints.

as_dict(expr: Expr) → dict[str, Any]

Turn the column definition into a dictionary.

If the column definition references other column definitions, they will be turned into dictionaries recursively.

Args:

expr: An expression referencing the column to turn into a dictionary. This

is required to properly encode custom checks.

Returns:

The column definition as dictionary.

Note:

This method stores custom checks as expressions rather than callables to allow for serialization.

Note:

Do NOT use the returned object to evaluate semantic equality of two columns. It may yield different results than matches().

Attention:

This method is only intended for internal use.

property col: Expr

Obtain a Polars column expression for the column.

property dtype: DataType

The polars dtype equivalent of this column definition’s data type.

This is primarily used for creating empty data frames with an appropriate schema. Thus, it should describe the default dtype equivalent if this data type encompasses multiple underlying data types.

classmethod from_dict(data: dict[str, Any]) → Self

Read the column definition from a dictionary.

Args:

data: The dictionary that was created via as_dict().

Returns:

The column definition read from the dictionary.

Attention:

This method is only intended for internal use.

matches(other: Column, expr: Expr) → bool

Check whether this column semantically matches another column.

Args:

other: The column to compare with. expr: An expression referencing the column. This is required to properly

evaluate the equivalence of custom checks.

Returns:

Whether the columns are semantically equal.

property name: str

Get the name of the column in a schema.

property pyarrow_dtype: pa.DataType

The pyarrow dtype equivalent of this column data type.

pyarrow_field(name: str) → pa.Field

Obtain the pyarrow field of this column definition.

Args:

name: The name of the column.

Returns:

The pyarrow field definition.

sample(generator: Generator, n: int = 1) → Series

Sample random elements adhering to the constraints of this column.

Args:

generator: The generator to use for sampling elements. n: The number of elements to sample.

Returns:

A series with the predefined number of elements. All elements are guaranteed to adhere to the column’s constraints.

Raises:

ValueError: If this column has a custom check. In this case, random values

cannot be guaranteed to adhere to the column’s constraints while providing any guarantees on the computational complexity.

sqlalchemy_column(name: str, dialect: sa.Dialect) → sa.Column

Obtain the SQL column specification of this column definition.

Args:

name: The name of the column. dialect: The SQL dialect for which to generate the column specification.

Returns:

The column as specified in sqlalchemy.

sqlalchemy_dtype(dialect: sa.Dialect) → sa_TypeEngine

The sqlalchemy dtype equivalent of this column data type.

validate_dtype(dtype: DataType | DataTypeClass) → bool

Validate if the polars data type satisfies the column definition.

Args:

dtype: The dtype to validate.

Returns:

Whether the dtype is valid.

validation_rules(expr: Expr) → dict[str, Expr]

A set of rules evaluating whether a data frame column satisfies the column’s constraints.

Args:

expr: An expression referencing the column of the data frame, i.e. an

expression created by calling polars.col().

Returns:

A mapping from validation rule names to expressions that provide exactly one boolean value per column item indicating whether validation with respect to the rule is successful. A value of False indicates invalid data, i.e. unsuccessful validation.