CellBlock

@beartype
class CellBlock:
    """Represent a homogeneous block of cells within a mesh.

    This container ties a meshio cell type string to a connectivity array so
    downstream conversions can assemble meshio or PyVista objects without extra
    bookkeeping. It keeps the data minimal and relies on runtime validation to
    ensure consistency with meshio conventions.

    Attributes:
        type: meshio cell type identifier for the block.
        connectivity: Cell connectivity array for the block.

    Notes:
        This is a lightweight container that relies on runtime type checks for
        validation rather than additional internal logic.

    """

    type: Annotated[str, Is[lambda x: x in meshio._mesh.topological_dimension]]
    connectivity: NDArray[np.integer]

    def __init__(
        self: Self,
        type: Annotated[str, Is[lambda x: x in meshio._mesh.topological_dimension]],
        connectivity: NDArray[np.integer],
    ):
        """Initialize the cell block.

        Args:
            type: meshio cell type string for the block.
            connectivity: connectivity array of point indices where each row
                          represents a cell.

        Notes:
            The connectivity array is stored as-is, hence there are no checks on the
            shape of the array corresponding to the cell type. The integers in the
            connectivity array reference the rows in the mesh point array.

        """
        self.type = type
        self.connectivity = connectivity

    def __str__(self: Self) -> str:
        """Return a concise string representation.

        Returns:
            String describing the cell type and number of cells.

        """
        return f"CellBlock(type: {self.type}, cells: {self.connectivity.shape[0]})"

    def __repr__(self: Self) -> str:
        """Return the canonical representation.

        Returns:
            String representation used by interactive displays.

        """
        return self.__str__()

    def __eq__(self: Self, other: object) -> bool:
        """Equate cell blocks.

        Returns:
            ``True`` if both type and connectivity matches, else ``False``.

        """
        if not isinstance(other, CellBlock):
            return False
        return bool(
            (self.type == other.type)
            and np.array_equal(self.connectivity, other.connectivity)
        )