xb.Sheet#

class excelbird.Sheet(*args: Any, children: list | None = None, title: str | None = None, sep: Any | None = None, tab_color: str | None = None, end_gap: bool | int | dict | excelbird.core.gap.Gap | None = None, isolate: bool | None = None, hidden: bool | None = None, zoom: int | None = None, background_color: str | None = None, cell_style: excelbird._base.dotdict.Style | dict | None = None, header_style: excelbird._base.dotdict.Style | dict | None = None, table_style: excelbird._base.dotdict.Style | dict | bool | None = None, **kwargs)[source]#

Behaves similar to VStack - it can hold any element, and arranges its children vertically - but lacks some styling features like margin and padding.

Note

If the first argument in *args is a string, it will be used as the title attribute. This allows for better readability in complex layouts with multiple sheets, so a sheet’s title can be visible at the start of the container.

Parameters:
*argsUnion[Stack, VStack, Frame, VFrame, Col, Row, Cell, list, tuple, str, int, float, pd.Series, pd.DataFrame, np.ndarray, Gap, Expr, Func, set, None]

Can take any layout element (besides Book and Sheet) or any value that can be used to construct a layout element.

childrenlist, optional

Will be combined with args

titlestr, optional

Sheet name

sepGap or bool or int or dict, optional

A sep in any excelbird layout element inserts a Gap between each of its children. If True, a default of Gap(1) is used. If int, Gap(sep) will be used. If a dict, Gap(1, **sep) will be used.

tab_colorstr, optional

Hex color for tab color.

end_gapbool or int or dict or Gap, optional

Applies a Gap to cells below and to the right of the Sheet. The Gap determines the number of columns filled, and 1/3 the number of rows filled. The default is Gap(35, fill_color=”FFFFFF”) (white). This means apply whitespace (hide grid) for 35 columns, and 105 rows surrounding the Sheet contents.

isolatebool, optional

After initialization, clear the global memory of ids and headers, so references in future declared Sheets won’t conflict with previous ones. This will also isolate previously declared Sheets, so they musn’t reference elements declared after the current one.

hiddenbool, optional

Whether to hide the Sheet

zoomint, optional

Percentage zoom level. (Passing None or 100 will have the same effect)

background_colorstr, optional

Hex code for background_color. Will be applied to fill_color of any Gap child who hasn’t specified its own fill_color, and to any child Stack/VStack’s margins. Will also be passed down to any child (Cell excluded) who hasn’t specified its own background_color.

cell_styledict, optional

Applied to each child who has cell_style

header_styledict, optional

Applied to each child who has header_style

table_styledict or bool, optional

Applied to each child who has table_style

**kwargsAny

Remaining kwargs will be applied to self.cell_style

Attributes:
loc

When subscripted, provides an alternative to the default subscripting behavior.

margin
padding

Methods

get(key[, default])

Safely get an element.

ref([inherit_style])

Get a new object with cell references to those in the caller.

set(**kwargs)

Set attributes inline.

transpose(**kwargs)

Convert to sibling type.

xb.Sheet Methods#

excelbird.Sheet.ref(self, inherit_style: bool = False, **kwargs) → VStack#

Get a new object with cell references to those in the caller. This assumes that both the calling object and the returned object will be placed in the workbook.

Parameters:
inherit_stylebool, default False

Copy the caller’s style to the returned object.

Returns:
Self

Notes

Note

Children’s header attributes are stylistic attributes, and therefore will not be passed to the returned object’s children unless inherit_style=True. And, if style is inherited, headers will be copied over to the children, instead of cell references to them.


excelbird.Sheet.transpose(self, **kwargs) → Stack#

Convert to sibling type. Places current children into the returned object, without copying or making cell references to them.

Parameters:
**kwargsAny

Keyword arguments to apply as attributes to the new object.

Returns:
Stack or VStack

The opposite to self’s type. Try type(my_obj).sibling_type

Notes

Assumes that the caller won’t be placed in the layout. Do not place both the calling object and returned object in the layout, since they both contain the same children.

# 'current' must not be placed in the workbook.
new = current.transpose()

To include the caller and make cell references to it, get a reference first:

new = current.ref().transpose()


excelbird.Sheet.get(self, key, default=None) → Any#

Safely get an element.

Parameters:
keystr or int

The index, id or header (if series) of a child element.

defaultAny, default None

Value to return if nothing is found

Returns:
Any

Note that some dynamic elements, such as Gap or Expr may not have been resolved to a valid child type yet.

Notes

Note

Excelbird containers are all subclasses of list so you can access elements using square brackets the same as you would with a list.


excelbird.Sheet.set(self, **kwargs) → ListIndexableById#

Set attributes inline.

Useful if defining a complex layout and setting attributes dynamically via either a list comprehension or inline conditionals.

Parameters:
**kwargsAny

All keyword arguments will be set as attributes on self, via setattr()

Returns:
Self

Examples

Instead of having to set an attribute ahead of time, like

if len(elem) > 5:
    elem.bold = True

Book(
    elem,
)

Set the attribute inline!

Book(
    elem if len(elem) < 5 else elem.set(bold=True)
)