Skip to content

xnano.core.frame

xnano.core.frame

xnano.core.frame

Inspect immutable text, cursor, device, and revision data from a rendered frame.

Classes:

  • Frame –

    Immutable snapshot of one painted native frame.

Functions:

Frame dataclass 

Frame(
    width: int,
    height: int,
    text: str = "",
    ansi: str = "",
    cursor_position: tuple[int, int] | None = None,
    cursor_visible: bool = True,
    cursor_style: str | None = None,
    title: str | None = None,
    commands: tuple[Mapping[str, Any], ...] = (),
    revision: int = 0,
)

Immutable snapshot of one painted native frame.

Example

Frame(width=20, height=4, text="Ready")

Attributes:

Methods:

  • contains –

    Return whether plain text contains needle.

width instance-attribute 

width: int

Frame width in cells.

height instance-attribute 

height: int

Frame height in cells.

text class-attribute instance-attribute 

text: str = ''

Plain-text cell rows.

ansi class-attribute instance-attribute 

ansi: str = ''

ANSI-styled cell rows.

cursor_position class-attribute instance-attribute 

cursor_position: tuple[int, int] | None = None

Caret position in cells.

cursor_visible class-attribute instance-attribute 

cursor_visible: bool = True

Whether the caret is visible.

cursor_style class-attribute instance-attribute 

cursor_style: str | None = None

Caret shape and blink style.

title class-attribute instance-attribute 

title: str | None = None

Window or document title.

commands class-attribute instance-attribute 

commands: tuple[Mapping[str, Any], ...] = ()

Device commands emitted with the frame.

revision class-attribute instance-attribute 

revision: int = 0

Monotonic frame revision.

rows property 

rows: tuple[str, ...]

Plain-text rows of the frame.

contains 

contains(needle: str) -> bool

Return whether plain text contains needle.

Source code in xnano/core/frame.py 
66
67
68
def contains(self, needle: str) -> bool:
    """Return whether plain text contains ``needle``."""
    return needle in self.text

frame_from_terminal 

frame_from_terminal(
    terminal: Any, *, revision: int = 0
) -> Frame

Build a Frame snapshot from a terminal or runtime.

Parameters:

  • terminal (Any) –

    Object exposing size/output/cursor/device.

  • revision (int, default: 0 ) –

    Monotonic revision to stamp on the frame.

Returns:

  • Frame –

    An immutable Frame.

Source code in xnano/core/frame.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def frame_from_terminal(terminal: Any, *, revision: int = 0) -> Frame:
    """Build a ``Frame`` snapshot from a terminal or runtime.

    Args:
        terminal: Object exposing size/output/cursor/device.
        revision: Monotonic revision to stamp on the frame.

    Returns:
        An immutable ``Frame``.
    """
    size: Any = getattr(terminal, "size", (0, 0))
    if callable(size):
        size = size()
    if hasattr(size, "width") and hasattr(size, "height"):
        width, height = int(size.width), int(size.height)
    else:
        width, height = int(size[0]), int(size[1])
    text = ""
    ansi = ""
    get_output = getattr(terminal, "get_output", None)
    get_ansi = getattr(terminal, "get_output_as_ansi", None)
    if callable(get_output):
        text = str(get_output())
    if callable(get_ansi):
        ansi = str(get_ansi())
    cursor = getattr(terminal, "cursor", None)
    position = None
    visible = True
    style = None
    if cursor is not None:
        get_position = getattr(cursor, "get_position", None)
        pos = (
            get_position()
            if callable(get_position)
            else getattr(cursor, "position", None)
        )
        if callable(pos):
            pos = pos()
        if isinstance(pos, Sequence) and len(pos) >= 2:
            position = (int(pos[0]), int(pos[1]))
        visible = bool(getattr(cursor, "visible", True))
        style = getattr(cursor, "style", None)
        if callable(style):
            style = style()
    device = getattr(terminal, "device", None)
    title = None
    if device is not None:
        title = getattr(device, "title", None)
        if callable(title):
            title = title()
    commands = tuple(getattr(terminal, "_frame_commands", ()) or ())
    return Frame(
        width=width,
        height=height,
        text=text,
        ansi=ansi,
        cursor_position=position,
        cursor_visible=visible,
        cursor_style=str(style) if style is not None else None,
        title=str(title) if title is not None else None,
        commands=commands,
        revision=revision,
    )