xb.Book

class excelbird.Book(*args: Any, children: list | None = None, path: str | None = None, auto_open: bool = False, sep: Any | None = None, tab_color: str | None = None, end_gap: bool | int | dict | excelbird.core.gap.Gap | None = None, isolate: bool | None = None, zoom: int | 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)

The outer-most parent container for a layout. Only Book has the ability to write to an Excel file.

Call .write(path) to save to an Excel file.

• Child Type: Sheet

Parameters:

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

Each element, if not a Sheet, will be placed in its own separate Sheet. Vectors which aren’t layout types (like list, or pd.DataFrame) will be inferred as Col or Frame

childrenlist, optional

Will be combined with args

pathstr, optional

Path to write Book. Can be omitted and passed to .write() instead

auto_openbool, default False

Attempt to automatically open after calling .write(). If a file with the same name is already open, it will be closed first. Requires dependency, xlwings

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

Applied to each child Sheet

end_gapbool or int or dict or Gap, optional

Applied to each child Sheet

isolatebool, optional

Applied to each child Sheet

zoomint, optional

Applied to each child Sheet

cell_styledict, optional

Applied to each child Sheet

header_styledict, optional

Applied to each child Sheet

table_styledict or bool, optional

Applied to each child Sheet

**kwargs

Remaining keyword arguments applied to cell_style, to be passed down to children

Attributes:

loc

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

Methods

get(key[, default])	Safely get an element.
set(**kwargs)	Set attributes inline.
write([path])	Evaluates the layout tree and writes the completed layout to a .xlsx file.

xb.Book Methods

excelbird.Book.write(self, path: str | None = None) → None

Evaluates the layout tree and writes the completed layout to a .xlsx file.

Parameters:

pathstr, optional

Full path to the output file. Only exclude if path attribute has already been set.

Notes

The algorithm, step by step

• First, all references inside each Expr in the layout is resolved and evaluated

• Now that the true size and shape of each layout element is known, spatial styling can be resolved

  • Margin and padding values are interpreted to create correctly sized Gap spacing

  • Background colors are applied to the appropriate cells, drilling breadth-first through the tree.

  • Then, all Gaps are evaluated as correctly sized and styled layout elements.

• Now that the layout structure, input data, and styling is complete

  • Traverse the tree and iteratevely assign a true sheet/column/row coordinate to each Cell individually. Notice that only cells who were placed directly inside the Book get assigned a location. Later on, this lets us ensure that the formulas and cell references we create are valid.

  • Call each child’s ._write() method. Each layout element’s write method will safely pass down styling to its children, and then call each child’s write method.

• Cells which contain cell references don’t know the value of their formula until their ._write() is called. At this point, their expression is nothing more than a binary tree of references to other Python objects. When recursively expanding the tree to a formula string, we’re able to tell whether a referenced Cell is actually being placed in the workbook or not, since unplaced Cells were never assigned locations. Therefore, we will always end up with a valid formula, because instead of trying to reference a non-existent cell, we take its value or formula and include it in our own.

excelbird.Book.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.Book.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)
)