cell

Cell dataclass

A unit that represents a single, possibly ANSI-styled character.

Source code in pytermgui/cell.py

@dataclass
class Cell:
    """A unit that represents a single, possibly ANSI-styled character."""

    char: str = ""
    styles: str = ""

    _foreground: str | None = None
    _background: str | None = None

    def __str__(self) -> str:
        """Gets the content of this cell."""

        return self.styles + self.char

    @property
    def foreground(self) -> str | None:
        """Returns the currently set foreground color in this cell."""

        return self._foreground

    @foreground.setter
    def foreground(self, new: str | None) -> None:
        """Allows setting the foreground color, while unsetting the current one."""

        current = self.foreground

        if current is not None:
            self.styles = self.styles.replace(current, "")

        self.styles += new

        if new is not None:
            self._foreground = f"\x1b[{new}m"

        else:
            self._foreground = None

    @property
    def background(self) -> str | None:
        """Returns the currently set background color in this cell."""

        return self._background

    @background.setter
    def background(self, new: str | None) -> None:
        """Allows setting the background color, while unsetting the current one."""

        current = self.background

        if current is not None:
            self.styles = self.styles.replace(current, "")

        self.styles += new

        if new is not None:
            self._background = f"\x1b[{new}m"

        else:
            self._background = None

    @classmethod
    def from_line(cls, line: str, styles: str = "") -> Generator[None, None, Cell]:
        """Yields Cells generated from a line of text.

        Args:
            line: The input line. May or may not contain ANSI styles.
            styles: Styles that are applied to the line from before the line started.

        Returns:
            A Cell generator.
        """

        in_style = False
        current_style = styles
        current_styles = []

        for char in line:
            if char == STYLE_START_CHAR:
                in_style = True
                current_style = ""
                continue

            if in_style:
                if char == "[":
                    continue

                if char == STYLE_END_CHAR:
                    current_styles.append(current_style)
                    in_style = False
                    continue

                current_style += char
                continue

            current_styles, fore, back = _process_styles(current_styles)

            yield Cell(char or " ", _combine(current_styles), fore, back)

        if current_style != "":
            current_styles, fore, back = _process_styles(
                current_styles + [current_style]
            )

            yield Cell("", _combine(current_styles), fore, back)

    @classmethod
    def first_of(cls, line: str) -> Cell:
        """Returns the first cell yielded by `from_line`."""

        for cell in cls.from_line(line):
            return cell

background: str | None property writable

Returns the currently set background color in this cell.

foreground: str | None property writable

Returns the currently set foreground color in this cell.

__str__()

Gets the content of this cell.

Source code in pytermgui/cell.py

def __str__(self) -> str:
    """Gets the content of this cell."""

    return self.styles + self.char

first_of(line) classmethod

Returns the first cell yielded by from_line.

Source code in pytermgui/cell.py

@classmethod
def first_of(cls, line: str) -> Cell:
    """Returns the first cell yielded by `from_line`."""

    for cell in cls.from_line(line):
        return cell

from_line(line, styles='') classmethod

Yields Cells generated from a line of text.

Parameters:

Name	Type	Description	Default
line	str	The input line. May or may not contain ANSI styles.	required
styles	str	Styles that are applied to the line from before the line started.	''

Returns:

Type	Description
Generator[None, None, Cell]	A Cell generator.

Source code in pytermgui/cell.py

@classmethod
def from_line(cls, line: str, styles: str = "") -> Generator[None, None, Cell]:
    """Yields Cells generated from a line of text.

    Args:
        line: The input line. May or may not contain ANSI styles.
        styles: Styles that are applied to the line from before the line started.

    Returns:
        A Cell generator.
    """

    in_style = False
    current_style = styles
    current_styles = []

    for char in line:
        if char == STYLE_START_CHAR:
            in_style = True
            current_style = ""
            continue

        if in_style:
            if char == "[":
                continue

            if char == STYLE_END_CHAR:
                current_styles.append(current_style)
                in_style = False
                continue

            current_style += char
            continue

        current_styles, fore, back = _process_styles(current_styles)

        yield Cell(char or " ", _combine(current_styles), fore, back)

    if current_style != "":
        current_styles, fore, back = _process_styles(
            current_styles + [current_style]
        )

        yield Cell("", _combine(current_styles), fore, back)