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 callself.ref()
to make an exact reference to its cells.- Parameters:
- *args
Union
[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
- sep
Gap
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.
- schema
Schema
,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
- **kwargs
Any
Remaining kwargs will be applied to cell_style
- *args
- 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.
- inherit_stylebool,
- Returns:
Self
Notes
Note
Children’s
header
attributes are stylistic attributes, and therefore will not be passed to the returned object’s children unlessinherit_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:
- **kwargs
Any
Keyword arguments to apply as attributes to the new object.
- **kwargs
- Returns:
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
orheader
(if series) of a child element.- default
Any
,default
None Value to return if nothing is found
- Returns:
Any
Note that some dynamic elements, such as
Gap
orExpr
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:
- **kwargs
Any
All keyword arguments will be set as attributes on self, via
setattr()
- **kwargs
- 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) )