xb.Cell

class excelbird.Cell(fn: str | excelbird.core.function.Func, **kwargs)

class excelbird.Cell(ex: str | set | excelbird.core.expression.Expr, **kwargs)

class excelbird.Cell(value: Any | None = None, dropdown: list | Any | None = None, id: str | None = None, align_x: str | None = None, align_y: str | None = None, indent: float | None = None, center: bool | None = None, wrap: bool | None = None, size: int | None = None, bold: bool | None = None, italic: bool | None = None, color: str | None = None, num_fmt: str | None = None, currency: bool | None = None, ignore_format: bool | None = None, fill_color: str | None = None, auto_color_font: bool | str | None = None, auto_shade_font: bool | float | None = None, border_left: bool | str | None = None, border_right: bool | str | None = None, border_top: bool | str | None = None, border_bottom: bool | str | None = None, border: bool | str | None = None, col_width: int | None = None, row_height: int | None = None, merge: tuple[int, int] | None = None, _expr: list | None = None, _func: list | None = None, autofit: bool | None = None, cell_style: dict | None = None, _written: bool | None = None)

Represents a real cell in Excel. Capable of math operations in python, and tracking cell references on its own, without knowing locations.

Excelbird cells are not mere containers for data. Since they represent a real object in Excel, each can only exist once inside a Book. This is because when you reference a Cell in a python expression (i.e. cell_c = cell_a + cell_b), cell references will be established so that when cell_c is written to the workbook, its value will be a formula that references the real locations of cell_a and cell_b. So if cell_a is found in multiple places in a Book, this formula could not be resolved.

ALL attributes have a default of None. This allows parent containers to know whether a value has been set or not, to avoid override. For any attribute, if you just want to ignore the value set by a parent container, set its value to False, even if it isn’t documented as accepting a boolean.

Parameters:

valuestr or int or float, optional

Value to display. If None, the Cell’s styling will NOT be rendered. To display an empty cell with styling, pass an empty string as a value. This attribute will temporarily be None if a Cell references other Cells in an expression. For instance, if cell3 = cell1 + cell2, cell3’s value will be None, until the parent book’s .write() is called and cell1 and cell2’s locations have been determined.

dropdownlist or Cell or Col or Row, optional

Apply data validation for the cell that offers a dropdown list of values to pick from. Pass a list of options, or a Cell, Col, or Row.

idstr, optional

Unique identifier to store globally so that this element can be referenced elsewhere in the layout without being assigned to a variable

align_xstr, optional

Horizontal alignment. Options: ‘center’, ‘right’, ‘left’

align_ystr, optional

Vertical alignment. Options: ‘top’, ‘center’, ‘bottom’

indentint or float, optional

Indent the cell’s value. Indentation direction will depend on horizontal alignment, so if align_x=’right’, the indentation will determine its distance from the right edge of the cell.

centerbool, optional

Center the cell horizontally and vertically. Shorthand for setting align_x and align_y to ‘center’

wrapbool, optional

Wrap the cell’s text so that it doesn’t continue outside of its boundary. As long as row_height=None and col_width=None, Excel will automatically resize the cell to display the full text.

sizeint, optional

Font size

boldbool, optional

Bold font

italicbool, optional

Italic font

colorstr, optional

Font color, as a hex code

num_fmtstr, optional

Cell value format. See the styles module for available formats

currencybool, optional

Indicate that this Cell might contain a currency value. If value is an int or float and num_fmt has not been set, apply accounting format. The recommended use-case for this attribute is to set currency=True for a parent container once, and all of its numerical data will be formatted accordingly

ignore_formatbool, optional

Negate any number formatting set by a parent container. This is an easier alternative to setting num_fmt=False, currency=False

fill_colorstr, optional

Hex code string color to fill the cell

auto_color_fontbool, optional

Sets font color to white or black, based on lightness of fill_color, so that text will be visible over any background. Lightness of fill_color is measured using the weighted euclidean norm of the rgb vector. If the resulting coefficient indicates a medium to light color, lightness will be re-calculated from the Luma of the rgb vector.

auto_shade_fontbool, optional

Font color will be a lighter or darker shade of fill_color. If fill_color is dark, a lighter shade will be chosen as the font color, and vice versa. Lightness coefficient of fill_color is measured using the weighted euclidean norm of the rgb vector. If the resulting coefficient indicates a medium to light color, lightness will be re-calculated from the Luma of the rgb vector.

borderlist[tuple or str or bool] or tuple[str or bool, str or bool] or str or bool, optional

Syntax inspired by CSS. A non-list value will be applied to all 4 sides. If list, length can be 2, 3, or 4 elements. Order is [top, right, bottom, left]. If length 2, apply the first element to top and bottom border, and apply the second element to right and left.

border_toptuple[str or bool, str or bool] or str or bool, optional

Top border. If True, a thin black border is used. If string (6 char hex code), use the default weight and apply the specified color. If string (valid weight name), use the default color and apply the specified weight. If tuple, apply the first element as weight, and second element as color.

border_righttuple[str or bool, str or bool] or str or bool, optional

Right border. See border_top

border_bottomtuple[str or bool, str or bool] or str or bool, optional

Bottom border. See border_top

border_lefttuple[str or bool, str or bool] or str or bool, optional

Left border. See border_top

col_widthint, optional

Column width. Format is the same as used in Excel.

row_heightint, optional

Row height. Format is the same as used in Excel.

autofitbool, optional

Autofit column width based on the length of the value. This is NOT as accurate as the built-in autofit feature in Excel. This is because we can’t determine the rendered width without actually rendering the value in the desired font and size, and counting pixels.

mergetuple[int, int], optional

Merge this cell with other cells to its right or below. First element is the distance to merge below, and second element is the distance to merge across. For instance, (0, 1) will merge the current Cell with the one to the right. (1,1) will merge diagonally in a square. The cells being merged must have values of None. For instance, if you have a Row of multiple values and want the first and second elements to be merged, your code would be as follows: Row(Cell('a', merge=(0,1)), Cell(), Cell('b'), Cell('c')) - notice the second Cell is empty

cell_styledict, optional

A dict that contains attributes to set. Priority is given to existing attributes - An attribute in cell_style will only be set if the Cell’s attribute is currently None

Attributes:

is_empty

Methods

ref([inherit_style])

Get a new Cell who will display a cell reference to the current cell.

xb.Cell Methods

excelbird.Cell.ref(self, inherit_style: bool = False, **kwargs) → Cell

Get a new Cell who will display a cell reference to the current cell. This assumes that both the calling object and the returned object will be placed in the workbook.

Note

Calling .ref() is not necessary when an object is used in a python expression (i.e. some_cell + some_row) and should only be used to duplicate data across a workbook.

Parameters:

inherit_stylebool, default False

Copy the caller’s style to the returned object.

**kwargsAny

Extra keyword arguments are set as attributes on the returned object.

Returns:

Cell