xnano.pixel

One cell (or one dot, at half-block and braille resolution) of a region.

The first argument is a preset name such as 'diamond', the name of a registered symbol, or a single character that is drawn as it is. A pixel is a value: it compares by its fields, and region[x, y] returns one and accepts one.

Parameters:

• preset_or_character (PixelPreset | str, default: 'block' ) –

  A PixelPreset, the name of a registered symbol, or one character.

• foreground (ColorValue | None, default: None ) –

  The color of the character.

• background (ColorValue | None, default: None ) –

  The color behind the character.

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

  A name to register this pixel under, so that Pixel('wall') finds it later. The name takes two characters or more; see register.

Attributes:

• character (str) –

  The glyph drawn in the cell or dot.

• foreground (ColorValue | None) –

  The color of the glyph, or None for the cell's own.

• background (ColorValue | None) –

  The color behind the glyph, or None for the cell's own.

• symbol (str | None) –

  The registered symbol name, or None.

Raises:

• ValueError –

  The name is not a preset or a registered symbol (the message lists both and the closest names first), or the character is empty.

Examples:

import xnano
from xnano import Pixel

diamond = Pixel('diamond', foreground='red')
assert diamond.character == '◆'
assert Pixel('x').character == 'x'

with xnano.new(width=4, height=1) as canvas:
    canvas.region[1, 0] = diamond
    assert canvas.region[1, 0].character == '◆'

Make a pixel from a preset, a symbol name or a character.

Parameters:

• preset_or_character (PixelPreset | str, default: 'block' ) –

  A preset name, a registered symbol name or one character.

• foreground (ColorValue | None, default: None ) –

  The color of the character.

• background (ColorValue | None, default: None ) –

  The color behind the character.

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

  A name to register this pixel under.

Methods:

• cell –

  Return the core cell that draws this pixel.

• __str__ –

  Return the character of the pixel, so print(pixel) shows what it draws.

• __xnano_render__ –

  Return a buffer of one cell that shows the pixel.

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

def __init__(
    self,
    preset_or_character: PixelPreset | str = 'block',
    *,
    foreground: ColorValue | None = None,
    background: ColorValue | None = None,
    symbol: str | None = None,
) -> None:
    """
    Make a pixel from a preset, a symbol name or a character.

    Args:
        preset_or_character: A preset name, a registered symbol name or one character.
        foreground: The color of the character.
        background: The color behind the character.
        symbol: A name to register this pixel under.
    """
    if not isinstance(preset_or_character, str) or not preset_or_character:
        raise ValueError(
            f'A pixel is made from a preset name, a symbol name or one character, but '
            f'got {preset_or_character!r}. Try Pixel("block") or Pixel("#").'
        )
    for color_name, color in (('foreground', foreground), ('background', background)):
        if color is None:
            continue
        try:
            if color_name == 'foreground':
                _core.Cell(' ', foreground=color)
            else:
                _core.Cell(' ', background=color)
        except (TypeError, ValueError) as error:
            raise type(error)(
                f'The {color_name} of a pixel must be a color, but was {color!r}. Use a '
                f'name such as "red", a hex string such as "#ff8800", an (r, g, b) '
                f'tuple or a Color.'
            ) from error
    name = preset_or_character
    known_symbol: str | None = None
    if len(name) == 1:
        if unicodedata.category(name) == 'Cc':
            raise ValueError(
                f'A pixel cannot be the control character {name!r}, because a cell '
                f'cannot hold one. Pass a printable character such as Pixel("#"), or a '
                f'preset such as Pixel("block").'
            )
        character = name
    elif name in _PRESET_CHARACTERS:
        character = _PRESET_CHARACTERS[name]
    elif name in symbols.names(kind=Pixel):
        registered = symbols.lookup(name, kind=Pixel)
        character = registered.character
        foreground = registered.foreground if foreground is None else foreground
        background = registered.background if background is None else background
        known_symbol = name
    else:
        raise _unknown_name_error(name)
    object.__setattr__(self, 'character', character)
    object.__setattr__(self, 'foreground', foreground)
    object.__setattr__(self, 'background', background)
    object.__setattr__(self, 'symbol', symbol if symbol is not None else known_symbol)
    object.__setattr__(self, '_cell', None)
    if symbol is not None:
        symbols.register(symbol, self)

character: str

foreground: ColorValue | None

background: ColorValue | None

symbol: str | None

cell() -> Cell

238
239
240
241
242
243
244
245
246
247
248
249
250
251
252

def cell(self) -> _core.Cell:
    """
    Return the core cell that draws this pixel.

    The cell is built once and kept, so writing the same pixel many times is cheap.
    """
    built = self._cell
    if built is None:
        built = _core.Cell(
            self.character,
            foreground=self.foreground,
            background=self.background,
        )
        object.__setattr__(self, '_cell', built)
    return built

__str__() -> str

254
255
256

def __str__(self) -> str:
    """Return the character of the pixel, so ``print(pixel)`` shows what it draws."""
    return self.character

__xnano_render__(context: Context | None = None) -> Buffer

258
259
260
261
262

def __xnano_render__(self, context: Context | None = None) -> _core.Buffer:
    """Return a buffer of one cell that shows the pixel."""
    buffer = _core.Buffer(width=1, height=1)
    buffer[0, 0] = self.cell()
    return buffer