Grid¶
A grid of cells.
Example of grid:
.. doctest:: grid_demo
>>> from benker.grid import Grid
>>> from benker.cell import Cell
>>> grid = Grid()
>>> grid[1, 1] = Cell("red", height=2)
>>> grid[2, 1] = Cell("pink", width=2)
>>> grid[2, 2] = Cell("blue")
>>> print(grid)
+-----------+-----------------------+
| red | pink |
| +-----------+-----------+
| | blue | |
+-----------+-----------+-----------+
You can retrieve the grid cells as follow:
>>> from benker.grid import Grid
>>> from benker.cell import Cell
>>> grid = Grid()
>>> grid[1, 1] = Cell("red", height=2)
>>> grid[2, 1] = Cell("pink", width=2)
>>> grid[2, 2] = Cell("blue")
>>> grid[1, 1]
<Cell('red', styles={}, nature=None, x=1, y=1, width=1, height=2)>
>>> grid[2, 1]
<Cell('pink', styles={}, nature=None, x=2, y=1, width=2, height=1)>
>>> grid[2, 2]
<Cell('blue', styles={}, nature=None, x=2, y=2, width=1, height=1)>
>>> grid[3, 3]
Traceback (most recent call last):
...
KeyError: Coord(x=3, y=3)
A grid has a bounding box, useful to get the grid sizes:
>>> from benker.grid import Grid
>>> from benker.cell import Cell
>>> grid = Grid()
>>> grid[1, 1] = Cell("red", height=2)
>>> grid[2, 1] = Cell("pink", width=2)
>>> grid[2, 2] = Cell("blue")
>>> grid.bounding_box
Box(min=Coord(x=1, y=1), max=Coord(x=3, y=2))
>>> grid.bounding_box.size
Size(width=3, height=2)
You can expand the cell size horizontally or vertically:
>>> from benker.grid import Grid
>>> from benker.cell import Cell
>>> grid = Grid()
>>> grid[1, 1] = Cell("red", height=2)
>>> grid[2, 1] = Cell("pink", width=2)
>>> grid[2, 2] = Cell("blue")
>>> grid.expand((2, 2), width=1)
<Cell('blue', styles={}, nature=None, x=2, y=2, width=2, height=1)>
>>> print(grid)
+-----------+-----------------------+
| red | pink |
| +-----------------------+
| | blue |
+-----------+-----------------------+
The content of the merged cells is merged too:
>>> from benker.grid import Grid
>>> from benker.cell import Cell
>>> grid = Grid()
>>> grid[1, 1] = Cell("red", height=2)
>>> grid[2, 1] = Cell("pink", width=2)
>>> grid[2, 2] = Cell("blue", width=2)
>>> grid.merge((2, 1), (3, 2), content_appender=lambda a, b: "/".join([a, b]))
<Cell('pink/blue', styles={}, nature=None, x=2, y=1, width=2, height=2)>
>>> print(grid)
+-----------+-----------------------+
| red | pink/blue |
| | |
| | |
+-----------+-----------------------+
- class benker.grid.Grid(cells=None)¶
Bases:
collections.abc.MutableMapping
Collection of
Cell
objects ordered in a grid of rows and columns.- property bounding_box¶
Bounding box of the grid (
None
if the grid is empty).
- expand(coord, width=0, height=0, content_appender=None)¶
Expand (or shrink) the width and/or height of a cell, using the content_appender to append cell contents.
See also the method
merge()
to merge a group of cells contained in a bounding box.- Parameters
coord – Coordinates of the cell to expand (or shrink).
width – Number of columns to add to the cell width.
height – Number of rows to add to the cell height.
content_appender – Function to use to append the cell contents. The function must have the following signature:
f(a, b) -> c
, where a, b anc c must be of the same type than the cell content. If not provided, the default function isoperator.__add__()
.
- Returns
The merged cell.
- Raises
ValueError – If the group of cells is empty or if cells cannot be merged.
- iter_rows()¶
Iterate the cells grouped by rows.
- merge(start, end, content_appender=None)¶
Merge a group of cells contained in a bounding box, using the content_appender to append cell contents.
The coordinates start and end delimit a group of cells to merge.
Warning
All the cells of the group must be included in the group bounding box, no intersection is allowed. If not,
ValueError
is raised.See also the method
expand()
to expand (or shrink) the width and/or height of a cell.- Parameters
start (Coord or tuple[int, int]) – Top-left coordinates of the group of cells to merge.
end – Bottom-right coordinates of the group of cells to merge (inclusive).
content_appender – Function to use to append the cell contents. The function must have the following signature:
f(a, b) -> c
, where a, b anc c must be of the same type than the cell content. If not provided, the default function isoperator.__add__()
.
- Returns
The merged cell.
- Raises
ValueError – If the group of cells is empty or if cells cannot be merged.