xnano.buffers

An image and how it is shown: what Canvas.write takes to put a picture on the canvas.

Make one from the path of an image file, its bytes, or a TerminalImage. A file is read once, here, where you can see it; write never takes a path. The placement values are what write uses when it is not given its own. An image sized by a percentage (or not sized at all) is converted again whenever the canvas is resized, so it always fits; give it a number, or lock=True, and it keeps its size.

Attributes:

• image (TerminalImage) –

  The picture.

• x (Axis | None) –

  The column of the left edge, or None for the top-left corner.

• y (Axis | None) –

  The row of the top edge, or None.

• width (Axis | None) –

  The width: cells, a percentage, an expression, or None for the picture's own.

• height (Axis | None) –

  The height, in the same forms.

• layer (int) –

  Content with a higher layer is drawn over content with a lower one.

• lock (bool) –

  Whether the image keeps the size it was shown at when the canvas is resized.

• fit (ImageFit | None) –

  How the picture sits in a box of width by height: 'contain' (the default), 'cover', 'stretch', 'crop' or 'smart'.

• resampling_filter (ResamplingFilter | None) –

  How pixels are blended when it is resized. By default a small picture that is enlarged keeps hard pixel edges ('nearest') and any other is smoothed ('lanczos3').

• background (tuple[int, int, int]) –

  The color behind transparent pixels and padding.

• symbol (str | None) –

  The name the image is registered under in symbols, or None.

Examples:

import xnano
from xnano.image import TerminalImage

picture = xnano.Image(TerminalImage.from_rgba(2, 2, bytes([255, 0, 0, 255]) * 4), width=8)
with xnano.new(width=20, height=6) as canvas:
    canvas.write(picture, x='center')
# xnano.Image('photo.png', width='100%') loads a file, and refits when the window resizes.

Load an image and set how it is shown.

Parameters:

• source (TerminalImage | PathLike[str] | str | bytes) –

  The path of an image file (PNG, JPEG, GIF, WebP or XNI), the bytes of one, or an image. An animated file plays on the canvas's clock.

• x (Axis | None, default: None ) –

  The column of the left edge: cells, a percentage, a word such as 'center', an expression or a range. See Axis.

• y (Axis | None, default: None ) –

  The row of the top edge, in the same forms.

• width (Axis | None, default: None ) –

  The width, in the same forms; the picture's own when None.

• height (Axis | None, default: None ) –

  The height, in the same forms.

• layer (int, default: 0 ) –

  Content with a higher layer is drawn over content with a lower one.

• lock (bool, default: False ) –

  Keep the size the image has when it is added, whatever the canvas does.

• fit (ImageFit | None, default: None ) –

  How the picture sits in a box of width by height.

• resampling_filter (ResamplingFilter | None, default: None ) –

  How pixels are blended when it is resized.

• background (ColorValue, default: (0, 0, 0) ) –

  The color behind transparent pixels and padding, as a color name, a hex string, an (r, g, b) tuple or a Color.

• speed (float, default: 1.0 ) –

  How fast an animated image plays: 2.0 is twice as fast.

• symbol (str | None, default: None ) –

  A name to register the image under in symbols.

Raises:

• ImportError –

  xnano-image is not installed. Install it with pip install "xnano[image]".

• TypeError –

  source is not a path, bytes or an image.

• FileNotFoundError –

  source is a path with no file at it.

• ValueError –

  symbol cannot be a symbol name, or another kind of value already has it.

464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544

def __init__(
    self,
    source: TerminalImage | os.PathLike[str] | str | bytes,
    *,
    x: Axis | None = None,
    y: Axis | None = None,
    width: Axis | None = None,
    height: Axis | None = None,
    layer: int = 0,
    lock: bool = False,
    fit: ImageFit | None = None,
    resampling_filter: ResamplingFilter | None = None,
    background: ColorValue = (0, 0, 0),
    speed: float = 1.0,
    symbol: str | None = None,
) -> None:
    """
    Load an image and set how it is shown.

    Args:
        source: The path of an image file (PNG, JPEG, GIF, WebP or XNI), the bytes of one,
            or an image. An animated file plays on the canvas's clock.
        x: The column of the left edge: cells, a percentage, a word such as ``'center'``, an
            expression or a range. See [`Axis`][xnano.types.Axis].
        y: The row of the top edge, in the same forms.
        width: The width, in the same forms; the picture's own when ``None``.
        height: The height, in the same forms.
        layer: Content with a higher layer is drawn over content with a lower one.
        lock: Keep the size the image has when it is added, whatever the canvas does.
        fit: How the picture sits in a box of ``width`` by ``height``.
        resampling_filter: How pixels are blended when it is resized.
        background: The color behind transparent pixels and padding, as a color name, a
            hex string, an ``(r, g, b)`` tuple or a [`Color`][xnano_core.Color].
        speed: How fast an animated image plays: ``2.0`` is twice as fast.
        symbol: A name to register the image under in [`symbols`][xnano.symbols].

    Raises:
        ImportError: ``xnano-image`` is not installed. Install it with
            ``pip install "xnano[image]"``.
        TypeError: ``source`` is not a path, bytes or an image.
        FileNotFoundError: ``source`` is a path with no file at it.
        ValueError: ``symbol`` cannot be a symbol name, or another kind of value
            already has it.
    """
    if is_image(source):
        image = cast('TerminalImage', source)
    else:
        module = require('image', needed_for='xnano.Image')
        if isinstance(source, bytes):
            image = module.TerminalImage.from_bytes(source)
        elif isinstance(source, (str, os.PathLike)):
            path = pathlib.Path(source)
            if not path.is_file():
                raise FileNotFoundError(
                    f'Image could not load {str(path)!r}, because no image file exists '
                    f'there. Check the path, or pass the bytes of the image.'
                )
            image = module.TerminalImage.open(path)
        else:
            raise TypeError(
                f'Image needs the path of an image file, the bytes of an image or an '
                f'image, but got {type(source).__name__}. Pass Image("picture.png").'
            )
    if speed != 1.0:
        image = image.with_speed(speed)
    for name, value in (
        ('image', image),
        ('x', x),
        ('y', y),
        ('width', width),
        ('height', height),
        ('layer', layer),
        ('lock', lock),
        ('fit', fit),
        ('resampling_filter', resampling_filter),
        ('background', to_rgb(background)),
        ('symbol', symbol),
    ):
        object.__setattr__(self, name, value)
    if symbol is not None:
        symbols.register(symbol, self)

Bases: Surface

A layer of cells with a position, a size and the hooks that animate it.

A buffer owns its cells, its geometry, its hook registrations and its place in a tree: it has at most one parent and is mounted on at most one runtime. Direct writes and operations share validation and revision tracking. Changing width or height keeps the cells that still fit and blanks new ones. Moving a mounted buffer redraws both its old and new area.

Parameters:

• content (TextContent | None, default: None ) –

  Text to start with. Without width and height the buffer is sized to fit it.

• width (int | None, default: None ) –

  The width in cells.

• height (int | None, default: None ) –

  The height in cells.

• x (int, default: 0 ) –

  The column of the buffer in its parent.

• y (int, default: 0 ) –

  The row of the buffer in its parent.

• style (Style | None, default: None ) –

  A style applied to the initial content.

• registry (Registry | None, default: None ) –

  The operation registry; defaults to the shared default registry.

Attributes:

• x (int) –

  The column of the buffer in its parent. Assigning moves the buffer.

• y (int) –

  The row of the buffer in its parent. Assigning moves the buffer.

• width (int) –

  The width in cells. Assigning resizes the buffer.

• height (int) –

  The height in cells. Assigning resizes the buffer.

• position (Point) –

  The Point of the buffer in its parent. Assigning moves the buffer.

• size (Size) –

  The Size of the buffer. Assigning resizes the buffer.

• bounds (Rectangle) –

  The buffer's rectangle in its parent.

• layer (int) –

  The stacking order among siblings; higher layers are drawn on top.

• is_visible (bool) –

  Whether the buffer is drawn. Hidden buffers still keep their content.

• is_focusable (bool) –

  Whether the buffer can receive input focus.

• content (Region) –

  The whole buffer as a region. Assigning text replaces the content.

• cells (Region) –

  The same view as content; there is only one store of cells.

• text (str) –

  The plain text of the buffer's own cells, without mounted children.

• revision (int) –

  A number that increases every time the buffer's cells or geometry change.

• children (tuple[Buffer, ...]) –

  The attached child buffers in attachment order.

• registry (Registry) –

  The registry that decides which operations this buffer can apply.

Examples:

card = Buffer(width=12, height=3, x=2, y=1)
card.update(Border('rounded'))
card.write('hello', x=1, y=1)
print(card.render(format='text'))

sized = Buffer('two\nlines')
assert (sized.width, sized.height) == (5, 2)

Create a Buffer.

Parameters:

• content (TextContent | None, default: None ) –

  TextContent | None. Defaults to None.

• width (int | None, default: None ) –

  int | None. Defaults to None.

• height (int | None, default: None ) –

  int | None. Defaults to None.

• x (int, default: 0 ) –

  int. Defaults to 0.

• y (int, default: 0 ) –

  int. Defaults to 0.

• style (Style | None, default: None ) –

  Style | None. Defaults to None.

• registry (Registry | None, default: None ) –

  Registry | None. Defaults to None.

Methods:

• __setitem__ –

  Replace one cell with a Cell or a single grapheme.

• write –

  Write text starting at a cell.

• fill –

  Set every cell of the surface.

• set_background_colors –

  Set the background color of a block of cells in one pass.

• set_foreground_colors –

  Set the foreground color of a block of cells in one pass.

• pixels –

  Return a pixel view that draws into this surface.

• update –

  Apply operations in argument order.

• inspect –

  Evaluate an expression against this surface and return its value.

• add_hook –

  Run a callback when the runtime reports matching events for this surface.

• invalidate –

  Ask the runtime to redraw an area, or the whole surface.

• to_cell_grid –

  Pack the surface into the cell grid byte format.

• __or__ –

  Apply operation to this surface and return the surface.

• with_text –

  Create a buffer sized to fit some text.

• with_size –

  Create a blank buffer of a given size.

• with_cells –

  Create a buffer from cells in row-major order.

• from_cell_grid –

  Create a buffer from the cell grid byte format.

• from_cell_animation –

  Create a buffer showing one frame of a packed cell animation.

• region –

  Return a region covering a rectangle of the buffer.

• resize –

  Change the size, keeping the cells that still fit.

• paste –

  Copy the cells of another buffer or region into this one.

• attach –

  Attach a child buffer as a retained layer of this one.

• detach –

  Remove an attached child.

• copy –

  Copy the cells, geometry and children into a new, independent buffer.

• supports –

  Return whether the buffer's registry can apply an operation type.

• __call__ –

  Return a lazy render of the buffer.

• render –

  Compose the visible children and serialize the buffer.

7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507

def __init__(
    self,
    content: TextContent | None = None,
    *,
    width: int | None = None,
    height: int | None = None,
    x: int = 0,
    y: int = 0,
    style: Style | None = None,
    registry: Registry | None = None,
) -> None:
    """
    Create a Buffer.

    Args:
        content: ``TextContent | None``. Defaults to ``None``.
        width: ``int | None``. Defaults to ``None``.
        height: ``int | None``. Defaults to ``None``.
        x: ``int``. Defaults to ``0``.
        y: ``int``. Defaults to ``0``.
        style: ``Style | None``. Defaults to ``None``.
        registry: ``Registry | None``. Defaults to ``None``.
    """

x: int

y: int

width: int

height: int

position: Point

size: Size

bounds: Rectangle

layer: int

parent = Buffer(width=6, height=1)
below = Buffer('a')
above = Buffer('b')
parent.attach(below)
parent.attach(above)
below.layer = 1
assert parent.render(format='text') == 'a'

is_visible: bool

is_focusable: bool

content: Region

cells: Region

text: str

revision: int

children: tuple[Buffer, ...]

registry: Registry

__setitem__(key: Coordinate, value: Cell | str) -> None

buffer = Buffer(width=3, height=1)
buffer[2, 0] = 'z'
buffer[0, 0] = Cell('a', foreground='green')
assert buffer.text == 'a z'

7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130

def __setitem__(self, key: Coordinate, value: Cell | str) -> None:
    """
    Replace one cell with a ``Cell`` or a single grapheme.

    Examples:
        ```python
        buffer = Buffer(width=3, height=1)
        buffer[2, 0] = 'z'
        buffer[0, 0] = Cell('a', foreground='green')
        assert buffer.text == 'a z'
        ```
    """

write(text: TextContent, *, x: int = 0, y: int = 0, style: Style | None = None, mode: WriteMode = 'replace') -> None

buffer = Buffer(width=6, height=2)
buffer.write('hi', x=1, y=0, style=Style(foreground='red'))
assert buffer[1, 0].foreground == Color('red')
assert buffer.text.split('\n')[0] == ' hi'

7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162

def write(
    self,
    text: TextContent,
    *,
    x: int = 0,
    y: int = 0,
    style: Style | None = None,
    mode: WriteMode = 'replace',
) -> None:
    """
    Write text starting at a cell.

    Text is clipped by display columns, whole graphemes are kept together and the
    continuation cells of wide characters are repaired.

    Args:
        text: A string or styled text.
        x: The starting column.
        y: The starting row.
        style: A style applied to the written cells.
        mode: ``'replace'`` overwrites the cell; ``'preserve_background'`` keeps
            the background already there.

    Examples:
        ```python
        buffer = Buffer(width=6, height=2)
        buffer.write('hi', x=1, y=0, style=Style(foreground='red'))
        assert buffer[1, 0].foreground == Color('red')
        assert buffer.text.split('\\n')[0] == ' hi'
        ```
    """

fill(cell: Cell | str = ' ') -> None

buffer = Buffer(width=3, height=1)
buffer.fill('#')
assert buffer.text == '###'

7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174

def fill(self, cell: Cell | str = ' ') -> None:
    """
    Set every cell of the surface.

    Examples:
        ```python
        buffer = Buffer(width=3, height=1)
        buffer.fill('#')
        assert buffer.text == '###'
        ```
    """

set_background_colors(colors: Sequence[ColorValue | None], *, width: int, x: int = 0, y: int = 0) -> None

buffer = Buffer(width=3, height=2)
buffer.write('abc')
buffer.set_background_colors(['red', None, (0, 0, 255), 'green'], width=2, x=1)
assert buffer[1, 0].background == Color('red')
assert buffer[2, 0].background == Color.reset
assert buffer[1, 1].background == Color('#0000ff')
assert buffer[2, 1].background == Color('green')
assert buffer[1, 0].symbol == 'b'

7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214

def set_background_colors(
    self,
    colors: Sequence[ColorValue | None],
    *,
    width: int,
    x: int = 0,
    y: int = 0,
) -> None:
    """
    Set the background color of a block of cells in one pass.

    Symbols and foreground colors are kept, and the whole block counts as one change (the
    revision grows by one).

    Args:
        colors: A flat, row-major sequence of colors (names, ``(r, g, b)`` tuples or
            [`Color`][xnano_core._xnano_core.Color] values). ``None`` leaves a cell alone.
        width: The number of colors in one row of ``colors``.
        x: The column of the block's top-left cell in this surface.
        y: The row of the block's top-left cell in this surface.

    Raises:
        ValueError: ``width`` is below 1, ``len(colors)`` is not a multiple of ``width``, or
            the block does not fit inside the surface, or an entry is not a color.
        TypeError: ``colors`` is a single string instead of a sequence of colors, or an
            entry has no color meaning.

    Examples:
        ```python
        buffer = Buffer(width=3, height=2)
        buffer.write('abc')
        buffer.set_background_colors(['red', None, (0, 0, 255), 'green'], width=2, x=1)
        assert buffer[1, 0].background == Color('red')
        assert buffer[2, 0].background == Color.reset
        assert buffer[1, 1].background == Color('#0000ff')
        assert buffer[2, 1].background == Color('green')
        assert buffer[1, 0].symbol == 'b'
        ```
    """

set_foreground_colors(colors: Sequence[ColorValue | None], *, width: int, x: int = 0, y: int = 0) -> None

buffer = Buffer(width=3, height=2)
buffer.write('abc')
buffer.set_foreground_colors(['red', None, (0, 0, 255), 'green'], width=2, x=1)
assert buffer[1, 0].foreground == Color('red')
assert buffer[2, 0].foreground == Color.reset
assert buffer[1, 1].foreground == Color('#0000ff')
assert buffer[2, 1].foreground == Color('green')
assert buffer[1, 0].symbol == 'b'

7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254

def set_foreground_colors(
    self,
    colors: Sequence[ColorValue | None],
    *,
    width: int,
    x: int = 0,
    y: int = 0,
) -> None:
    """
    Set the foreground color of a block of cells in one pass.

    Symbols and background colors are kept, and the whole block counts as one change (the
    revision grows by one).

    Args:
        colors: A flat, row-major sequence of colors (names, ``(r, g, b)`` tuples or
            [`Color`][xnano_core._xnano_core.Color] values). ``None`` leaves a cell alone.
        width: The number of colors in one row of ``colors``.
        x: The column of the block's top-left cell in this surface.
        y: The row of the block's top-left cell in this surface.

    Raises:
        ValueError: ``width`` is below 1, ``len(colors)`` is not a multiple of ``width``, or
            the block does not fit inside the surface, or an entry is not a color.
        TypeError: ``colors`` is a single string instead of a sequence of colors, or an
            entry has no color meaning.

    Examples:
        ```python
        buffer = Buffer(width=3, height=2)
        buffer.write('abc')
        buffer.set_foreground_colors(['red', None, (0, 0, 255), 'green'], width=2, x=1)
        assert buffer[1, 0].foreground == Color('red')
        assert buffer[2, 0].foreground == Color.reset
        assert buffer[1, 1].foreground == Color('#0000ff')
        assert buffer[2, 1].foreground == Color('green')
        assert buffer[1, 0].symbol == 'b'
        ```
    """

pixels(*, encoding: PixelEncoding = 'half_blocks') -> PixelView

buffer = Buffer(width=3, height=2)
assert (buffer.pixels().width, buffer.pixels().height) == (3, 4)
assert (buffer.pixels(encoding='braille').width) == 6

7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270

def pixels(self, *, encoding: PixelEncoding = 'half_blocks') -> PixelView:
    """
    Return a pixel view that draws into this surface.

    Args:
        encoding: ``'half_blocks'`` for one column and two rows per cell or
            ``'braille'`` for two columns and four rows per cell.

    Examples:
        ```python
        buffer = Buffer(width=3, height=2)
        assert (buffer.pixels().width, buffer.pixels().height) == (3, 4)
        assert (buffer.pixels(encoding='braille').width) == 6
        ```
    """

update(*operations: Operation) -> None

buffer = Buffer(width=8, height=3)
buffer.update(Border('rounded'), Write('hi', x=1, y=1))
assert buffer[0, 0].symbol == '╭'
assert buffer[1, 1].symbol == 'h'

7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287

def update(self, *operations: Operation) -> None:
    """
    Apply operations in argument order.

    Raises:
        UnsupportedOperationError: The surface's registry cannot apply an operation.
        RuntimeRequiredError: An operation needs a mounted buffer on a runtime.

    Examples:
        ```python
        buffer = Buffer(width=8, height=3)
        buffer.update(Border('rounded'), Write('hi', x=1, y=1))
        assert buffer[0, 0].symbol == '╭'
        assert buffer[1, 1].symbol == 'h'
        ```
    """

inspect(expression: Expression[ValueType]) -> ValueType

width = _reference('Width', 'numeric_property')
height = _reference('Height', 'numeric_property')
buffer = Buffer(width=8, height=3)
assert buffer.inspect(width) == 8
assert buffer.inspect(width * height) == 24