ExcelFrame

ExcelFrame

DataFrame-like object that allows referencing other cell's values lazily like an Excel spreadsheet.

Example

>>> import excelify as el
>>> df = el.ExcelFrame.empty(columns=["x", "y"], height=2)
>>> df
shape: (2, 2)
+---+-------+-------+
|   | x (A) | y (B) |
+---+-------+-------+
| 1 |       |       |
| 2 |       |       |
+---+-------+-------+
>>> df = df.with_columns(
...     el.lit([0, 1]).alias("x"),
...     el.col("x").alias("y"),
... )
>>> df
shape: (2, 2)
+---+-------+-------+
|   | x (A) | y (B) |
+---+-------+-------+
| 1 |   0   |  A1   |
| 2 |   1   |  A2   |
+---+-------+-------+
>>> df.evaluate()
shape: (2, 2)
+---+-------+-------+
|   | x (A) | y (B) |
+---+-------+-------+
| 1 |   0   |   0   |
| 2 |   1   |   1   |
+---+-------+-------+

columns property

columns: list[str]

List of column names in order.

height property

height: int

Height of the table.

shape property

shape: tuple[int, int]

Shape of the table.

width property

width: int

Width of the table.

empty classmethod

empty(*, columns: Sequence[str], height: int) -> ExcelFrame

Creates an empty table with given columns and height.

Parameters:

Name	Type	Description	Default
columns	Sequence[str]	list of columns	required
height	int	height of the table	required

Returns:

Type	Description
ExcelFrame	An empty ExcelFrame

evaluate

evaluate(inherit_style: bool = False) -> ExcelFrame

Evaluate the table and return a new table with numerical values only.

Example

>>> import excelify as el
>>> df = el.ExcelFrame.empty(columns=["x", "x_times_two"], height=2)
>>> df = df.with_columns(
...         el.lit([1, 2]).alias("x"),
...         (el.col("x") * 2).alias("x_times_two"),
...     )
>>> df.evaluate()
shape: (2, 2)
+---+-------+-----------------+
|   | x (A) | x_times_two (B) |
+---+-------+-----------------+
| 1 |   1   |        2        |
| 2 |   2   |        4        |
+---+-------+-----------------+

Parameters:

Name	Type	Description	Default
inherit_style	bool	If True, the returned table will also inherit the style of the original table.	False

Returns:

Type	Description
ExcelFrame	A new ExcelFrame where each cell represents a computed value.

select

select(columns: list[str]) -> Self

Select a list of columns. It can also be used to reorder the columns.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2], "y": [4, 5]})
>>> df = df.with_columns((el.col("x") + el.col("y")).alias("z"))
>>> df.select(["y", "x", "z"])
shape: (2, 3)
+---+-------+-------+---------+
|   | y (A) | x (B) |  z (C)  |
+---+-------+-------+---------+
| 1 |   4   |   1   | B1 + A1 |
| 2 |   5   |   2   | B2 + A2 |
+---+-------+-------+---------+
>>> df.select(["x", "z"])
shape: (2, 2)
+---+-------+--------------+
|   | x (A) |    z (B)     |
+---+-------+--------------+
| 1 |   1   | A1 + ???:y:0 |
| 2 |   2   | A2 + ???:y:1 |
+---+-------+--------------+

to_excel

to_excel(path: Path | str, *, start_pos: tuple[int, int] = (0, 0)) -> None

Writes the ExcelFrame to path in an .xlsx format.

Parameters:

Name	Type	Description	Default
path	Path | str	Path to write an .xlsx file to	required
start_pos	tuple[int, int]	Starting position of the table. It represents the table's upper left cell position.	(0, 0)

Returns:

Type	Description
None	None, but the file will be written to the path.

to_json

to_json(
    *, include_header: bool = False, start_pos: tuple[int, int] = (0, 0)
) -> Any

Returns a JSON that represents the ExcelFrame table. excelify-app uses it to get the JSON-formatted state of the ExcelFrame table.

Parameters:

Name	Type	Description	Default
include_header	bool	Include header in the beginning of the row if set to True	False
start_pos	tuple[int, int]	Starting position of the table. It represents the table's upper left cell position.	(0, 0)

Returns:

Type	Description
Any	a dict that represents JSON.

transpose

transpose(
    *,
    include_header: bool = False,
    header_name: str = "column",
    column_names: Iterable[str] | None = None,
) -> ExcelFrame

Transpose the table.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2], "y": [3, 4]})
>>> df = df.with_columns((el.col("x") + el.col("y")).alias("x_plus_y"))
>>> df
shape: (2, 3)
+---+-------+-------+--------------+
|   | x (A) | y (B) | x_plus_y (C) |
+---+-------+-------+--------------+
| 1 |   1   |   3   |   A1 + B1    |
| 2 |   2   |   4   |   A2 + B2    |
+---+-------+-------+--------------+
>>> df.transpose(include_header=True)
shape: (3, 3)
+---+------------+--------------+--------------+
|   | column (A) | column_0 (B) | column_1 (C) |
+---+------------+--------------+--------------+
| 1 |     x      |      1       |      2       |
| 2 |     y      |      3       |      4       |
| 3 |  x_plus_y  |   B1 + B2    |   C1 + C2    |
+---+------------+--------------+--------------+

Parameters:

Name	Type	Description	Default
include_header	bool	Add header as a separate column if set to True.	False
header_name	str	Name of the header column if include_header is set to True.	'column'
column_names	Iterable[str] | None	Name of the new ExcelFrame's columns.	None

Returns:

Type	Description
ExcelFrame	A transposed ExcelFrame

with_columns

with_columns(*exprs: Expr, **kwargs) -> Self

Adds or modifies an expression of the column to the table and returns a new ExcelFrame.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2]})
>>> df = df.with_columns(
...     el.map(
...         lambda idx: el.col("x")
...         if idx == 0
...         else el.col("cumulative_x_sum").prev(1) + el.col("x")
...     ).alias("cumulative_x_sum"),
...     x_times_two=el.col("x") * 2
... )
>>> df.select(["x", "x_times_two", "cumulative_x_sum"])
shape: (2, 3)
+---+-------+-----------------+----------------------+
|   | x (A) | x_times_two (B) | cumulative_x_sum (C) |
+---+-------+-----------------+----------------------+
| 1 |   1   |     A1 * 2      |          A1          |
| 2 |   2   |     A2 * 2      |       C1 + A2        |
+---+-------+-----------------+----------------------+

Parameters:

Name	Type	Description	Default
*exprs	Expr	expressions to add to the ExcelFrame	()
**kwargs		Column expressions whose name will be determined by the argument name.	{}

Returns:

Type	Description
Self	An ExcelFrame with added/updated columns based on the passed expressions.

concat

concat(dfs: Iterable[ExcelFrame]) -> ExcelFrame

Concatenates ExcelFrames along the rows into one. The cell references across the ExcelFrames will be converted to refer to cells within the outputted ExcelFrame. Cell reference outside the given ExcelFrames will still be kept as is.

Example

>>> import excelify as el
>>> df1 = el.ExcelFrame.empty(columns=["x", "y"], height=2)
>>> df1 = df1.with_columns(
...     el.lit([1, 2]).alias("x"),
...     el.lit([3, 4]).alias("y"),
... )
>>> df2 = el.ExcelFrame.empty(columns=["x", "y"], height=2)
>>> df2 = df2.with_columns(
...     el.col("x", from_=df1).alias("x"),
...     el.col("y", from_=df1).alias("y"),
... )
>>> el.concat([df1, df2])
shape: (4, 2)
+---+-------+-------+
|   | x (A) | y (B) |
+---+-------+-------+
| 1 |   1   |   3   |
| 2 |   2   |   4   |
| 3 |  A1   |  B1   |
| 4 |  A2   |  B2   |
+---+-------+-------+

Parameters:

Name	Type	Description	Default
dfs	Iterable[ExcelFrame]	An iterable of ExcelFrames to concatenate	required

Returns:

Type	Description
ExcelFrame	A concatenated ExcelFrame