neptyne.cell_range

CellRange is a class that represents a range of cells in a sheet. It can be 1D or 2D. CellRange is a subclass of Sequence

Of particular note is that cell ranges are iterable. This means that you can loop over the cells in a cell range.

For example:

for row in A1:C4:
    for cell in row:
        print(cell)

CellRanges are also indexable and sliceable. This means you can access individual cells or ranges of cells using square brackets. This indexing supports numpy style syntax for convenience.

For example:

A1:C4[0] # Returns the first row of the cell range
A1:C4[0:2] # Returns the first 2 rows of the cell range
A1:C4[:, 1] # Returns the second column of the cell range
A1:C4[0, 1] # Returns the cell in the first row and second column

A1:C4[1, 0] = "Hello" # Sets the value of the cell in the second row and first column to "Hello"
A1:C4[1, 1:3] = [1, 2] # Sets the values of the cells in the first row and second and third columns to 1 and 2
A1:C4[0, 0] = ['spills', 'down', 'ward'] # Spills down the first column starting at the first row

class CellRange(collections.abc.Sequence):

All the operations on a read-only sequence.

Concrete subclasses must override __new__ or __init__, __getitem__, and __len__.

two_dimensional: bool

Whether or not the cell range is 2D. Single rows and columns are represented as 1D cell range.

def is_empty(self) -> bool:

Returns True if all the cells in the cell range are empty.

def insert_row( self, index: int, data: Any = None, amount: int | None = None) -> neptyne_kernel.cell_range.CellRange:

Insert a row at the specified index.

If data is provided, data will be spilled into the new row(s).

If amount is provided, amount rows are inserted

Returns a new cell range representing the inserted row(s).

Data supports a wide variety of types such as lists, dictionaries and dataframes using standard Neptyne spilling. An error will be thrown if the data does not fit the dimensions of the cell range.

All other insert/append/delete operations accept data and amount parameters in the same way.

Example usage:

A1:B4.insert_row(1, data=[[1, 2], [3, 4]], amount=2)

def insert_column( self, index: int, data: Any = None, amount: int | None = None) -> neptyne_kernel.cell_range.CellRange:

Insert columns at the specified index.

Works the same way as insert_row, but for columns. Data is still spilled the same way spreading multi-dimensional arrays across rows into the new column(s)

def delete_row(self, index: int, amount: int = 1) -> None:

Delete 1 row starting at the specified index.

If amount is provided, amount rows are deleted.

def delete_column(self, index: int, amount: int = 1) -> None:

Delete 1 column starting at the specified index.

If amount is provided, amount columns are deleted.

def append_row( self, data: Any = None, amount: int | None = None) -> neptyne_kernel.cell_range.CellRange:

Append a row to the cell range.

There is no index argument as the row is appended to the end of the cell range.

If data is provided, data will be spilled into the new row(s).

If amount is provided, amount rows are appended

Returns a new cell range representing the inserted row(s).

def append_column( self, data: Any = None, amount: int | None = None) -> neptyne_kernel.cell_range.CellRange:

Append column(s) to the cell range.

Works the same way as append_row, but for columns.

def sort_rows( self, by_column: int | Sequence[int] | None = None, reverse: bool = False, key: Optional[Callable] = None) -> None:

Sorts the rows in the cell range in place.

If by_column is provided, the rows will be sorted by the values in the specified column(s).

If reverse is True, the rows will be sorted in descending order.

If key is provided, it will be used to extract a comparison key from each row.

by_column and key are mutually exclusive.

def any(self) -> bool:

Returns true if any the values in the cell range are 'truthy'

def all(self) -> bool:

Returns true if all the values in the cell range are 'truthy'

def to_list(self) -> list:

Converts the cell range to a list. If the cell range is 2D, it will be a list of lists.

def boolean_mask_operator( self, other: Any, op: Callable) -> neptyne_kernel.cell_range.CellRangeList:

Applies a boolean mask operator between the cell range and a scalar 'other'. The operator is applied element-wise.

This function is used to implement the comparison operators (<, >, <=, >=, !=, ==) which can all be applied to cell ranges against a scalar.

For example:

A1:A4 < 4

will return a cell range with the same shape as A1:A4, where each cell is True if the value in A1:A4 is less than 4, and False otherwise.

def apply_operator( self, other: Any, op: Callable, reverse: bool = False) -> neptyne_kernel.cell_range.CellRangeList:

Applies a binary operator to the cell range and a scalar 'other' of the same shape. The operator is applied element-wise.

This function is used to implement the binary operators (+, -, *, /, //) which can all be applied between cell ranges or lists other collections of the same size.

For example:

A1:B2 + A3:B4

will return a cell range maintaining the 2x2 shape of A1:B2 and A3:B4, where each cell is the sum of the corresponding cells in A1:B2 and A3:B4.

def map(self, to_apply: Callable) -> neptyne_kernel.cell_range.CellRangeList:

Applies a function to each cell in the cell range. The function should take a single argument and return a single value.

def to_dataframe( self, header: bool = True, dtype: dict[str, typing.Any] | None = None) -> pandas.core.frame.DataFrame:

Converts the cell range to a pandas DataFrame. The first row will be used as the column names. Subsequent rows will be the data.

def to_pandas(self) -> pandas.core.frame.DataFrame:

A wrapper around to_dataframe which emulates arrow's to_pandas method.

def pivot_table(self, *args: Any, **kwargs: Any) -> pandas.core.frame.DataFrame:

Returns a pivot table from the cell range. This function is a wrapper around pandas' pivot_table function.

shape: tuple[int, int] | tuple[int]

Returns the shape of the cell range. If the cell range is 2D, it will return a tuple of (rows, cols). If the cell range is 1D, it will return a tuple of (length,).

range: neptyne_kernel.cell_address.Range

Returns the range of the cell range.

@dataclass(frozen=True)

class Range:

Represents an immutable excel style range as numbers. To mimic excel most accurately, max_* are inclusive

For infinite ranges, -1 is used as the max_*

Range(min_col: int, max_col: int, min_row: int, max_row: int, sheet: int)

min_col: int

The minimum column in the range

max_col: int

The maximum column in the range. -1 for infinite

min_row: int

The minimum row in the range

max_row: int

The maximum row in the range. -1 for infinite

def is_fully_bounded(self) -> bool:

Returns True if the range is fully bounded, i.e. has a definite max_col and max_row.

def is_bounded(self) -> bool:

Returns True if the range is bounded, i.e. has a definite max_col or max_row.

def origin(self) -> neptyne_kernel.cell_address.Address:

Returns the top-left cell of the range.

def translated(self, dx: int, dy: int) -> neptyne_kernel.cell_address.Range:

Returns a new range translated by dx columns and dy rows.

def extended(self, dx: int, dy: int) -> neptyne_kernel.cell_address.Range:

Returns a new range extended by dx columns and dy rows.

def intersects(self, other: neptyne_kernel.cell_address.Range) -> bool:

Returns True if the range intersects with another range.

def shape(self) -> tuple[int, int]:

Returns the shape of the range as a tuple of (n_rows, n_cols).

def dimensions(self) -> int:

Returns the number of dimensions of the range. 1 if either n_rows or n_cols is 1, 2 otherwise.

@classmethod

def from_a1(cls, a1: str, sheet: int = 0) -> neptyne_kernel.cell_address.Range:

Creates a range from an A1:B4 notation string.

def to_a1(self) -> str:

Converts the range to A1:B4 notation.

def to_dict(self) -> dict[str, int]:

Converts the range to a dictionary.

@classmethod

def from_dict(cls, d: dict) -> neptyne_kernel.cell_address.Range:

Creates a range from a dictionary.

def to_coord(self) -> tuple[int, int, int, int, int]:

Converts the range to a tuple.