xb.Frame#

class excelbird.Frame(fn: str | excelbird.core.function.Func, **kwargs)[source]#

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

A 2-dimensional vector that can be used in a python expression

Direction: horizontal
Child Type: Col

Parameters:

*argsUnion[Col, Row, Frame, VFrame, list, tuple, pd.Series, pd.DataFrame, np.ndarray, Gap, Item, Expr, Func, set, None]: Children must be (or resolve to) a series. Frame holds Cols, and VFrame holds Rows - Gap and Item will be interpreted as the respective element. Can also take any value that will be resolved to one of the above types, such as a list, tuple, pandas Series, etc. 2-dimensional arguments, such as pandas DataFrame, will be ‘exploded’ inplace into separate 1-dimensional elements.
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
schemaSchema, optional: A Schema object to use to rename child headers to desired output names at write time.
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.
sizesdict[str, int], optional: Specify the column width (or row height, if VFrame) for any child element by header. Keys should be the header of a child element, and values should be integers representing that element’s size. Note: unlike most excelbird styling, this argument will override any other column widths / row heights given to the children.
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. Will also be passed down to any Col/Row child who hasn’t specified its own background_color.
fill_emptybool, optional: Fill shorter children (if children vary in length) with Cell("") so that all lengths are matching, and all Cells inside the child will follow the same style. If False or None, these empty spaces will instead be filled with Gap(), to which the child’s background_color will be applied, if present.
cell_styledict, optional: Will be applied to each child’s cell_style
header_styledict, optional: Will be applied to each child’s header_style
table_styledict or bool, optional: Format a Frame as an Excel table. (ignored for VFrame). If True, default style ‘name=”TableStyleMedium2”’ is used. If dict, key ‘displayName’ will be used as the table name, and all other key/values will be passed to openpyxl.worksheet.table.TableStyleInfo.
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. To apply border to children instead, use cell_style.
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
**kwargsAny: Remaining kwargs will be applied to cell_style

Attributes:

headers: The headers of each child.
loc: When subscripted, provides an alternative to the default subscripting behavior.

Methods

`get`(key[, default])	Safely get an element.
`range`([include_headers])	Get a reference to the entire range of the frame, instead of a vector of cell references.
`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.

Properties

excelbird.Frame.headers#

The headers of each child. None will be placed at the index of children who have no header, so the returned list will be of the same length as self.

Returns:

list[str or None]

excelbird.Frame.loc#

When subscripted, provides an alternative to the default subscripting behavior. Instead of returning the elements found by the slice, a subscripted loc will return a range from the found elements.

Warning

Slices of loc will be inclusive of the ‘stop’ argument, unlike normal slices which exclude it.

For instance, my_frame.loc[2:5] is equivalent to my_frame[2] >> my_frame[5].

Returns:

Locable

xb.Frame Methods#

excelbird.Frame.range(self, include_headers: bool = False)#

Get a reference to the entire range of the frame, instead of a vector of cell references.

Parameters:

include_headersbool, default False: If True, the header cells will be included in the range reference.

Returns:

Cell

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

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.

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.

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

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:

Frame or VFrame: 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 both, use a reference of current instead

new = current.ref().transpose()

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