xb.Row#

class excelbird.Row(fn: str | excelbird.core.function.Func, **kwargs)[source]#
class excelbird.Row(ex: str | set | excelbird.core.expression.Expr, **kwargs)
class excelbird.Row(*args: Any, children: list | None = None, id: str | None = None, header: str | None = None, sep: Any | None = None, border_left: bool | str | None = None, border_right: bool | str | None = None, border_top: bool | str | None = None, border_bottom: bool | str | None = None, border: Optional[Union[bool, str, Iterable]] = None, background_color: str | None = None, cell_style: excelbird._base.dotdict.Style | dict | None = None, header_style: excelbird._base.dotdict.Style | dict | None = None, **kwargs)

A 1-dimensional vector that can be used in a python expression and can be prefixed with a header.

  • Direction: horizontal

  • Child Type: Cell

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

Children must be, or resolve to, Cell. Iterables will be exploded inplace. So, if given 1, pandas.Series([2, 3]), 4, it will be read as 1, 2, 3, 4 before converting the ints to Cell. If a pandas.Series is passed as the only argument, its name (if present) will be used as header.

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

headerstr, optional

Unique identifier to be inserted as a Cell at position 0 at write time. Can be referenced by an Expr elsewhere in the layout. Set automatically if a named pandas.Series is given. Read more

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 any Gap child who hasn’t specified its own fill_color.

cell_styledict, optional

Each key/value will be used to set an attribute on each child Cell (header excluded) only if the respective attribute has not already been set on the child Cell (its value is None). This mimics HTML/CSS behavior, where styling declared at the parent level is passed down to children, but each child can override the parent.

header_styledict, optional

Just like cell_style, but for the header only. Ignored if header is None.

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:
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 range of the series, 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.

from_valid_children

Properties

excelbird.Row.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.Row Methods#

excelbird.Row.range(self, include_headers: bool = False) → Cell#

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

Parameters:
include_headersbool, default False

If True, the header cell will be included in the range reference.

Returns:
Cell


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

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.

**kwargsAny

Extra keyword arguments are set as attributes on the returned object.

Returns:
Self

Notes

Note

self.header is a stylistic attribute, and therefore will not be passed to the returned object unless inherit_style=True. And, if style is inherited, the header will be copied to its new cell, instead of having a cell reference made to it.


excelbird.Row.transpose(self, **kwargs) → Col#

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:
Col or Row

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