xb.Stack#

class excelbird.Stack(*args: Any, children: list | None = None, id: str | int | None = None, sep: Any | None = None, background_color: str | None = None, margin: int | list[int] | None = None, margin_top: int | None = None, margin_right: int | None = None, margin_bottom: int | None = None, margin_left: int | None = None, padding: int | list[int] | None = None, padding_top: int | None = None, padding_right: int | None = None, padding_bottom: int | None = None, padding_left: int | None = None, schema: 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]#

A general container that can hold any element, including itself. Offers unique spatial styling features, like margin and padding, described below.

Note

Stacks cannot be used in a python expression, or included in a Func. However, you can still call self.ref() to make an exact reference to its cells.

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 or Sheet), or any value that can be used to construct a layout element. Stack is the only layout element that can store other instances of itself as children

childrenlist, optional

Will be combined with args

idstr, optional

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

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.

background_colorstr, optional

Hex code for background_color. Will be applied to fill_color of padding, 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.

schemaSchema, optional

Applied to each child who takes schema

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

marginint or list[int], optional

Margin, like padding, will apply space around the element. Unlike padding, margin space will NOT inherit any of the element’s styling. It will, however, be filled with the parent container’s background_color, if present. Syntax inspired by CSS. An int, if passed, 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 margin, and second to right and left.

margin_topint, optional

Top margin, measured in number of cells

margin_rightint, optional

Right margin, measured in number of cells

margin_bottomint, optional

Bottom marign, measured in number of cells

margin_leftint, optional

Left margin, measured in number of cells

paddingint or list[int], optional

Padding, like margin, will apply space around the element. Unlike margin, padding space WILL inherit the element’s styling, like background_color. Syntax inspired by CSS. An int, if passed, 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 margin, and second to right and left.

padding_topint, optional

Top padding, measured in number of cells

padding_rightint, optional

Right padding, measured in number of cells

padding_bottomint, optional

Bottom padding, measured in number of cells

padding_leftint, optional

Left padding, measured in number of cells

**kwargsAny

Remaining kwargs will be applied to 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.Stack Methods#

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

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.Stack.transpose(self, **kwargs) → VStack#

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.Stack.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.Stack.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)
)