irx.table_io

irx.table_io

Source: packages/irx/src/irx/table_io.py

title: Simple native CSV and Parquet table I/O.
summary: >-
  Eager reads return independently owned PyArrow tables; writes borrow their
  input and check finalization. Importing this module performs no native build
  or optional Parquet loading. Format engines remain in the IRx native runtime.

Functions

where(column: str, operation: str, value: str | int | float | bool | None=None) -> ParquetFilter

title: Create a checked predicate without serialized values or type tags.
parameters:
  column:
    type: str
  operation:
    type: str
  value:
    type: str | int | float | bool | None
returns:
  type: ParquetFilter

table_library(parquet: bool=False) -> ctypes.CDLL

title: Bind table symbols lazily and reject stale native overrides.
parameters:
  parquet:
    type: bool
returns:
  type: ctypes.CDLL

check_arrow(status: int, lib: ctypes.CDLL) -> None

title: Check the Arrow runtime status before reading any output slots.
parameters:
  status:
    type: int
  lib:
    type: ctypes.CDLL

export_table(handle: ctypes.c_void_p, lib: ctypes.CDLL) -> pa.Table

title: Transfer independent table references through the C Stream ABI.
parameters:
  handle:
    type: ctypes.c_void_p
  lib:
    type: ctypes.CDLL
returns:
  type: pa.Table

import_table(table: pa.Table, lib: ctypes.CDLL) -> Iterator[ctypes.c_void_p]

title: Borrow a PyArrow table through chunk-preserving C Stream references.
parameters:
  table:
    type: pa.Table
  lib:
    type: ctypes.CDLL
returns:
  type: Iterator[ctypes.c_void_p]

schema_handle(schema: pa.Schema | None) -> Iterator[ctypes.c_void_p | None]

title: Keep an optional imported schema alive through a native read.
parameters:
  schema:
    type: pa.Schema | None
returns:
  type: Iterator[ctypes.c_void_p | None]

selection(values: Sequence[str] | None, name: str, allow_empty: bool=False) -> tuple[str, ...] | None

title: Validate and snapshot string selectors before native side effects.
parameters:
  values:
    type: Sequence[str] | None
  name:
    type: str
  allow_empty:
    type: bool
returns:
  type: tuple[str, Ellipsis] | None

csv_options(lib: ctypes.CDLL, integers: dict[str, int], texts: dict[str, str], lists: dict[str, tuple[str, ...] | None]) -> Iterator[ctypes.c_void_p]

title: Own checked native CSV options for one operation.
parameters:
  lib:
    type: ctypes.CDLL
  integers:
    type: dict[str, int]
  texts:
    type: dict[str, str]
  lists:
    type: dict[str, tuple[str, Ellipsis] | None]
returns:
  type: Iterator[ctypes.c_void_p]

read_csv(path: str | os.PathLike[str], *, schema: pa.Schema | None=None, columns: Sequence[str] | None=None, names: Sequence[str] | None=None, delimiter: str=',', header: bool=True, quotechar: str='"', doublequote: bool=True, escapechar: str='', skiprows: int=0, skip_blank_lines: bool=False, null_values: Sequence[str]=('',), block_size: int=1048576) -> pa.Table

title: Read all CSV rows with strict parsing before optional projection.
summary: >-
  The eager result must fit in memory. Inference freezes after the first
  block; schema controls parsing. Names require header=False and no schema.
  Quoted empty strings remain strings, unlike default unquoted empty nulls.
parameters:
  path:
    type: str | os.PathLike[str]
  schema:
    type: pa.Schema | None
  columns:
    type: Sequence[str] | None
  names:
    type: Sequence[str] | None
  delimiter:
    type: str
  header:
    type: bool
  quotechar:
    type: str
  doublequote:
    type: bool
  escapechar:
    type: str
  skiprows:
    type: int
  skip_blank_lines:
    type: bool
  null_values:
    type: Sequence[str]
  block_size:
    type: int
returns:
  type: pa.Table

write_csv(frame: pa.Table, path: str | os.PathLike[str], *, delimiter: str=',', header: bool=True, lineterminator: str='\n', na_rep: str='', quoting: Literal['needed', 'all_valid', 'none']='needed') -> None

title: Write all chunks and check finalization without consuming the table.
summary: >-
  CSV is nontransactional. Custom null tokens can collide with non-null
  data; use matching read null_values. Do not assume lossless roundtrips.
parameters:
  frame:
    type: pa.Table
  path:
    type: str | os.PathLike[str]
  delimiter:
    type: str
  header:
    type: bool
  lineterminator:
    type: str
  na_rep:
    type: str
  quoting:
    type: Literal[needed, all_valid, none]

read_parquet(path: str | os.PathLike[str], *, schema: pa.Schema | None=None, columns: Sequence[str] | None=None, filters: ParquetFilter | None=None, row_groups: Sequence[int] | None=None, options: ParquetOptions | None=None, batch_size: int | None=None) -> pa.Table

title: Read exact rows, discovering files or Hive datasets by default.
summary: >-
  Explicit keywords replace options snapshots without mutating the input.
  None means an omitted override. Schema asserts the final projected types.
parameters:
  path:
    type: str | os.PathLike[str]
  schema:
    type: pa.Schema | None
  columns:
    type: Sequence[str] | None
  filters:
    type: ParquetFilter | None
  row_groups:
    type: Sequence[int] | None
  options:
    type: ParquetOptions | None
  batch_size:
    type: int | None
returns:
  type: pa.Table

write_parquet(frame: pa.Table, path: str | os.PathLike[str], *, compression: str | None=None, row_group_size: int | None=None, atomic: bool | None=None, durable: bool | None=None, append: bool | None=None, partition_columns: Sequence[str] | None=None, options: ParquetOptions | None=None) -> None

title: Write exact table types using explicit overrides and checked close.
summary: >-
  Default compression is snappy; row-group size is 1048576. Atomic writes
  are opt-in and POSIX-local; None means no keyword override. Partitioned
  output selects Hive dataset mode unless explicit options say otherwise.
parameters:
  frame:
    type: pa.Table
  path:
    type: str | os.PathLike[str]
  compression:
    type: str | None
  row_group_size:
    type: int | None
  atomic:
    type: bool | None
  durable:
    type: bool | None
  append:
    type: bool | None
  partition_columns:
    type: Sequence[str] | None
  options:
    type: ParquetOptions | None

Classes

ParquetFilter

title: Immutable AND predicate group with independent composition.
attributes:
  predicates:
    type: tuple[ParquetPredicate, Ellipsis]

Methods

and_where(self, column: str, operation: str, value: str | int | float | bool | None=None) -> ParquetFilter
title: Return a new group, preserving the original and its aliases.
parameters:
  column:
    type: str
  operation:
    type: str
  value:
    type: str | int | float | bool | None
returns:
  type: ParquetFilter
Back to top