Python API

The Python package has four main types:

Type	Role
Series	One named, typed eager column
DataFrame	An eager table and its mutation, reshape, persistence, and Arrow interop methods
Expr	A reusable node in a lazy expression tree
LazyFrame	An optimized query plan that executes at collect()

The package also exports GroupBy, QueryCtx, expression constructors, file scanners, Arrow import, concatenation, and worker-pool controls. keyten.__version__ reports the installed package version.

Conventions

Two conventions apply across the API:

• Where a method accepts expressions (select, with_columns, group_by, agg, over), a bare string names a column.
• Where a method accepts a value (filter, lit, arithmetic, comparisons, if_else, corr), a bare string is a string literal. Use col("name") for a column reference.

Expressions and lazy frames are immutable builders. Each call returns a new object. A DataFrame is eager and supports explicit in-place mutation through append, upsert, update, and delete; lazy frames created before a mutation keep their original snapshot.

Reference map

• Expressions: operators, math, nulls, strings, temporal functions, aggregation, windows, and recoding
• Series and DataFrame: construction, inspection, reshape, mutation, rows, and persistence
• LazyFrame and GroupBy: transforms, joins, execution, progress, and plan serialization
• Input, output, and runtime: CSV, Parquet, native tables, out-of-core execution, and worker threads
• Arrow interop: PyCapsule import/export and the supported type map
• Remote and distributed execution: workers, path mapping, fallback rules, and security

Errors

All engine exceptions derive from KeytenError:

Exception	Meaning
SchemaError	Unknown column, kind mismatch, invalid cast, or misplaced aggregate
ComputeError	Malformed input, shape failure, corrupt data, or another execution-time data error
CancelledError	A query observed cancellation at a block boundary

File-system failures raise OSError, memory exhaustion raises MemoryError, and invalid Python argument forms raise TypeError or ValueError at the call that validates them.