xnano.region

def __contains__(self, point: object) -> bool:
    """
    Whether a screen cell is inside the region.

    Args:
        point: A ``(x, y)`` pair or a [`Point`][xnano_core.Point] in screen cells, such
            as ``context.mouse.position``.
    """
    if isinstance(point, _core.Point):
        column, row = point.x, point.y
    elif isinstance(point, tuple) and len(point) == 2:
        column, row = point
    else:
        return False
    width, height = self._cell_size()
    origin_x = self.x
    origin_y = self.y
    return (
        origin_x <= column < origin_x + width and origin_y <= row < origin_y + height
    )

def local(self, point: _core.Point) -> _core.Point:
    """
    Convert a screen cell into a cell of this region.

    Args:
        point: A cell in screen coordinates, such as ``context.mouse.position``.
    """
    point = check_point(point)
    return _core.Point(point.x - self.x, point.y - self.y)

def resize(self, width: int, height: int) -> None:
    """
    Change the size of the region, in cells.

    On a view of a placement this resizes the placement. A standalone region made by
    [`box`][xnano.box] keeps its cells where they fit. A region made by
    [`write`][xnano.write] is sized by its text, border, padding and margin, so it
    cannot be resized.

    Args:
        width: The new width in cells.
        height: The new height in cells.

    Raises:
        TerminalError: The region is the view of a canvas, whose size follows its screen,
            a slice of another region, or it was made by ``write``, whose size follows
            its text.
        ValueError: A size is below 1 or above 65535.
    """
    _check_cell_counts('resize', width, height)
    if width < 1 or height < 1:
        raise ValueError(
            f'A region is at least 1 by 1 cells, but resize got {width} by {height}. '
            f'Pass whole numbers of cells, 1 or more.'
        )
    owner = self._owner
    if self._is_standalone and self._is_text:
        raise TerminalError(
            'A region made by write() is sized by its text, border, padding and margin, '
            'so resize() cannot change it. Make a region of a size you choose with '
            'xnano.box(width, height), or change the text or the padding.'
        )
    if self._is_standalone:
        self._resize_standalone(width, height)
        return
    if owner is None or not hasattr(owner, '_set_axis'):
        if owner is None or any(self._inset):
            raise TerminalError(
                'A slice of a region is a window onto it and cannot be resized. Resize the '
                'region it was taken from with its resize(width, height), or take a new '
                'slice.'
            )
        raise TerminalError(
            'The size of a canvas follows its screen or its width and height; set '
            'those instead of resizing its region.'
        )
    left, top, right, bottom = self._inset
    placement = cast('Placement[object, object]', owner)
    extra_width = left + right
    extra_height = top + bottom
    decorated = getattr(placement, '_decorated', None)
    if decorated is not None:
        extra_width += decorated.insets.horizontal
        extra_height += decorated.insets.vertical
    placement.width = width + extra_width
    placement.height = height + extra_height

def __getitem__(self, key: tuple[int | slice, int | slice]) -> Pixel | Region:
    """
    Read a cell (a [`Pixel`][xnano.pixel.Pixel]) or take a part of the region.

    Args:
        key: ``(x, y)`` in region coordinates, or two slices without a step.

    Raises:
        IndexError: A coordinate is outside the region; the message names the valid ranges.
        TypeError: The key is a screen [`Point`][xnano_core.Point] or not a pair.
        ValueError: A slice has a step, or a slice is taken from a pixel resolution.
    """
    if type(key) is tuple and len(key) == 2 and self._resolution == 'cells':
        column, row = key
        if type(column) is int and type(row) is int:
            self._flush_look()
            buffer = self._buffer
            if (
                not any(self._inset)
                and 0 <= column < buffer.width
                and 0 <= row < buffer.height
            ):
                cell = buffer[column, row]
                foreground = cell.foreground
                background = cell.background
                return Pixel._of(
                    cell.symbol,
                    None if foreground is None or foreground.is_reset else foreground,
                    None if background is None or background.is_reset else background,
                )
    self._check_point(key)
    column, row = key
    if isinstance(column, slice) or isinstance(row, slice):
        if self._resolution != 'cells':
            raise ValueError(
                f'A slice of a {self._resolution} region would cut cells in two. '
                f'Take the slice from the cell region (region[0:5, 0:2]) and then '
                f'use .{self._resolution}.'
            )
        width, height = self._cell_size()
        first_x, last_x = self._span(column, width, 'x')
        first_y, last_y = self._span(row, height, 'y')
        left, top, right, bottom = self._inset
        view = Region(
            self._buffer,
            owner=self._owner,
            inset=(
                left + first_x,
                top + first_y,
                right + (width - last_x),
                bottom + (height - last_y),
            ),
        )
        view._canvas = self._canvas
        return view
    column, row = self._check_bounds(column, row)
    surface = self._surface()
    if self._resolution == 'cells':
        cell = surface[column, row]
        return Pixel._of(
            cell.symbol, _plain(cell.foreground), _plain(cell.background)
        )
    if self._resolution == 'half_blocks':
        cell = surface[column, row // 2]
        is_top = row % 2 == 0
        symbol = cell.symbol
        if symbol == '▀':
            color = cell.foreground if is_top else cell.background
        elif symbol == '▄':
            color = cell.background if is_top else cell.foreground
        elif symbol == '█':
            color = cell.foreground
        else:
            color = cell.background
        plain = _plain(color)
        return Pixel._of('█', plain) if plain is not None else Pixel._of(' ')
    cell = surface[column // 2, row // 4]
    code = ord(cell.symbol[0]) - 0x2800 if cell.symbol else -1
    is_set = 0 <= code <= 0xFF and bool(code & _BRAILLE_BITS[row % 4][column % 2])
    return Pixel._of('•', _plain(cell.foreground)) if is_set else Pixel._of(' ')

def __setitem__(
    self,
    key: tuple[int | slice, int | slice],
    value: Pixel | _core.Color | tuple[int, int, int] | str | object,
) -> None:
    """
    Write a pixel, a color, text or content into a cell or a part of the region.

    * A [`Pixel`][xnano.pixel.Pixel] writes its character and colors; over a slice it fills it.
    * A [`Color`][xnano_core.Color] or an ``(red, green, blue)`` tuple sets the background
      of a cell (the color of a pixel or dot at the other resolutions). A ``str`` is never
      a color: make one with ``Color('#336699')``.
    * A ``str`` is text, written from the cell and clipped at the slice.
    * Any other content that ``write`` accepts covers a slice.

    Args:
        key: ``(x, y)`` in region coordinates, or two slices without a step.
        value: What to write.

    Raises:
        IndexError: A coordinate is outside the region.
        TypeError: A single cell was given content that needs a slice, a screen
            [`Point`][xnano_core.Point] was used as the key, or text was written at a
            pixel resolution.
        ValueError: A slice has a step.
    """
    if type(key) is tuple and len(key) == 2 and self._resolution == 'cells':
        column, row = key
        if type(column) is int and type(row) is int and type(value) is Pixel:
            self._flush_look()
            buffer = self._buffer
            if (
                not any(self._inset)
                and 0 <= column < buffer.width
                and 0 <= row < buffer.height
            ):
                buffer[column, row] = value.cell()
                return
    self._check_point(key)
    column, row = key
    if isinstance(column, int) and isinstance(row, int):
        x, y = self._check_bounds(column, row)
        self._set_cell(x, y, value)
        return
    width, height = self.width, self.height
    first_x, last_x = self._span(column, width, 'x')
    first_y, last_y = self._span(row, height, 'y')
    if last_x <= first_x or last_y <= first_y:
        return
    self._set_block(first_x, last_x, first_y, last_y, value)

def shade(self, function: Callable[[int, int], ColorValue | None]) -> None:
    """
    Color every cell, pixel or dot from a function of its position, in one write.

    At the default resolution the function is called for each cell and the result is
    the cell's background; ``region.half_blocks.shade`` and ``region.braille.shade`` call
    it for each pixel or dot.

    Args:
        function: Called with ``(x, y)`` in region coordinates; return the color, or
            ``None`` to leave the cell alone.

    Examples:
        ```python
        import xnano

        with xnano.new(width=4, height=2) as canvas:
            canvas.region.shade(lambda x, y: (x * 60, y * 60, 0) if x < 3 else None)
            assert canvas.region[2, 1].background.to_rgb() == (120, 60, 0)
            canvas.region.half_blocks.shade(lambda x, y: (0, y * 30, 0))
            assert canvas.region.half_blocks[0, 3].foreground is not None
        ```
    """
    _check_shade_function(function)
    if self._resolution == 'cells':
        width, height = self._cell_size()
        if width == 0 or height == 0:
            return
        colors = [
            function(column, row) for row in range(height) for column in range(width)
        ]
        self._surface().set_background_colors(colors, width=width)
        return
    view = self._pixel_view()
    colored: list[tuple[int, int, RGB]] = []
    for row in range(view.height):
        for column in range(view.width):
            color = function(column, row)
            if color is not None:
                colored.append((column, row, to_rgb(color)))
    view.write(colored)

def draw_color_bytes(
    self,
    data: bytes,
    *,
    width: int,
    height: int,
    x: int = 0,
    y: int = 0,
    mode: _core.RasterMode = 'over',
) -> None:
    """
    Draw a row-major RGBA image with its top-left pixel at ``(x, y)``.

    At the default resolution the image is drawn with half-block pixels.

    Args:
        data: ``width * height * 4`` bytes of red, green, blue and alpha.
        width: The image width in pixels.
        height: The image height in pixels.
        x: The pixel column of the image's left edge.
        y: The pixel row of the image's top edge.
        mode: ``'over'`` blends by alpha; ``'replace'`` overwrites.
    """
    self._pixel_view().draw_rgba(
        data, width=width, height=height, x=x, y=y, mode=mode
    )

def draw_image(
    self,
    image: Image | TerminalImage,
    *,
    x: int = 0,
    y: int = 0,
    mode: _core.RasterMode = 'over',
    frame_index: int = 0,
) -> None:
    """
    Draw an image with its top-left pixel at ``(x, y)``.

    Pixels outside the region are skipped, so drawing a large image at a negative ``x``
    and ``y`` scrolls it. At the default resolution the image is drawn with half-block
    pixels.

    Args:
        image: An [`Image`][xnano.Image] or a picture from ``xnano.image``. It needs the
            optional ``xnano-image`` package.
        x: The pixel column of the image's left edge. May be negative.
        y: The pixel row of the image's top edge. May be negative.
        mode: ``'over'`` blends by alpha; ``'replace'`` overwrites.
        frame_index: Which frame of an animated image to draw.
    """
    from xnano._media import Image as MediaImage

    picture = image.image if isinstance(image, MediaImage) else image
    if not hasattr(picture, 'to_rgba'):
        raise TypeError(
            f'draw_image() takes an xnano.Image or a picture from xnano.image, but got '
            f'{image!r}. Load one with xnano.from_image(path) first.'
        )
    self.draw_color_bytes(
        picture.to_rgba(frame_index),
        width=picture.width,
        height=picture.height,
        x=x,
        y=y,
        mode=mode,
    )

def cell_for_pixel(self, x: int, y: int) -> tuple[int, int]:
    """
    Return the cell that holds a pixel or dot.

    Args:
        x: The pixel or dot column.
        y: The pixel or dot row.
    """
    if self._resolution == 'cells':
        return (x, y)
    return self._pixel_view().cell_at(x, y)

def pixel_for_cell(
    self, x: int, y: int, *, anchor: PixelAnchor = 'center'
) -> tuple[int, int]:
    """
    Return the pixel or dot at an anchor of a cell.

    The mouse reports cells; this picks one pixel of the cell the pointer is over.

    Args:
        x: The cell column.
        y: The cell row.
        anchor: Which pixel of the cell to return.
    """
    if self._resolution == 'cells':
        return (x, y)
    return self._pixel_view().pixel_at(x, y, anchor=anchor)

def copy(self) -> Region:
    """Return a standalone region with a copy of these cells and, for one, its look."""
    copy = Region(_snapshot(self._surface()), is_standalone=True)
    if self._is_standalone and self._appearance is not None:
        import dataclasses

        copy._appearance = dataclasses.replace(
            self._appearance, sides=dict(self._appearance.sides)
        )
        copy._is_text = self._is_text
        copy._insets_applied = self._insets_applied
    return copy

def render(self, *, format: Literal['text', 'ansi'] = 'text') -> str:
    """
    Draw the region to a string.

    Args:
        format: ``'text'`` for the characters only, ``'ansi'`` with colors and styles.

    Examples:
        ```python
        import xnano

        assert xnano.write('hi', padding=1).render().splitlines() == ['', ' hi']
        ```
    """
    return _snapshot(self._surface()).render(format=format)

def __str__(self) -> str:
    """Return the characters of the region, so ``print(region)`` shows it."""
    return self.render()

def __xnano_render__(self, context: Context | None = None) -> _core.Buffer:
    """Return the buffer that shows the region: its own, or a copy for a view."""
    if self._is_standalone:
        self._flush_look()
        return self._buffer
    return _snapshot(self._surface())

def __setattr__(self, name: str, value: object) -> None:
    """Set an attribute, or raise ``AttributeError`` for an unknown public name."""
    if (
        name[:1] != '_'
        and self.__dict__.get('_is_sealed')
        and not hasattr(type(self), name)
        and name not in self.__dict__
    ):
        kind = type(self).__name__
        settable = sorted(
            key
            for key in dir(type(self))
            if key[:1] != '_' and _is_settable(type(self), key)
        )
        close = difflib.get_close_matches(name, settable, n=1)
        hint = f' Did you mean {close[0]!r}?' if close else ''
        raise AttributeError(
            f'{kind} has no attribute called {name!r}, so assigning to it would change '
            f'nothing.{hint} The attributes you can assign are: {", ".join(settable)}.'
        )
    object.__setattr__(self, name, value)