xnano

xnano ¶

xnano

An extremely nano python terminal experience; built on ratatui.

Referenced by:

API Reference xnano_core xnano_core

Modules:

appearance –

xnano.appearance
art –

xnano.art
audio –

xnano.audio
buffers –

xnano.buffers
canvas –

xnano.canvas
components –

xnano.components
context –

xnano.context
cursor –

xnano.cursor
demo –

xnano.demo
effects –

xnano.effects
errors –

xnano.errors
events –

xnano.events
expressions –

xnano.expressions
geometry –

xnano.geometry
image –

xnano.image
input –

xnano.input
music –

xnano.music
operations –

xnano.operations
output –

xnano.output
pixel –

xnano.pixel
placement –

xnano.placement
region –

xnano.region
state –

xnano.state
styles –

xnano.styles
symbols –

xnano.symbols
terminal –

xnano.terminal
time –

xnano.time
types –

xnano.types
widgets –

xnano.widgets

Classes:

Audio –

A sound you can play with Canvas.play or
Image –

An image and how it is shown: what Canvas.write takes
Canvas –

A workspace of text, pixels and sound on a clock, with or without a screen.
Context –

What a hook is called with.
Note –

A note, or a chord, to play: a pitch, how long it lasts and how it sounds.
Pixel –

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

A canvas that draws on your screen and reads your keyboard and mouse.
Color –

A terminal color: a named palette color, a palette index or a true color.

Functions:

from_audio –

Load a sound from a WAV file path or from bytes.
from_image –

Load an image or an animation from a file path or from bytes.
draw –

Build pixel art from text, a picture, bytes or nothing (does not draw).
active –

Return the innermost canvas that is running in this thread or task.
iter –

Iterate over the frames of the active canvas, drawing between them.
new –

Create a canvas: a virtual terminal with a clock, hooks, sound, a cursor and state.
playable –

Turn a function into a component that plays itself.
renderable –

Turn a function into a component that draws itself.
note –

Make a Note: a pitch, or several for a chord, with its length and sound.
play –

Play a note, a sound, a symbol name, a melody or a sequence of those.
hook –

Describe a hook once, to attach to any canvas or placement later.
box –

Build an empty standalone rectangle of cells with a border (does not draw).
write –

Build a standalone region from text (does not draw).
open –

Put a canvas on your screen and return it as a Terminal.

Audio `dataclass` ¶

Audio(source: TerminalSound | PathLike[str] | str | bytes, *, symbol: str | None = None)

A sound you can play with Canvas.play or AudioDevice.play.

Make one from the path of a WAV file, the bytes of one, or a TerminalSound.

Attributes:

sound (TerminalSound) –

The rendered sound.
symbol (str | None) –

The name the sound is registered under in symbols, or None. play('kick') plays the sound registered as 'kick'.

Examples:

import xnano
from xnano_audio import TerminalSound

audio = xnano.Audio(TerminalSound.from_samples([0.0, 0.5, -0.5, 0.0]))
assert audio.sound.sample_rate == 44100

Load a sound.

Parameters:

source (TerminalSound | PathLike[str] | str | bytes) –

The path of a WAV file, the bytes of one, or a sound.
symbol (str | None, default: None ) –

A name to register the sound under in symbols, so play(name) plays it.

Raises:

ImportError –

xnano-audio is not installed. Install it with pip install "xnano[audio]".
TypeError –

source is not a path, bytes or a sound.
FileNotFoundError –

source is a path to a file that does not exist.
ValueError –

The file is not a PCM WAV file that xnano can read, or symbol cannot be a symbol name, or another kind of value already has it.

Referenced by:

API Reference xnano
- xnano from_audio
- xnano.audio audio
  - PlaySource
  - AudioDevice play
- xnano.types types
  - PlaySource
  - Playable

Returned by:

API Reference xnano xnano from_audio

Source code in xnano/_media.py

def __init__(
    self,
    source: TerminalSound | os.PathLike[str] | str | bytes,
    *,
    symbol: str | None = None,
) -> None:
    """
    Load a sound.

    Args:
        source: The path of a WAV file, the bytes of one, or a sound.
        symbol: A name to register the sound under in [`symbols`][xnano.symbols], so
            ``play(name)`` plays it.

    Raises:
        ImportError: ``xnano-audio`` is not installed. Install it with
            ``pip install "xnano[audio]"``.
        TypeError: ``source`` is not a path, bytes or a sound.
        FileNotFoundError: ``source`` is a path to a file that does not exist.
        ValueError: The file is not a PCM WAV file that xnano can read, or ``symbol`` cannot
            be a symbol name, or another kind of value already has it.
    """
    module = require('audio', needed_for='xnano.Audio')
    if isinstance(source, module.TerminalSound):
        sound = source
    elif isinstance(source, bytes):
        sound = _decode_wave(module, source)
    elif isinstance(source, (str, os.PathLike)):
        path = pathlib.Path(source)
        if not path.is_file():
            raise FileNotFoundError(
                f'Audio could not load {str(path)!r}, because no WAV file exists '
                f'there. Check the path, or pass the bytes of the sound.'
            )
        sound = _decode_wave(module, path.read_bytes())
    else:
        raise TypeError(
            f'Audio needs the path of a WAV file, the bytes of one or a sound, but got '
            f'{type(source).__name__}. Pass Audio("sound.wav").'
        )
    object.__setattr__(self, 'sound', sound)
    object.__setattr__(self, 'symbol', symbol)
    if symbol is not None:
        symbols.register(symbol, self)

Image `dataclass` ¶

Image(source: TerminalImage | 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)

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.

Referenced by:

API Reference xnano
- xnano
  - Canvas write
  - Terminal write
  - draw
  - from_image
- xnano.art art draw
- xnano.canvas canvas Canvas write
- xnano.region region Region draw_image
- xnano.terminal terminal Terminal write
- xnano.types types Renderable

Returned by:

API Reference xnano xnano from_image

Used by:

API Reference xnano
- xnano draw
- xnano.art art
  - Art replace
  - draw
- xnano.region region Region draw_image

Source code in xnano/_media.py

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)

Canvas ¶

Canvas(*, width: int | str | None, height: int | str | None, fps: float, bpm: float, is_realtime: bool, deps: object, state: object, title: str | None, gates: Mapping[str, object], appearance: Mapping[str, object], effects: Sequence[RenderableEffectSpecification], enclosing: Canvas[object, object] | None = None, layout: CanvasLayout = 'overlay', edges: EdgeBehavior = 'clip')

Bases: _Hooked[DepsT, StateT], _TextModifiers, Generic[DepsT, StateT]

A workspace of text, pixels and sound on a clock, with or without a screen.

A canvas is a virtual terminal. Create one with new: it has a size, a clock, hooks, a cursor, sound and state, and no screen, so it draws into memory and its time moves only when you move it with step or iter, which makes every run the same. new(realtime=True) runs it on the wall clock instead, on a thread of its own. open puts the same object on your screen, where it becomes a Terminal and its time continues from where it was. It is not the drawing widget xnano.widgets.Canvas.

How a canvas ends depends on who moves its clock. On a canvas from new(), quit only ends a running iter(): the canvas stays open for writing and rendering. On a canvas that runs by itself (realtime=True, or opened on the screen) its loop ends with quit(), Ctrl-C or a quit key of run, and that closes the canvas. close (or leaving the with block) always closes it. The three states are:

State	Read it from	Meaning
running	`is_running`	open, and its loop has not been asked to end
time stopped	`time.is_stopped`	frozen by `stop()`; it still draws and hears input
closed	`is_closed`	torn down; it cannot draw or listen

What you put on the canvas is declared on the canvas itself: write, hook and indexing. Everything else is grouped by what it is: canvas.time is the Time, canvas.cursor the one Cursor, canvas.output the Output of drawn frames and canvas.audio the AudioDevice.

Any thread may write, remove, draw and play. Hooks run on the canvas's loop, so keep them short.

Attributes:

is_closed (bool) –

Whether the canvas has been torn down.
is_running (bool) –

Whether the canvas is open and its loop has not been asked to end.
core_buffer (Buffer) –

The core buffer everything is added to, as large as the canvas.
parent (ParentExpressionScope) –

Symbolic expressions for the parent container's width, height and size.
root (RootExpressionScope) –

Symbolic expressions for the root canvas's geometry and clock.
size (Size) –

The size of the canvas in cells.
width (int) –

The width of the canvas in cells.
height (int) –

The height of the canvas in cells.
x (int) –

The column of the canvas, which is 0 for a canvas that is not written into another.
y (int) –

The row of the canvas, which is 0 for a canvas that is not written into another.
title (str | None) –

The window title; None clears it.
fps (float) –

The most frames drawn per second.
bpm (float) –

Beats per minute for beat timers, notes and melodies.
deps (DepsT) –

The dependencies given to new(deps=...), which hooks read.
time (Time) –

The Time everything on the canvas runs on.
cursor (Cursor) –

The canvas's one cursor.
state –

The dataclass given to new(state=...).
output (Output) –

The Output: what was drawn, and held-back text.
audio (AudioDevice) –

The AudioDevice: notes, melodies, sounds and the microphone.
input (Input) –

The keys held down right now, for programs that poll instead of listening.

Examples:

import xnano

with xnano.new(width=12, height=2, fps=10) as canvas:
    greeting = canvas.write('hello', x=1, y=1)
    for frame in canvas.iter(count=3):
        greeting.text = f'frame {frame.index}'
    assert canvas.render().splitlines()[1] == ' frame 2'
    assert round(canvas.time.elapsed, 3) == 0.3

Create a canvas. Use new instead of calling this.

Parameters:

width (int | str | None) –

The width in cells or as a percentage of the window, or None for 80.
height (int | str | None) –

The height in cells or as a percentage of the window, or None for 24.
fps (float) –

The most frames drawn per second.
bpm (float) –

Beats per minute.
is_realtime (bool) –

Whether the canvas runs on the wall clock, on a thread of its own.
deps (object) –

The dependencies, or the unset marker when none were given.
state (object) –

A dataclass instance the canvas keeps and validates, or the unset marker.
title (str | None) –

The window title, or None.
gates (Mapping[str, object]) –

The input gates that were given, by name.
appearance (Mapping[str, object]) –

The appearance keywords of the canvas itself, by name.
effects (Sequence[RenderableEffectSpecification]) –

Effects to apply to the canvas, as dictionaries with a kind key.
enclosing (Canvas[object, object] | None, default: None ) –

The canvas whose with block this one was created in, which its sizes are measured in and which closes it, or None.
layout (CanvasLayout, default: 'overlay' ) –

How the canvas places what is written on it.
edges (EdgeBehavior, default: 'clip' ) –

What content written on the canvas does at the edges of its area.

Referenced by:

Returned by:

API Reference xnano
- xnano
  - Canvas new
  - Context
    - buffer
    - canvas
    - parent
    - root
  - Terminal new
  - active
  - new
- xnano.canvas canvas
  - Canvas new
  - active
  - new
- xnano.context context
  - Context
    - buffer
    - canvas
    - parent
    - root
  - Frame canvas
  - Update canvas
- xnano.placement placement Placement canvas
- xnano.terminal terminal Terminal new

Subclassed by:

API Reference xnano
- xnano Terminal
- xnano.terminal terminal Terminal

Used by:

API Reference xnano
- xnano
  - Canvas write
  - Context
  - Terminal write
  - new
  - open
- xnano.audio audio AudioDevice
- xnano.canvas canvas
  - Canvas write
  - new
- xnano.context context
  - Context
  - Frame
  - Update
- xnano.cursor cursor Cursor
- xnano.input input
- xnano.operations operations
  - ContextualOperation apply_to
  - Customization apply_to
- xnano.output output Output
- xnano.placement placement Placement write
- xnano.region region Region
- xnano.state state StateNamespace
- xnano.terminal terminal
  - Terminal write
  - open
- xnano.time time Time
- xnano.types types RenderableEffects

Methods:

__setattr__ –

Set an attribute, or raise AttributeError for an unknown public name.
bold –

Make the text bold, or undo it with False; the same as setting is_bold.
dim –

Dim the text, or undo it with False; the same as setting is_dim.
italic –

Make the text italic, or undo it with False; the same as setting is_italic.
underline –

Underline the text, or undo it with False; the same as setting is_underlined.
blink –

Make the text blink, or undo it with False; the same as setting is_blinking.
reverse –

Swap the foreground and background, or undo it with False; the same as setting is_reversed.
hidden –

Hide the text, or undo it with False; the same as setting is_hidden.
crossed_out –

Strike the text through, or undo it with False; the same as setting is_crossed_out.
hook –

Call a function when something happens on this canvas or placement.
__new__ –

Refuse a direct call: a canvas is created with xnano.new.
open –

Put this canvas on your screen, and return it as a Terminal.
close –

Release everything the canvas holds, and give the screen back if it has one.
local –

Convert a cell of the screen into a cell of this canvas.
move –

Move a canvas that is written into another one by a number of cells along each axis.
up –

Move a written canvas up by count rows; see move.
down –

Move a written canvas down by count rows; see move.
left –

Move a written canvas left by count columns; see move.
right –

Move a written canvas right by count columns; see move.
new –

Create a canvas inside this one and draw it here at once, at the top-left corner.
write –

Put something on the canvas: text, a widget, a buffer, another canvas or an image.
clear –

Erase everything written or drawn directly on the canvas's cells.
update –

Change the canvas's own cells with operations, styles or effects.
__or__ –

Apply an operation, customization or style with canvas | operation.
__ior__ –

Apply an operation, customization or style in place with canvas |= operation.
inspect –

Evaluate an expression against the canvas and return its value.
iter –

Iterate over the canvas's frames, drawing between them; pass count= or seconds=,
step –

Move time by delta_seconds, one frame by default, and draw exactly one frame.
deliver_events –

Deliver pushed events to their hooks and draw a frame, without moving time.
stop –

Freeze time: the same as Time.stop.
resume –

Let time run on from where stop froze it.
quit –

Ask the canvas's loop to end.
run –

Wait until the canvas's loop ends.
wait_for_key –

Wait until a key is pressed, and return its name.
prompt –

Prompt for a line of text, and return what was typed.
render –

Draw the current frame and return it, without a screen.
push –

Deliver an event to the canvas as if it had been typed, clicked or reported.
play –

Play a note, a sound, a symbol name, a melody or a sequence of those, and return at once.
state_reference –

A core reference for one field of the canvas's state.

Source code in xnano/canvas.py

def __init__(
    self,
    *,
    width: int | str | None,
    height: int | str | None,
    fps: float,
    bpm: float,
    is_realtime: bool,
    deps: object,
    state: object,
    title: str | None,
    gates: Mapping[str, object],
    appearance: Mapping[str, object],
    effects: Sequence[RenderableEffectSpecification],
    enclosing: Canvas[object, object] | None = None,
    layout: CanvasLayout = 'overlay',
    edges: EdgeBehavior = 'clip',
) -> None:
    """
    Create a canvas. Use [`new`][xnano.new] instead of calling this.

    Args:
        width: The width in cells or as a percentage of the window, or ``None`` for 80.
        height: The height in cells or as a percentage of the window, or ``None`` for 24.
        fps: The most frames drawn per second.
        bpm: Beats per minute.
        is_realtime: Whether the canvas runs on the wall clock, on a thread of its own.
        deps: The dependencies, or the unset marker when none were given.
        state: A dataclass instance the canvas keeps and validates, or the unset marker.
        title: The window title, or ``None``.
        gates: The input gates that were given, by name.
        appearance: The appearance keywords of the canvas itself, by name.
        effects: Effects to apply to the canvas, as dictionaries with a ``kind`` key.
        enclosing: The canvas whose ``with`` block this one was created in, which its
            sizes are measured in and which closes it, or ``None``.
        layout: How the canvas places what is written on it.
        edges: What content written on the canvas does at the edges of its area.
    """
    super().__init__()
    self._canvas = self
    self._root_canvas = self
    self._lock = threading.RLock()
    self._root = _core.Buffer()
    self._buffer = self._root
    self._fps = fps
    self._bpm = bpm
    self._is_realtime = is_realtime
    self._requested_width = width
    self._requested_height = height
    self._deps_given = deps is not _UNSET
    self._deps = cast('DepsT', None if deps is _UNSET else deps)
    self._state_given = state is not _UNSET
    self._title = title
    self._gates: dict[str, object] = dict(gates)
    self._resolved_gates: dict[str, object] = {}
    self._appearance = (
        Appearance(**cast('dict[str, object]', _plain_appearance(appearance)))  # type: ignore[arg-type]
        if appearance
        else None
    )
    self._decorated: Decorated | None = None
    self._dirty_looks: dict[int, _Looked] = {}
    self._placements: list[Placement[DepsT, StateT]] = []
    self._ledger: list[_Registration] = []
    self._effects: list[
        tuple[Customization, Canvas[object, object] | Placement[object, object]]
    ] = []
    self._frame_listeners: dict[int, Callable[[FrameContext], None]] = {}
    self._frame_listener_tokens = itertools.count()
    self._frame_demand = 0
    self._frame_registration: _Registration | None = None
    self._size_hook: _core.Hook | None = None
    self._parent_placement: Placement[object, object] | None = None
    self._children: list[Canvas[object, object]] = []
    self._enclosing: weakref.ref[Canvas[object, object]] | None = None
    self._enclosing_size: tuple[int, int] | None = None
    self._nested_canvases: list[weakref.ref[Canvas[object, object]]] = []
    self._areas: dict[int, Placement[object, object]] = {}
    self._is_hidden_until_written = False
    self._layout: CanvasLayout = layout
    self._edges: EdgeBehavior = edges
    self._slots: list[
        tuple[Placement[object, object] | None, _core.Buffer, _core.SizeRule]
    ] = []
    self._is_layout_pending = False
    self._pending_layouts: dict[int, Canvas[object, object]] = {}
    if enclosing is not None:
        self._enclosing = weakref.ref(enclosing)
        self._enclosing_size = (enclosing.width, enclosing.height)
        with enclosing._lock:
            enclosing._nested_canvases.append(
                weakref.ref(cast('Canvas[object, object]', self))
            )
    self._is_closed = False
    self._is_finalized = False
    self._stop_requested = threading.Event()
    self._failure: BaseException | None = None
    self._is_failure_reported = False
    self._failure_report = ''
    self._moved = 0
    self._carried: dict[str, object] | None = None
    self._cursor_follow: tuple[_core.Buffer, int, int] | None = None
    self._state_namespace: StateNamespace | None = None
    self._state_fields: dict[str, object] = {}
    self._state_store: _core.TerminalStateStore | None = None
    if state is not _UNSET and state is not None:
        self._state_store = _prepare_state(cast('DataclassInstance', state))
        self._state_fields = _state_field_types(cast('DataclassInstance', state))
    self._state_followers: _StateFollowers | None = None
    self._state_subscription: _core.TerminalStateSubscription | None = None
    self._state_hook: _core.Hook | None = None
    self._state_marked: dict[_StateFollower, _core.TerminalStateChange] = {}
    self._internal_revisions: deque[int] = deque(maxlen=16)
    self._namespace_identifiers = itertools.count(1)
    self._active_run_by_thread = threading.local()
    self._images: dict[int, ImageSource] = {}
    # Only placements with a formula or a range need looking at before each frame.
    self._dynamic: dict[int, Placement[DepsT, StateT]] = {}
    self._time = Time(cast('Canvas[object, object]', self))
    self._cursor_view = Cursor(cast('Canvas[object, object]', self))
    self.output = Output(cast('Canvas[object, object]', self))
    self._audio: AudioDevice | None = None
    self._input: Input | None = None
    self._runtime_object: _core.Runtime | None = None
    self._clock: _core.Clock | None = None
    self._cursor: _core.Cursor | None = None
    self._input_state: _core.InputState | None = None
    self._pushed_pointer: tuple[tuple[int, int], object, int] | None = None
    self._size = _core.Size(0, 0)
    self._previous_chain = tuple(
        reference for reference in _active_canvas.get() if reference() is not None
    )
    _active_canvas.set(
        (weakref.ref(cast('Canvas[object, object]', self)), *self._previous_chain)
    )
    self._host: _Host
    columns, rows = _canvas_size(width, height, self._enclosing_size)
    interval_milliseconds = max(1, round(1000.0 / fps))

    def create_runtime() -> _core.Runtime:
        runtime = _core.Runtime.offscreen(
            width=columns,
            height=rows,
            frame_interval_milliseconds=interval_milliseconds,
            clock=_core.Clock.monotonic() if is_realtime else None,
        )
        if title is not None:
            runtime.title = title
        return runtime

    try:
        if is_realtime:
            _ThreadHost(cast('Canvas[object, object]', self), create_runtime)
        else:
            _InlineHost(cast('Canvas[object, object]', self), create_runtime)
    except BaseException:
        _active_canvas.set(self._previous_chain)
        self._finalize()
        raise
    try:
        if effects:
            apply_effects(cast('Canvas[object, object]', self), effects)
    except BaseException:
        self.close(raise_failure=False)
        raise
    self._renderable_effects = RenderableEffects(cast('Canvas[object, object]', self))
    self._seal()

color `property` ¶

color: Colors

The colors: color.fg for the text and color.bg for what is behind it.

Each is a ColorSlot. Assign a color name, an (red, green, blue) tuple, a Color or another slot; 'reset' clears the color.

Examples:

import xnano

with xnano.new(width=10, height=3) as canvas:
    label = canvas.write('hi')
    label.color.fg = 'red'
    label.color.bg = (0, 0, 80)
    label.color.bg.lighten(0.1)
    assert label.color.fg.value == xnano.Color('red')

border `property` `writable` ¶

border: BorderAppearance

The border: its kind, a setting for each side, its color and its title.

Assign 'plain', 'rounded', 'double' or 'thick' to draw a border on every side, True for 'plain' and False to remove it. It works on any content, not only on text.

The border, padding and margin are drawn around the content, so the placement grows by the cells they take. A widget with no size of its own is shrunk to fit its parent, border included.

Examples:

import xnano

with xnano.new(width=12, height=5) as canvas:
    card = canvas.write('hi', border='rounded')
    card.border.top = 'double'
    card.border.left = False
    card.border.color = 'cyan'
    card.border = False
    assert not card.border

padding `property` `writable` ¶

padding: PaddingAppearance

The space between the border and the content, edge by edge.

Assign a number of cells, a percentage such as '10%' or a dictionary such as {'vertical': 1, 'horizontal': 2}, or set one edge with padding.left = 2.

margin `property` `writable` ¶

margin: MarginAppearance

The transparent space outside the border, edge by edge, set like padding.

is_bold `property` `writable` ¶

is_bold: bool

Whether the text is bold.

is_dim `property` `writable` ¶

is_dim: bool

Whether the text is dimmed.

is_italic `property` `writable` ¶

is_italic: bool

Whether the text is italic.

is_underlined `property` `writable` ¶

is_underlined: bool

Whether the text is underlined.

is_blinking `property` `writable` ¶

is_blinking: bool

Whether the text blinks.

is_reversed `property` `writable` ¶

is_reversed: bool

Whether foreground and background are swapped.

is_hidden `property` `writable` ¶

is_hidden: bool

Whether the text is hidden.

is_crossed_out `property` `writable` ¶

is_crossed_out: bool

Whether the text is struck through.

output `instance-attribute` ¶

output: Output = Output(cast('Canvas[object, object]', self))

The canvas's drawn frames and captured text.

is_closed `property` ¶

is_closed: bool

Whether the canvas has been torn down: closed, or its loop has ended.

is_running `property` ¶

is_running: bool

Whether the canvas is open and its loop has not been asked to end.

core_buffer `property` ¶

core_buffer: Buffer

The core buffer the canvas draws, as large as the canvas.

Everything you write is a child of this buffer, and everything drawn directly on the canvas is stored in it. A canvas with a border, padding or margin draws them around a buffer of its own; this is the buffer inside them.

parent `property` ¶

parent: ParentExpressionScope

Symbolic expressions for the parent container's width, height and size.

root `property` ¶

root: RootExpressionScope

Symbolic expressions for the root canvas's width, height, size and time.

size `property` ¶

size: Size

The size of the canvas in cells.

width `property` ¶

width: int

The width of the canvas in cells.

height `property` ¶

height: int

The height of the canvas in cells.

x `property` ¶

x: int

The column of the canvas: 0, unless it was written into another canvas.

y `property` ¶

y: int

The row of the canvas: 0, unless it was written into another canvas.

fps `property` ¶

fps: float

The most frames drawn per second, and the rate iter aims for.

Referenced by:

API Reference xnano xnano.time time Time

bpm `property` `writable` ¶

bpm: float

Beats per minute: the length of a beat for beat timers, notes and melodies.

It is 120 unless new(bpm=...) said otherwise, and it can change while things are playing; the change applies from the next beat.

Raises:

ValueError –

The tempo is not above 0 and at most 600000.

Referenced by:

API Reference xnano xnano.audio audio AudioDevice

deps `property` ¶

deps: DepsT

The dependencies given to new(deps=...), or None. Hooks read them.

title `property` `writable` ¶

title: str | None

The window title last set on this canvas.

Assign a single line of printable text to set the title of the window a canvas on the screen draws in, or None to clear it. A canvas without a screen keeps the value and shows it when it is opened.

time `property` ¶

time: Time

The canvas's Time: how long it has run, stopping, and formulas.

Referenced by:

API Reference xnano xnano.time time Time

cursor `property` ¶

cursor: Cursor

The canvas's Cursor.

A canvas has exactly one cursor. Set its position (a cell, or None to hide it), shape, is_blinking and is_visible, move it with up, down, left, right and move, or follow a placement. It can be changed from any thread, and on the screen the cursor you had before is restored when the canvas closes.

Examples:

import xnano

with xnano.new(width=10, height=2) as canvas:
    canvas.cursor.position = (3, 0)
    canvas.cursor.shape = 'bar'
    assert canvas.cursor.position.x == 3

Referenced by:

API Reference xnano xnano.cursor cursor Cursor

region `property` ¶

region: Region

The cells of the canvas as a Region: read and write canvas.region[x, y].

The default resolution is one cell. canvas.region.half_blocks addresses two pixels per cell and canvas.region.braille eight dots.

Examples:

import xnano

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

layout `property` ¶

layout: CanvasLayout

How the canvas places what is written on it, chosen when the canvas is created.

'overlay' places every piece on its own over the whole canvas. 'column' stacks the pieces from top to bottom in the order they are written, and 'row' from left to right. Each piece then takes a slot: one with a size on the stacking axis (height in a column, width in a row, in cells or as a percentage) gets exactly that, and the others share what is left equally. Inside its slot a piece is positioned as on any canvas, so y='center' and y='50%' are measured in the slot. Removing a piece gives its slot back. A canvas created inside the with block of a stacking canvas takes a slot only once it is written.

Examples:

import xnano

with xnano.new(width=20, height=10, layout='column') as terminal:
    terminal.write('top half', y='center')
    panel = terminal.new(height='50%')
    panel.write('bottom half')
    rows = terminal.render().splitlines()
    assert (rows[2], rows[5]) == ('top half', 'bottom half')

edges `property` `writable` ¶

edges: EdgeBehavior

What content written on the canvas does at the edges of its area, unless given its own.

'clip' lets it move past the edge, where it is not drawn; 'stop' holds it inside its area when it moves; 'wrap' continues text on the next rows of its area. A piece written with edges=... keeps its own; see Placement.edges.

Raises:

ValueError –

The value is not 'clip', 'stop' or 'wrap'.

audio `property` ¶

audio: AudioDevice

The canvas's AudioDevice: notes, melodies, sounds and the microphone.

It needs the optional xnano-audio package, which is imported the first time this is read.

Raises:

ImportError –

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

Referenced by:

API Reference xnano xnano.audio audio AudioDevice

fx `property` ¶

fx: RenderableEffects

The visual effects of the canvas itself, one method for each effect.

canvas.fx.fade_to(background='navy') starts a fade over the whole canvas at once, and canvas.fx.clear() stops what was started here. A placement has its own fx, and the sound effects of what the canvas plays are canvas.audio.fx. See RenderableEffects.

Examples:

import xnano

with xnano.new('hello', width=8, height=1) as canvas:
    canvas.fx.dissolve(duration_milliseconds=300)
    assert len(canvas.fx.active) == 1

Referenced by:

API Reference xnano xnano.types types RenderableEffects

input `property` ¶

input: Input

The keys held down right now, for programs that poll instead of listening.

Read it anywhere, from any thread. A canvas opened with keyboard='release_events' knows exactly when a key is let go.

Referenced by:

API Reference xnano xnano.input input Input

state `class-attribute` `instance-attribute` ¶

state = _StateAccessor()

The canvas's state: values that hooks and your code share, read and written by path.

canvas.state.get('player.score') reads a value and canvas.state.push('player.score', 3) writes one; see StateNamespace for the path rules. A canvas created with new(state=Settings()) also gives the fields of the dataclass as attributes with their declared types, so canvas.state.volume is an int for a field declared volume: int; a write is checked against the field's type. A type checker sees get and push only on a canvas without a state dataclass, but both exist on every canvas.

The state can be used from any thread. A write updates every expression that reads the field and draws a frame.

Referenced by:

API Reference xnano xnano.placement placement Placement state

setattr ¶

__setattr__(name: str, value: object) -> None

Set an attribute, or raise AttributeError for an unknown public name.

Source code in xnano/_attributes.py

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)

bold ¶

bold(value: bool = True) -> Self

Make the text bold, or undo it with False; the same as setting is_bold.

Parameters:

value (bool, default: True ) –

Whether the text is bold.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Examples:

import xnano

with xnano.new(width=12, height=1) as canvas:
    title = canvas.write('Ready').bold().underline()
    assert title.is_bold and title.is_underlined
    title.bold(False)
    assert not title.is_bold

Source code in xnano/appearance.py

def bold(self, value: bool = True) -> Self:
    """
    Make the text bold, or undo it with ``False``; the same as setting ``is_bold``.

    Args:
        value: Whether the text is bold.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.

    Examples:
        ```python
        import xnano

        with xnano.new(width=12, height=1) as canvas:
            title = canvas.write('Ready').bold().underline()
            assert title.is_bold and title.is_underlined
            title.bold(False)
            assert not title.is_bold
        ```
    """
    self.is_bold = value
    return self

dim ¶

dim(value: bool = True) -> Self

Dim the text, or undo it with False; the same as setting is_dim.

Parameters:

value (bool, default: True ) –

Whether the text is dimmed.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def dim(self, value: bool = True) -> Self:
    """
    Dim the text, or undo it with ``False``; the same as setting ``is_dim``.

    Args:
        value: Whether the text is dimmed.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_dim = value
    return self

italic ¶

italic(value: bool = True) -> Self

Make the text italic, or undo it with False; the same as setting is_italic.

Parameters:

value (bool, default: True ) –

Whether the text is italic.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def italic(self, value: bool = True) -> Self:
    """
    Make the text italic, or undo it with ``False``; the same as setting ``is_italic``.

    Args:
        value: Whether the text is italic.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_italic = value
    return self

underline ¶

underline(value: bool = True) -> Self

Underline the text, or undo it with False; the same as setting is_underlined.

Parameters:

value (bool, default: True ) –

Whether the text is underlined.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def underline(self, value: bool = True) -> Self:
    """
    Underline the text, or undo it with ``False``; the same as setting ``is_underlined``.

    Args:
        value: Whether the text is underlined.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_underlined = value
    return self

blink ¶

blink(value: bool = True) -> Self

Make the text blink, or undo it with False; the same as setting is_blinking.

Parameters:

value (bool, default: True ) –

Whether the text blinks.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def blink(self, value: bool = True) -> Self:
    """
    Make the text blink, or undo it with ``False``; the same as setting ``is_blinking``.

    Args:
        value: Whether the text blinks.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_blinking = value
    return self

reverse ¶

reverse(value: bool = True) -> Self

Swap the foreground and background, or undo it with False; the same as setting is_reversed.

Parameters:

value (bool, default: True ) –

Whether foreground and background are swapped.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def reverse(self, value: bool = True) -> Self:
    """
    Swap the foreground and background, or undo it with ``False``; the same as setting ``is_reversed``.

    Args:
        value: Whether foreground and background are swapped.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_reversed = value
    return self

hidden ¶

hidden(value: bool = True) -> Self

Hide the text, or undo it with False; the same as setting is_hidden.

Parameters:

value (bool, default: True ) –

Whether the text is hidden.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def hidden(self, value: bool = True) -> Self:
    """
    Hide the text, or undo it with ``False``; the same as setting ``is_hidden``.

    Args:
        value: Whether the text is hidden.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_hidden = value
    return self

crossed_out ¶

crossed_out(value: bool = True) -> Self

Strike the text through, or undo it with False; the same as setting is_crossed_out.

Parameters:

value (bool, default: True ) –

Whether the text is struck through.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def crossed_out(self, value: bool = True) -> Self:
    """
    Strike the text through, or undo it with ``False``; the same as setting ``is_crossed_out``.

    Args:
        value: Whether the text is struck through.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_crossed_out = value
    return self

hook ¶

hook(function: Hook[DepsT, StateT], /, *, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> HookHandle[DepsT, StateT]

hook(*, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]]

hook(function: Hook[DepsT, StateT] | None = None, /, *, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> HookHandle[DepsT, StateT] | Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]]

Call a function when something happens on this canvas or placement.

on says what to listen to. A hook without on hears every input event. A mouse, scroll or drag hook on a placement hears only the pointer inside the placement, and a press inside holds the pointer for the hook until the button is released. A pointer hook that matches an event stops it from reaching the parent; a hook that does not match lets it through. Keys are not consumed: while nothing has focus, every key hook hears a key.

hook(function, ...) attaches one function, and @target.hook(...) decorates the function that follows. A hook function may be a generator that receives a new context at each bare yield: write context = yield. A drag is a loop that runs while context.mouse.is_down.

every and after are seconds for on='tick' and beats for on='beat': every=2 means 2 seconds for a tick hook and 2 beats for a beat hook. On a canvas from new() a hook that is due several times in one step runs once for each interval, up to 100,000 times in one step; the intervals that remain run in the steps that follow. The function's return value is ignored, unless it is an operation, a style or an effect, which is applied to this target.

Parameters:

function (Hook[DepsT, StateT] | None, default: None ) –

The function to call with a Context, or a function with no parameters, which is called without it.
on (HookKind | None, default: None ) –

What to listen to: 'frame', 'tick', 'beat', 'key', 'mouse', 'scroll', 'drag', 'paste', 'focus', 'resize', 'state' or 'custom'. See HookKind.
when (When[DepsT, StateT] | None, default: None ) –

A condition that must hold: an expression, a function of the context, or a string. See When. A string tells xnano which input the hook needs, so the mouse, scroll and key-release gates it reads are turned on when the canvas opens. An expression or a function does not, so a condition that reads Mouse, Scroll or key releases needs the gate set on new() or open() yourself: mouse=True, scroll=True or keyboard='release_events'. A comparison with an input the event does not carry, such as keyboard.key on a paste, does not hold; != is one of them, so keyboard.key != 'q' hears only key events. not and not in negate the whole comparison, so not keyboard.key == 'q' and keyboard.key not in ['q'] also hold for events that have no key.
every (float | None, default: None ) –

Repeat every this many seconds ('tick') or beats ('beat').
after (float | None, default: None ) –

Run once after this many seconds ('tick') or beats ('beat').
keys (KeyName | Sequence[KeyName] | None, default: None ) –

The key or keys an on='key' hook reacts to, such as 'q' or 'ctrl+s'. A key hook with keys hears presses and repeats; omit them and test keyboard.kind to hear releases.
requires_deps (bool, default: False ) –

Whether the hook needs the dependencies given to new(deps=...).

Returns:

HookHandle[DepsT, StateT] | Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]] –

The hook, whose remove stops it; or, without a function, the decorator.

Raises:

ValueError –

The combination of arguments does not make sense, a key name is unknown, or a when string is not a condition. The message says what to write instead.
TypeError –

on is not text, when is a plain bool, or the function is not callable with a context, or is an async function.
TerminalError –

requires_deps is true and the canvas was created without deps, or the canvas is on a screen with an input gate this hook needs turned off.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:
    heard = []

    @canvas.hook(on='key', keys=['q', 'escape'])
    def leave(context: xnano.Context) -> None:
        heard.append(context.keyboard.key)

    @canvas.hook(on='tick', every=0.5)
    def blink(context: xnano.Context) -> None:
        heard.append('tick')

    canvas.push(Event.key_press('q'))
    canvas.step(delta_seconds=1.0)
    assert heard == ['q', 'tick', 'tick']

Referenced by:

Source code in xnano/_hooks.py

def hook(
    self,
    function: Hook[DepsT, StateT] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[DepsT, StateT] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> (
    HookHandle[DepsT, StateT]
    | Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]]
):
    """
    Call a function when something happens on this canvas or placement.

    ``on`` says what to listen to. A hook without ``on`` hears every input event. A mouse,
    scroll or drag hook on a placement hears only the pointer inside the placement, and a
    press inside holds the pointer for the hook until the button is released. A pointer hook
    that matches an event stops it from reaching the parent; a hook that does not match lets
    it through. Keys are not consumed: while nothing has focus, every key hook hears a key.

    ``hook(function, ...)`` attaches one function, and ``@target.hook(...)`` decorates the
    function that follows. A hook function may be a generator that receives a new context
    at each bare ``yield``: write ``context = yield``. A drag is a loop that runs while
    ``context.mouse.is_down``.

    ``every`` and ``after`` are seconds for ``on='tick'`` and beats for ``on='beat'``:
    ``every=2`` means 2 seconds for a tick hook and 2 beats for a beat hook. On a canvas
    from ``new()`` a hook that is due several times in one ``step`` runs once for each
    interval, up to 100,000 times in one step; the intervals that remain run in the steps
    that follow. The function's return value is ignored, unless it is an operation, a
    style or an effect, which is applied to this target.

    Args:
        function: The function to call with a [`Context`][xnano.context.Context], or a
            function with no parameters, which is called without it.
        on: What to listen to: ``'frame'``, ``'tick'``, ``'beat'``, ``'key'``, ``'mouse'``,
            ``'scroll'``, ``'drag'``, ``'paste'``, ``'focus'``, ``'resize'``, ``'state'``
            or ``'custom'``. See [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold: an expression, a function of the context, or a
            string. See [`When`][xnano.types.When]. A string tells xnano which input
            the hook needs, so the mouse, scroll and key-release gates it reads are
            turned on when the canvas opens. An expression or a function does not, so a
            condition that reads ``Mouse``, ``Scroll`` or key releases needs the gate set
            on ``new()`` or ``open()`` yourself: ``mouse=True``, ``scroll=True`` or
            ``keyboard='release_events'``. A comparison with an input the event does not
            carry, such as ``keyboard.key`` on a paste, does not hold; ``!=`` is one of
            them, so ``keyboard.key != 'q'`` hears only key events. ``not`` and ``not in``
            negate the whole comparison, so ``not keyboard.key == 'q'`` and
            ``keyboard.key not in ['q']`` also hold for events that have no key.
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds (``'tick'``) or beats (``'beat'``).
        keys: The key or keys an ``on='key'`` hook reacts to, such as ``'q'`` or
            ``'ctrl+s'``. A key hook with keys hears presses and repeats; omit them and
            test ``keyboard.kind`` to hear releases.
        requires_deps: Whether the hook needs the dependencies given to
            ``new(deps=...)``.

    Returns:
        The hook, whose ``remove`` stops it; or, without a function, the decorator.

    Raises:
        ValueError: The combination of arguments does not make sense, a key name is
            unknown, or a ``when`` string is not a condition. The message says what to
            write instead.
        TypeError: ``on`` is not text, ``when`` is a plain ``bool``, or the function is not callable with a
            context, or is an ``async`` function.
        TerminalError: ``requires_deps`` is true and the canvas was created without
            ``deps``, or the canvas is on a screen with an input gate this hook needs
            turned off.

    Examples:
        ```python
        import xnano
        from xnano_core import Event

        with xnano.new(width=8, height=1) as canvas:
            heard = []

            @canvas.hook(on='key', keys=['q', 'escape'])
            def leave(context: xnano.Context) -> None:
                heard.append(context.keyboard.key)

            @canvas.hook(on='tick', every=0.5)
            def blink(context: xnano.Context) -> None:
                heard.append('tick')

            canvas.push(Event.key_press('q'))
            canvas.step(delta_seconds=1.0)
            assert heard == ['q', 'tick', 'tick']
        ```
    """
    canvas = self._canvas
    self._require_attached()
    owner = cast('_Hooked[object, object]', self)
    normalized_keys = _check_hook_arguments(owner, on, every, after, keys)
    compiled = compile_when(when)
    if on is None and not compiled.is_opaque and compiled.reads:
        if not compiled.reads & {'keyboard', 'mouse', 'scroll'}:
            raise ValueError(
                'when reads time, the size of the parent or deps, but a hook with no on= is '
                'only checked when an input event arrives. Add on="tick" or '
                'on="frame" so it is checked as time passes, or read an input in the '
                'condition.'
            )
    if requires_deps and not canvas._deps_given:
        raise TerminalError(
            'This hook needs dependencies (requires_deps=True), but the canvas has none '
            'yet. Give them when you create the canvas: xnano.new(deps=your_dependencies) '
            'or xnano.open(deps=your_dependencies), or open the canvas with '
            'canvas.open(deps=your_dependencies) before you register this hook.'
        )

    def attach(
        callback: Hook[DepsT, StateT],
    ) -> HookHandle[DepsT, StateT]:
        return self._attach_hook(
            cast(
                'Callable[[Context[DepsT, StateT]], object]',
                _check_hook_function(callback),
            ),
            on=on,
            when=compiled,
            every=every,
            after=after,
            keys=normalized_keys,
        )

    if function is None:
        return attach
    return attach(function)

new ¶

__new__(*arguments: object, **keywords: object) -> Self

Refuse a direct call: a canvas is created with xnano.new.

Source code in xnano/canvas.py

def __new__(cls, *arguments: object, **keywords: object) -> Self:
    """Refuse a direct call: a canvas is created with ``xnano.new``."""
    if arguments or 'is_realtime' not in keywords:
        raise TypeError(
            f'{cls.__name__} is not created by calling it. Create a canvas with '
            f'xnano.new(...), or put one on the screen with xnano.open(...).'
        )
    return super().__new__(cls)

open ¶

open(*, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, **settings: Unpack[OpenSettings]) -> Terminal[DepsT, StateT]

Put this canvas on your screen, and return it as a Terminal.

The same object is returned: after this, isinstance(canvas, xnano.Terminal) is true. From then on it runs by itself on a thread of its own and on the wall clock, which continues from the time the canvas had: elapsed time, the frame count, every and after timers and a stopped clock carry over, and so do the cursor, the title, everything written and every hook. Effects that were running start again from their beginning, and keyboard focus and a captured pointer are released.

width and height are the size of the canvas: the ones given here, else the ones given to new(), draw in a region of that size below the cursor; a canvas created without a size, or with '100%' for both, fills the whole window. A percentage such as '50%' is a share of the window when the canvas is opened. Any other keyword of new() except realtime may be given and applies before the canvas is shown; a gate given here wins over the one given to new(). title is the window title.

Parameters:

title (str | None, default: None ) –

The window title; None keeps the canvas's title.
width (int | Percentage | str | None, default: None ) –

The width of the region to draw in: cells, or a percentage of the window.
height (int | Percentage | str | None, default: None ) –

The height of the region to draw in: cells, or a percentage of the window.
settings (Unpack[OpenSettings], default: {} ) –

Gates, appearance keywords, fps, bpm, effects, and deps and state for a canvas that was created without them; see OpenSettings.

Returns:

Terminal[DepsT, StateT] –

This canvas, now attached to the screen.

Raises:

TerminalAlreadyOpenError –

Another canvas is already on the screen.
TerminalError –

This canvas is already on the screen, was written into another canvas, has a hook that needs a gate given as False, or there is no terminal to draw on; the canvas stays as it was.
TypeError –

realtime was given, deps or state that the canvas already has, or an effect that is not a visual effect dictionary.
ValueError –

A width was given without a height, or a value is out of range.

Examples:

with xnano.new(width=40, height=5) as canvas:
    canvas.write('hello', border='rounded')
    canvas.step()
    canvas.open(mouse=True)        # now a xnano.Terminal, 40 by 5 below the prompt
    canvas.run(quit_on='q')

Referenced by:

API Reference xnano
- xnano
  - Canvas
  - Terminal
  - new
  - open
- xnano.canvas canvas
  - Canvas
  - new
- xnano.terminal terminal
  - Terminal
  - open
- xnano.types types OpenSettings

Source code in xnano/canvas.py

def open(
    self,
    *,
    title: str | None = None,
    width: int | Percentage | str | None = None,
    height: int | Percentage | str | None = None,
    **settings: Unpack[OpenSettings],
) -> Terminal[DepsT, StateT]:
    """
    Put this canvas on your screen, and return it as a [`Terminal`][xnano.Terminal].

    The same object is returned: after this, ``isinstance(canvas, xnano.Terminal)`` is
    true. From then on it runs by itself on a thread of its own and on the wall clock, which
    continues from the time the canvas had: elapsed time, the frame count, ``every`` and
    ``after`` timers and a stopped clock carry over, and so do the cursor, the title,
    everything written and every hook. Effects that were running start again from their
    beginning, and keyboard focus and a captured pointer are released.

    ``width`` and ``height`` are the size of the canvas: the ones given here, else the
    ones given to ``new()``, draw in a region of that size below the cursor; a canvas
    created without a size, or with ``'100%'`` for both, fills the whole window. A
    percentage such as ``'50%'`` is a share of the window when the canvas is opened. Any other keyword of ``new()`` except
    ``realtime`` may be given and applies before the canvas is shown; a gate given here
    wins over the one given to ``new()``. ``title`` is the window title.

    Args:
        title: The window title; ``None`` keeps the canvas's title.
        width: The width of the region to draw in: cells, or a percentage of the window.
        height: The height of the region to draw in: cells, or a percentage of the window.
        settings: Gates, appearance keywords, ``fps``, ``bpm``, ``effects``, and ``deps``
            and ``state`` for a canvas that was created without them; see
            [`OpenSettings`][xnano.types.OpenSettings].

    Returns:
        This canvas, now attached to the screen.

    Raises:
        TerminalAlreadyOpenError: Another canvas is already on the screen.
        TerminalError: This canvas is already on the screen, was written into another
            canvas, has a hook that needs a gate given as ``False``, or there is no
            terminal to draw on; the canvas stays as it was.
        TypeError: ``realtime`` was given, ``deps`` or ``state`` that the canvas already
            has, or an effect that is not a visual effect dictionary.
        ValueError: A ``width`` was given without a ``height``, or a value is out of
            range.

    Examples:
        ```text
        with xnano.new(width=40, height=5) as canvas:
            canvas.write('hello', border='rounded')
            canvas.step()
            canvas.open(mouse=True)        # now a xnano.Terminal, 40 by 5 below the prompt
            canvas.run(quit_on='q')
        ```
    """
    self._attach_screen(title=title, width=width, height=height, settings=settings)
    from xnano.terminal import Terminal

    assert isinstance(self, Terminal)
    return self

close ¶

close(*, raise_failure: bool = True) -> None

Release everything the canvas holds, and give the screen back if it has one.

Closing twice is harmless. Leaving a with block closes the canvas, unless it is part of another canvas or was created inside another canvas's with block: then it stays usable and closes with that canvas. Closing a canvas closes the canvases created inside its block that were not written anywhere. Closing a canvas that was written into another one takes it off and leaves that one running.

Parameters:

raise_failure (bool, default: True ) –

Whether to raise the error a callback raised on the loop, which stopped the canvas. A with block passes False while another error is already propagating.

Raises:

TerminalError –

A callback raised on the canvas's loop, or the loop would not stop.

Referenced by:

API Reference xnano
- xnano Canvas
- xnano.canvas canvas Canvas

Source code in xnano/canvas.py

def close(self, *, raise_failure: bool = True) -> None:
    """
    Release everything the canvas holds, and give the screen back if it has one.

    Closing twice is harmless. Leaving a ``with`` block closes the canvas, unless it is
    part of another canvas or was created inside another canvas's ``with`` block: then it
    stays usable and closes with that canvas. Closing a canvas closes the canvases created
    inside its block that were not written anywhere. Closing a canvas that was written into
    another one takes it off and leaves that one running.

    Args:
        raise_failure: Whether to raise the error a callback raised on the loop, which
            stopped the canvas. A ``with`` block passes ``False`` while another error is
            already propagating.

    Raises:
        TerminalError: A callback raised on the canvas's loop, or the loop would not stop.
    """
    self._close_nested_canvases()
    if self._canvas is not self:
        if not self._is_closed:
            self._is_closed = True
            root = self._canvas
            closing: list[Canvas[object, object]] = [
                cast('Canvas[object, object]', self)
            ]
            with root._lock:
                # A canvas written into this one is part of it, so it ends with it.
                closing.extend(
                    inner
                    for inner in list(root._children)
                    if inner is not self
                    and inner._is_inside(cast('Canvas[object, object]', self))
                )
                for canvas in closing:
                    canvas._is_closed = True
                    if canvas in root._children:
                        root._children.remove(canvas)
            placement = self._parent_placement
            if placement is not None and not root.is_closed:
                for canvas in closing:
                    root._host.post(canvas._cancel_hooks)
                placement.remove()
        if _current_canvas() is self:
            _active_canvas.set(self._previous_chain)
        return
    if not self._stop_requested.is_set() or not self._is_finalized:
        host = getattr(self, '_host', None)
        if host is not None:
            host.require_closable()
        self._stop_requested.set()
        try:
            if host is not None:
                host.shutdown()
        finally:
            self._finalize()
    if _current_canvas() is self:
        _active_canvas.set(self._previous_chain)
    failure = self._failure
    if failure is not None and raise_failure and not self._is_failure_reported:
        self._failure = None
        raise TerminalError(self._failure_text(failure)) from failure

local ¶

local(point: Point) -> Point

Convert a cell of the screen into a cell of this canvas.

Parameters:

point (Point) –

A cell in screen coordinates, such as context.mouse.position.

Examples:

import xnano
from xnano_core import Point

with xnano.new(width=10, height=3) as canvas:
    assert canvas.local(Point(4, 1)) == Point(4, 1)

Source code in xnano/canvas.py

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

    Args:
        point: A cell in screen coordinates, such as ``context.mouse.position``.

    Examples:
        ```python
        import xnano
        from xnano_core import Point

        with xnano.new(width=10, height=3) as canvas:
            assert canvas.local(Point(4, 1)) == Point(4, 1)
        ```
    """
    point = check_point(point)
    if self._canvas is self:
        return _core.Point(point.x, point.y)
    bounds = self._root._absolute_bounds
    return _core.Point(point.x - bounds.x, point.y - bounds.y)

move ¶

move(x: int = 0, y: int = 0) -> Self

Move a canvas that is written into another one by a number of cells along each axis.

This moves the placement the canvas is drawn in; see Placement.move.

Parameters:

x (int, default: 0 ) –

Columns to move right; a negative number moves left.
y (int, default: 0 ) –

Rows to move down; a negative number moves up.

Returns:

Self –

The canvas, so calls can chain.

Raises:

TerminalError –

The canvas is not written into another canvas, so it sits at the origin and cannot move.
TypeError –

An amount is not a whole number.

Examples:

import xnano

with xnano.new(width=20, height=3) as outer:
    inner = outer.new('box', width=4, height=1)
    inner.move(x=2, y=1)
    assert (inner.x, inner.y) == (2, 1)
    assert outer.render().splitlines()[1] == '  box'

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - down
    - left
    - new
    - right
    - up
  - Terminal
    - down
    - left
    - new
    - right
    - up
- xnano.canvas canvas Canvas
  - down
  - left
  - new
  - right
  - up
- xnano.terminal terminal Terminal
  - down
  - left
  - new
  - right
  - up

Source code in xnano/canvas.py

def move(self, x: int = 0, y: int = 0) -> Self:
    """
    Move a canvas that is written into another one by a number of cells along each axis.

    This moves the placement the canvas is drawn in; see
    [`Placement.move`][xnano.placement.Placement.move].

    Args:
        x: Columns to move right; a negative number moves left.
        y: Rows to move down; a negative number moves up.

    Returns:
        The canvas, so calls can chain.

    Raises:
        TerminalError: The canvas is not written into another canvas, so it sits at the
            origin and cannot move.
        TypeError: An amount is not a whole number.

    Examples:
        ```python
        import xnano

        with xnano.new(width=20, height=3) as outer:
            inner = outer.new('box', width=4, height=1)
            inner.move(x=2, y=1)
            assert (inner.x, inner.y) == (2, 1)
            assert outer.render().splitlines()[1] == '  box'
        ```
    """
    self._written_placement().move(x=x, y=y)
    return self

up ¶

up(count: int = 1) -> Self

Move a written canvas up by count rows; see move.

Parameters:

count (int, default: 1 ) –

How many rows to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def up(self, count: int = 1) -> Self:
    """
    Move a written canvas up by ``count`` rows; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many rows to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().up(count)
    return self

down ¶

down(count: int = 1) -> Self

Move a written canvas down by count rows; see move.

Parameters:

count (int, default: 1 ) –

How many rows to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def down(self, count: int = 1) -> Self:
    """
    Move a written canvas down by ``count`` rows; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many rows to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().down(count)
    return self

left ¶

left(count: int = 1) -> Self

Move a written canvas left by count columns; see move.

Parameters:

count (int, default: 1 ) –

How many columns to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def left(self, count: int = 1) -> Self:
    """
    Move a written canvas left by ``count`` columns; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many columns to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().left(count)
    return self

right ¶

right(count: int = 1) -> Self

Move a written canvas right by count columns; see move.

Parameters:

count (int, default: 1 ) –

How many columns to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def right(self, count: int = 1) -> Self:
    """
    Move a written canvas right by ``count`` columns; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many columns to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().right(count)
    return self

new ¶

new(content: Content | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, effects: Sequence[RenderableEffectSpecification] = (), **settings: Unpack[CanvasSettings]) -> Canvas[DepsT, StateT]

Create a canvas inside this one and draw it here at once, at the top-left corner.

This is new followed by canvas.write(child): the child's size is measured in this canvas ('50%' is half of it, and no size fills it), it runs on this canvas's time and hears its input, and it closes with this canvas. Move it with move and its relatives, or create it with new and write it with x and y to place it elsewhere.

Parameters:

content (Content | None, default: None ) –

Something to write into the new canvas at once, such as text.
width (int | Percentage | str | None, default: None ) –

The width in cells, or a percentage of this canvas such as '50%'.
height (int | Percentage | str | None, default: None ) –

The height in cells, or a percentage of this canvas.
effects (Sequence[RenderableEffectSpecification], default: () ) –

Effects to apply to the new canvas, as dictionaries with a kind key.
settings (Unpack[CanvasSettings], default: {} ) –

The input gates and the new canvas's own look; see CanvasSettings.

Returns:

Canvas[DepsT, StateT] –

The new Canvas, already drawn in this one.

Raises:

TypeError –

An appearance keyword was given with content, or a keyword is unknown.
ValueError –

A size, gate or border kind is out of range.
TerminalError –

This canvas is closed, or a hook of the new canvas needs a gate this canvas turned off.

Examples:

import xnano

with xnano.new(width=12, height=4) as outer:
    panel = outer.new(height='50%', border='plain')
    assert (panel.width, panel.height) == (12, 2)
    assert outer.render().splitlines()[0] == '┌──────────┐'

Referenced by:

API Reference xnano
- xnano new
- xnano.canvas canvas new

Source code in xnano/canvas.py

def new(
    self,
    content: Content | None = None,
    /,
    *,
    width: int | Percentage | str | None = None,
    height: int | Percentage | str | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
    **settings: Unpack[CanvasSettings],
) -> Canvas[DepsT, StateT]:
    """
    Create a canvas inside this one and draw it here at once, at the top-left corner.

    This is [`new`][xnano.new] followed by ``canvas.write(child)``: the child's size is
    measured in this canvas (``'50%'`` is half of it, and no size fills it), it runs on
    this canvas's time and hears its input, and it closes with this canvas. Move it with
    [`move`][xnano.canvas.Canvas.move] and its relatives, or create it with
    [`new`][xnano.new] and write it with ``x`` and ``y`` to place it elsewhere.

    Args:
        content: Something to write into the new canvas at once, such as text.
        width: The width in cells, or a percentage of this canvas such as ``'50%'``.
        height: The height in cells, or a percentage of this canvas.
        effects: Effects to apply to the new canvas, as dictionaries with a ``kind`` key.
        settings: The input gates and the new canvas's own look; see
            [`CanvasSettings`][xnano.types.CanvasSettings].

    Returns:
        The new [`Canvas`][xnano.canvas.Canvas], already drawn in this one.

    Raises:
        TypeError: An appearance keyword was given with content, or a keyword is unknown.
        ValueError: A size, gate or border kind is out of range.
        TerminalError: This canvas is closed, or a hook of the new canvas needs a gate
            this canvas turned off.

    Examples:
        ```python
        import xnano

        with xnano.new(width=12, height=4) as outer:
            panel = outer.new(height='50%', border='plain')
            assert (panel.width, panel.height) == (12, 2)
            assert outer.render().splitlines()[0] == '┌──────────┐'
        ```
    """
    self._require_open()
    canvas: Canvas[DepsT, StateT] = _create(
        content,
        width=width,
        height=height,
        fps=self.fps,
        bpm=self.bpm,
        effects=effects,
        enclosing=cast('Canvas[object, object]', self),
        **settings,
    )
    try:
        self.write(cast('Canvas[object, object]', canvas))
    except BaseException:
        canvas.close(raise_failure=False)
        raise
    return canvas

write ¶

write(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, x: Axis | None = None, y: Axis | None = None, width: Axis | None = None, height: Axis | None = None, layer: int = 0, lock: bool = False, edges: EdgeBehavior | None = None, effects: Sequence[RenderableEffectSpecification] = (), style: Style | None = None, foreground: ColorValue | None = None, background: ColorValue | None = None, bold: bool = False, dim: bool = False, italic: bool = False, underline: bool = False, blink: bool = False, reverse: bool = False, hidden: bool = False, crossed_out: bool = False, title: str | None = None, border: BorderKind | bool | None = None, border_style: Style | None = None, padding: Spacing | None = None, margin: Spacing | None = None) -> Placement[DepsT, StateT]

Put something on the canvas: text, a widget, a buffer, another canvas or an image.

On a canvas that runs by itself it appears at once: this only declares it, and the canvas's own loop draws it. Anything you leave out is taken from the content: x and y default to the top-left corner, and width and height to the size of the content, so canvas.write('hello') shows five cells of text where it is. Change the text later by assigning the placement's text.

Inside the with block of a canvas created in this one's block, what is written here is placed and clipped within that canvas's area of this one: where it is written, or the top-left corner while it is not. Positions such as y='center' are measured in that area, and that canvas's edges applies there.

A canvas from new that is written here becomes part of this one: it draws inside the placement, its own clock is set aside and it runs on this canvas's time. It may not have been given state or deps, which belong to the outermost canvas. Its audio is not carried over: a musical clock it started and a note it was playing stop, and a formula that reads its audio.beat follows the outer canvas's musical clock, which starts at the first beat.

An image is added as an Image (never a file path or a bare TerminalImage; load one with from_image). With neither width nor height it keeps its own proportions at its own size, shrunk to fit the canvas. With one of them the other follows the image's proportions, and with both the image fits inside that box. An image sized by a percentage, or by the canvas because you gave no size, is converted again when the canvas is resized, unless it is locked. An animated image plays on the canvas's clock.

Parameters:

content (Content | Canvas[WrittenDepsT, WrittenStateT] | None, default: None ) –

Text (or a list of lines), a Buffer or widget, a canvas from new(), an image, or any Renderable; None for an empty placement.
x (Axis | None, default: None ) –

The column of the left edge: a number of cells, a percentage string, a word ('left', 'center' or 'right'), an expression, or a range ((0, 20)) that limits how far it may travel. See Axis.
y (Axis | None, default: None ) –

The row of the top edge, in the same forms ('top', 'center', 'bottom').
width (Axis | None, default: None ) –

The width, in the same forms; the content's own width when None.
height (Axis | None, default: None ) –

The height, in the same forms; the content's own height when None.
layer (int, default: 0 ) –

Content with a higher layer is drawn over content with a lower one.
lock (bool, default: False ) –

Keep the position and size the content has now, whatever the canvas's size does afterwards: percentages, words and formulas are read once.
edges (EdgeBehavior | None, default: None ) –

What the content does at the edges of its area: 'clip', 'stop' or 'wrap'; see Placement.edges. Left out, it follows what it is written on.
effects (Sequence[RenderableEffectSpecification], default: () ) –

Effects to start on the placement, as dictionaries with a kind key, such as [{'kind': 'effect.fade_to', 'foreground': 'red'}].
style (Style | None, default: None ) –

A ready-made Style for text. The parameters below are applied over it.
foreground (ColorValue | None, default: None ) –

The text color.
background (ColorValue | None, default: None ) –

The color behind the text.
bold (bool, default: False ) –

Whether the text is bold.
dim (bool, default: False ) –

Whether the text is dimmed.
italic (bool, default: False ) –

Whether the text is italic.
underline (bool, default: False ) –

Whether the text is underlined.
blink (bool, default: False ) –

Whether the text blinks.
reverse (bool, default: False ) –

Whether foreground and background are swapped.
hidden (bool, default: False ) –

Whether the text is hidden.
crossed_out (bool, default: False ) –

Whether the text is struck through.
title (str | None, default: None ) –

A title on the border of a box around the text.
border (BorderKind | bool | None, default: None ) –

The kind of border for a box around the content, a BorderKind such as 'plain', 'rounded', 'double' or 'thick'; True for 'plain' and False for none. Giving a title alone draws a plain one.
border_style (Style | None, default: None ) –

The style of the box's border.
padding (Spacing | None, default: None ) –

Space between the border and the text: a number of cells, a float or a percentage of the text's size, or a dictionary with top, right, bottom, left, vertical and horizontal. Giving it draws the text in a box without a border unless border or title is also given.
margin (Spacing | None, default: None ) –

Space outside the box, in the same forms.

Returns:

Placement[DepsT, StateT] –

A Placement to move, resize, listen on or remove.

Raises:

TypeError –

The content is a file path, raw bytes, or an operation, style or effect (apply those with canvas.update(...) instead).
TerminalError –

The content is a canvas that cannot be written here.

Examples:

import xnano

with xnano.new(width=20, height=4) as canvas:
    box = canvas.write('hello', x='50%', y=1)
    assert box.x == 10
    assert (box.width, box.height) == (5, 1)
    canvas.write(
        'Ready',
        x='center',
        y='bottom',
        foreground='green',
        bold=True,
        border='rounded',
        title='Status',
    )

Referenced by:

API Reference xnano

Source code in xnano/canvas.py

@refuse_unknown_keywords
def write(
    self,
    content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None,
    /,
    *,
    x: Axis | None = None,
    y: Axis | None = None,
    width: Axis | None = None,
    height: Axis | None = None,
    layer: int = 0,
    lock: bool = False,
    edges: EdgeBehavior | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
    style: _core.Style | None = None,
    foreground: ColorValue | None = None,
    background: ColorValue | None = None,
    bold: bool = False,
    dim: bool = False,
    italic: bool = False,
    underline: bool = False,
    blink: bool = False,
    reverse: bool = False,
    hidden: bool = False,
    crossed_out: bool = False,
    title: str | None = None,
    border: _core.BorderKind | bool | None = None,
    border_style: _core.Style | None = None,
    padding: Spacing | None = None,
    margin: Spacing | None = None,
) -> Placement[DepsT, StateT]:
    """
    Put something on the canvas: text, a widget, a buffer, another canvas or an image.

    On a canvas that runs by itself it appears at once: this only declares it, and the
    canvas's own loop draws it. Anything you leave out is taken from the content: ``x``
    and ``y`` default to the top-left corner, and ``width`` and ``height`` to the size of
    the content, so ``canvas.write('hello')`` shows five cells of text where it is.
    Change the text later by assigning the placement's
    [`text`][xnano.placement.Placement.text].

    Inside the ``with`` block of a canvas created in this one's block, what is written here
    is placed and clipped within that canvas's area of this one: where it is written, or
    the top-left corner while it is not. Positions such as ``y='center'`` are measured in
    that area, and that canvas's ``edges`` applies there.

    A canvas from [`new`][xnano.new] that is written here becomes part of this one: it
    draws inside the placement, its own clock is set aside and it runs on this canvas's
    time. It may not have been given ``state`` or ``deps``, which belong to the outermost
    canvas. Its audio is not carried over: a musical clock it started and a note it was
    playing stop, and a formula that reads its ``audio.beat`` follows the outer canvas's
    musical clock, which starts at the first beat.

    An image is added as an [`Image`][xnano.Image] (never a file path or a bare
    [`TerminalImage`][xnano_image.TerminalImage]; load one with
    [`from_image`][xnano.from_image]). With neither ``width`` nor ``height`` it keeps
    its own proportions at its own size, shrunk to fit the canvas. With one of them the
    other follows the image's proportions, and with both the image fits inside that box. An
    image sized by a percentage, or by the canvas because you gave no size, is converted
    again when the canvas is resized, unless it is locked. An animated image plays on the
    canvas's clock.

    Args:
        content: Text (or a list of lines), a [`Buffer`][xnano_core.Buffer] or widget, a
            canvas from ``new()``, an image, or any
            [`Renderable`][xnano.types.Renderable]; ``None`` for an empty placement.
        x: The column of the left edge: a number of cells, a percentage string, a word
            (``'left'``, ``'center'`` or ``'right'``), an expression, or a range
            (``(0, 20)``) that limits how far it may travel. See
            [`Axis`][xnano.types.Axis].
        y: The row of the top edge, in the same forms (``'top'``, ``'center'``,
            ``'bottom'``).
        width: The width, in the same forms; the content's own width when ``None``.
        height: The height, in the same forms; the content's own height when ``None``.
        layer: Content with a higher layer is drawn over content with a lower one.
        lock: Keep the position and size the content has now, whatever the canvas's
            size does afterwards: percentages, words and formulas are read once.
        edges: What the content does at the edges of its area: ``'clip'``, ``'stop'`` or
            ``'wrap'``; see [`Placement.edges`][xnano.placement.Placement.edges]. Left
            out, it follows what it is written on.
        effects: Effects to start on the placement, as dictionaries with a ``kind``
            key, such as ``[{'kind': 'effect.fade_to', 'foreground': 'red'}]``.
        style: A ready-made [`Style`][xnano.styles.Style] for text. The parameters below
            are applied over it.
        foreground: The text color.
        background: The color behind the text.
        bold: Whether the text is bold.
        dim: Whether the text is dimmed.
        italic: Whether the text is italic.
        underline: Whether the text is underlined.
        blink: Whether the text blinks.
        reverse: Whether foreground and background are swapped.
        hidden: Whether the text is hidden.
        crossed_out: Whether the text is struck through.
        title: A title on the border of a box around the text.
        border: The kind of border for a box around the content, a
            [`BorderKind`][xnano.types.BorderKind] such as ``'plain'``, ``'rounded'``,
            ``'double'`` or ``'thick'``; ``True`` for ``'plain'`` and ``False`` for none.
            Giving a ``title`` alone draws a plain one.
        border_style: The style of the box's border.
        padding: Space between the border and the text: a number of cells, a float or a
            percentage of the text's size, or a dictionary with ``top``, ``right``,
            ``bottom``, ``left``, ``vertical`` and ``horizontal``. Giving it draws the
            text in a box without a border unless ``border`` or ``title`` is also given.
        margin: Space outside the box, in the same forms.

    Returns:
        A [`Placement`][xnano.placement.Placement] to move, resize, listen on or remove.

    Raises:
        TypeError: The content is a file path, raw bytes, or an operation, style or effect
            (apply those with ``canvas.update(...)`` instead).
        TerminalError: The content is a canvas that cannot be written here.

    Examples:
        ```python
        import xnano

        with xnano.new(width=20, height=4) as canvas:
            box = canvas.write('hello', x='50%', y=1)
            assert box.x == 10
            assert (box.width, box.height) == (5, 1)
            canvas.write(
                'Ready',
                x='center',
                y='bottom',
                foreground='green',
                bold=True,
                border='rounded',
                title='Status',
            )
        ```
    """
    self._require_open()
    if edges is not None:
        edges = check_edges(edges)
    area = self._area_for_write(content)
    if area is not None:
        return area.write(  # type: ignore[return-value]
            content,
            x=x,
            y=y,
            width=width,
            height=height,
            layer=layer,
            lock=lock,
            edges=edges,
            effects=effects,
            style=style,
            foreground=foreground,
            background=background,
            bold=bold,
            dim=dim,
            italic=italic,
            underline=underline,
            blink=blink,
            reverse=reverse,
            hidden=hidden,
            crossed_out=crossed_out,
            title=title,
            border=border,
            border_style=border_style,
            padding=padding,
            margin=margin,
        )
    parent_buffer = self._content
    slot: _core.Buffer | None = None
    if self._layout != 'overlay':
        slot, width, height = self._open_slot(content, width, height)
        parent_buffer = slot
    try:
        placement = self._canvas._place_on(
            parent_buffer,
            content,
            parent_owner=cast('Canvas[object, object]', self),
            x=x,
            y=y,
            width=width,
            height=height,
            layer=layer,
            lock=lock,
            style=style,
            foreground=foreground,
            background=background,
            bold=bold,
            dim=dim,
            italic=italic,
            underline=underline,
            blink=blink,
            reverse=reverse,
            hidden=hidden,
            crossed_out=crossed_out,
            title=title,
            border=border,
            border_style=border_style,
            padding=padding,
            margin=margin,
        )
    except BaseException:
        if slot is not None:
            self._close_slot(slot)
        raise
    if slot is not None:
        self._slots[-1] = (
            cast('Placement[object, object]', placement),
            *self._slots[-1][1:],
        )
    if effects:
        apply_effects(cast('Placement[object, object]', placement), effects)
    placement._take_edges(edges, content)
    return placement

clear ¶

clear() -> None

Erase everything written or drawn directly on the canvas's cells.

Source code in xnano/canvas.py

def clear(self) -> None:
    """Erase everything written or drawn directly on the canvas's cells."""
    self._require_open()
    self._flush_look()
    self._content.update(_core.Fill(' '))

update ¶

update(*operations: Operation | Style) -> Self

Change the canvas's own cells with operations, styles or effects.

canvas | operation does the same. To put content on the canvas, use write instead.

Parameters:

operations (Operation | Style, default: () ) –

What to apply, in order: a core operation such as Fill or Write, a style, or an xnano customization such as an effect.

Returns:

Self –

The canvas, so calls chain.

Examples:

import xnano
from xnano_core import Fill

with xnano.new(width=4, height=1) as canvas:
    canvas.update(Fill('.'))
    assert canvas.render() == '....'
    canvas | Fill('#')
    assert canvas.render() == '####'

Source code in xnano/canvas.py

def update(self, *operations: _core.Operation | _core.Style) -> Self:
    """
    Change the canvas's own cells with operations, styles or effects.

    ``canvas | operation`` does the same. To put content on the canvas, use
    [`write`][xnano.canvas.Canvas.write] instead.

    Args:
        operations: What to apply, in order: a core operation such as ``Fill`` or
            ``Write``, a style, or an xnano customization such as an effect.

    Returns:
        The canvas, so calls chain.

    Examples:
        ```python
        import xnano
        from xnano_core import Fill

        with xnano.new(width=4, height=1) as canvas:
            canvas.update(Fill('.'))
            assert canvas.render() == '....'
            canvas | Fill('#')
            assert canvas.render() == '####'
        ```
    """
    self._require_open()
    for item in operations:
        if isinstance(item, ContextualOperation):
            cast('ContextualOperation[DepsT, StateT]', item).apply_to(self)
        elif isinstance(item, Customization):
            item.apply_to(cast('Canvas[object, object]', self))
        elif isinstance(item, _core.Style):
            self._content.update(_core.ApplyStyle(item))
        else:
            self._content.update(item)
    return self

or ¶

__or__(other: Operation | Style | Sequence[Operation]) -> Self

Apply an operation, customization or style with canvas | operation.

Source code in xnano/canvas.py

def __or__(
    self,
    other: _core.Operation | _core.Style | Sequence[_core.Operation],
) -> Self:
    """Apply an operation, customization or style with ``canvas | operation``."""
    if isinstance(other, (_core.Operation, _core.Style)):
        self.update(other)
    else:
        self.update(*other)
    return self

ior ¶

__ior__(other: Operation | Style | Sequence[Operation]) -> Self

Apply an operation, customization or style in place with canvas |= operation.

Source code in xnano/canvas.py

def __ior__(
    self,
    other: _core.Operation | _core.Style | Sequence[_core.Operation],
) -> Self:
    """Apply an operation, customization or style in place with ``canvas |= operation``."""
    return self.__or__(other)

inspect ¶

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

Evaluate an expression against the canvas and return its value.

Parameters:

expression (Expression[ValueT]) –

Any expression, such as Width, TimeElapsed % 1 or canvas.audio.level.

Examples:

import xnano
from xnano_core import Width

with xnano.new(width=12, height=2) as canvas:
    assert canvas.inspect(Width) == 12

Source code in xnano/canvas.py

def inspect(self, expression: _core.Expression[ValueT]) -> ValueT:
    """
    Evaluate an expression against the canvas and return its value.

    Args:
        expression: Any expression, such as ``Width``, ``TimeElapsed % 1`` or
            ``canvas.audio.level``.

    Examples:
        ```python
        import xnano
        from xnano_core import Width

        with xnano.new(width=12, height=2) as canvas:
            assert canvas.inspect(Width) == 12
        ```
    """
    self._require_open()
    return self._canvas._host.call(lambda: self._root.inspect(expression))

iter ¶

iter(*, count: int | None = None, seconds: float | None = None) -> Iterator[Frame]

Iterate over the canvas's frames, drawing between them; pass count= or seconds=, or break out of the loop.

Each iteration yields a Frame, and whatever you change before asking for the next one is drawn. On a canvas from new() each iteration moves the clock by one frame of its fps, so the same loop produces the same frames every run; without count or seconds it runs as fast as your code. A canvas that runs by itself draws as you declare, so there this only paces your code at its fps: if you are slow, frames are skipped rather than queued.

stop freezes the time iter() follows: the iterations go on drawing and hooks still run, but the clock stands still until resume. To move a stopped canvas one frame, call step.

The iteration ends when count frames have been yielded, when the canvas's time has run for seconds (whichever comes first), when the canvas is asked to quit or closed, or when you break out of the loop.

Parameters:

count (int | None, default: None ) –

The most frames to yield.
seconds (float | None, default: None ) –

The most seconds of the canvas's time to run for.

Raises:

TerminalError –

seconds without count on a stopped canvas, which would never reach the end.
TerminalClosedError –

The canvas is closed.

Examples:

import xnano

with xnano.new(width=8, height=1, fps=10) as canvas:
    frames = list(canvas.iter(count=3))
assert [frame.elapsed_seconds for frame in frames] == [0.0, 0.1, 0.2]

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - fps
    - step
  - Terminal
    - fps
    - step
  - iter
  - new
- xnano.canvas canvas
  - Canvas
    - fps
    - step
  - iter
  - new
- xnano.terminal terminal Terminal
  - fps
  - step

Source code in xnano/canvas.py

def iter(
    self, *, count: int | None = None, seconds: float | None = None
) -> Iterator[Frame]:
    """
    Iterate over the canvas's frames, drawing between them; pass ``count=`` or ``seconds=``,
    or break out of the loop.

    Each iteration yields a [`Frame`][xnano.context.Frame], and whatever you change
    before asking for the next one is drawn. On a canvas from ``new()`` each iteration
    moves the clock by one frame of its ``fps``, so the same loop produces the same
    frames every run; without ``count`` or ``seconds`` it runs as fast as your code. A
    canvas that runs by itself draws as you declare, so there this only paces your code
    at its ``fps``: if you are slow, frames are skipped rather than queued.

    [`stop`][xnano.canvas.Canvas.stop] freezes the time ``iter()`` follows: the
    iterations go on drawing and hooks still run, but the clock stands still until
    [`resume`][xnano.canvas.Canvas.resume]. To move a stopped canvas one frame, call
    [`step`][xnano.canvas.Canvas.step].

    The iteration ends when ``count`` frames have been yielded, when the canvas's time has
    run for ``seconds`` (whichever comes first), when the canvas is asked to
    [`quit`][xnano.canvas.Canvas.quit] or closed, or when you break out of the loop.

    Args:
        count: The most frames to yield.
        seconds: The most seconds of the canvas's time to run for.

    Raises:
        TerminalError: ``seconds`` without ``count`` on a stopped canvas, which would
            never reach the end.
        TerminalClosedError: The canvas is closed.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1, fps=10) as canvas:
            frames = list(canvas.iter(count=3))
        assert [frame.elapsed_seconds for frame in frames] == [0.0, 0.1, 0.2]
        ```
    """
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    if count is not None and (
        isinstance(count, bool) or not isinstance(count, int) or count < 0
    ):
        raise ValueError(
            f'count must be a whole number of frames, 0 or more, but was {count!r}.'
        )
    if seconds is not None and (
        isinstance(seconds, bool)
        or not isinstance(seconds, (int, float))
        or not seconds > 0
    ):
        raise ValueError(
            f'seconds must be a number above zero, but was {seconds!r}. Pass count= to '
            f'stop after a number of frames instead.'
        )
    if seconds is not None and count is None:
        canvas._refuse_endless_seconds(seconds)
    return canvas._frames(count, seconds)

step ¶

step(*, delta_seconds: float | None = None) -> Frame

Move time by delta_seconds, one frame by default, and draw exactly one frame.

On a canvas from new() this always works, and it moves time even while the canvas is stopped, which leaves it stopped: it is how a stopped canvas is walked one frame at a time. A canvas that runs by itself can be stepped only while it is stopped. One frame is 1 / fps seconds; default steps and the frames of iter share one count, so sixty of them at fps=60 are exactly one second. A large delta_seconds is one jump: timers that it crossed all run, and so do fixed-step every hooks, at most 100000 of their steps in one step; the steps that remain run in the steps that follow.

Parameters:

delta_seconds (float | None, default: None ) –

How far to move, in seconds, above zero; one frame when None.

Returns:

Frame –

The Frame that was drawn.

Raises:

ValueError –

delta_seconds is not above zero.
TerminalError –

The canvas runs by itself and is not stopped.
TerminalClosedError –

The canvas was closed.

Examples:

import xnano

with xnano.new(width=8, height=1, fps=10) as canvas:
    frame = canvas.step()
    assert frame.elapsed_seconds == 0.1
    canvas.stop()
    canvas.step(delta_seconds=0.5)
    assert canvas.time.elapsed == 0.6
    assert canvas.time.is_stopped

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - stop
  - Terminal
    - iter
    - stop
  - new
- xnano.audio audio AudioDevice render_sound
- xnano.canvas canvas
  - Canvas
    - iter
    - stop
  - new
- xnano.terminal terminal Terminal
  - iter
  - stop
- xnano.time time Time step
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def step(self, *, delta_seconds: float | None = None) -> Frame:
    """
    Move time by ``delta_seconds``, one frame by default, and draw exactly one frame.

    On a canvas from ``new()`` this always works, and it moves time even while the
    canvas is stopped, which leaves it stopped: it is how a stopped canvas is walked one
    frame at a time. A canvas that runs by itself can be stepped only while it is
    stopped. One frame is ``1 / fps`` seconds; default steps and the frames of
    [`iter`][xnano.canvas.Canvas.iter] share one count, so sixty of them at ``fps=60``
    are exactly one second. A large ``delta_seconds`` is one jump: timers that it crossed
    all run, and so do fixed-step ``every`` hooks, at most 100000 of their steps in one
    step; the steps that remain run in the steps that follow.

    Args:
        delta_seconds: How far to move, in seconds, above zero; one frame when ``None``.

    Returns:
        The [`Frame`][xnano.context.Frame] that was drawn.

    Raises:
        ValueError: ``delta_seconds`` is not above zero.
        TerminalError: The canvas runs by itself and is not stopped.
        TerminalClosedError: The canvas was closed.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1, fps=10) as canvas:
            frame = canvas.step()
            assert frame.elapsed_seconds == 0.1
            canvas.stop()
            canvas.step(delta_seconds=0.5)
            assert canvas.time.elapsed == 0.6
            assert canvas.time.is_stopped
        ```
    """
    self._require_own_presence()
    return self._canvas._step(delta_seconds)

deliver_events ¶

deliver_events() -> None

Deliver pushed events to their hooks and draw a frame, without moving time.

Events pushed with push reach their hooks at the canvas's next step; this is that step on a canvas whose clock you move. A canvas that runs by itself delivers them on its own.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:
    heard = []
    canvas.hook(lambda context: heard.append(context.event.kind))
    canvas.push(Event.custom('ping'))
    canvas.deliver_events()
    assert heard == ['custom']
    assert canvas.time.elapsed == 0.0

Source code in xnano/canvas.py

def deliver_events(self) -> None:
    """
    Deliver pushed events to their hooks and draw a frame, without moving time.

    Events pushed with [`push`][xnano.canvas.Canvas.push] reach their hooks at the
    canvas's next step; this is that step on a canvas whose clock you move. A canvas that
    runs by itself delivers them on its own.

    Examples:
        ```python
        import xnano
        from xnano_core import Event

        with xnano.new(width=8, height=1) as canvas:
            heard = []
            canvas.hook(lambda context: heard.append(context.event.kind))
            canvas.push(Event.custom('ping'))
            canvas.deliver_events()
            assert heard == ['custom']
            assert canvas.time.elapsed == 0.0
        ```
    """
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    if canvas._host.is_autonomous:
        canvas._host.call(lambda: canvas._runtime.request_frame())
        return
    canvas._raise_failure()
    canvas._runtime.step()
    canvas._pushed_pointer = None
    canvas._raise_failure()

stop ¶

stop() -> None

Freeze time: the same as Time.stop.

The canvas keeps drawing and hooks still hear input, but animations, effects, formulas, timers and the beat stand still until resume. step moves a stopped canvas one frame at a time. To end a loop, call quit.

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - resume
  - Terminal
    - iter
    - resume
- xnano.audio audio AudioDevice stop
- xnano.canvas canvas Canvas
  - iter
  - resume
- xnano.terminal terminal Terminal
  - iter
  - resume
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def stop(self) -> None:
    """
    Freeze time: the same as [`Time.stop`][xnano.time.Time.stop].

    The canvas keeps drawing and hooks still hear input, but animations, effects,
    formulas, timers and the beat stand still until [`resume`][xnano.canvas.Canvas.resume].
    [`step`][xnano.canvas.Canvas.step] moves a stopped canvas one frame at a time. To end a
    loop, call [`quit`][xnano.canvas.Canvas.quit].
    """
    self._require_own_presence()
    self._canvas._time.stop()

resume ¶

resume() -> None

Let time run on from where stop froze it.

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - stop
  - Terminal
    - iter
    - stop
- xnano.audio audio AudioDevice stop
- xnano.canvas canvas Canvas
  - iter
  - stop
- xnano.terminal terminal Terminal
  - iter
  - stop
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def resume(self) -> None:
    """Let time run on from where [`stop`][xnano.canvas.Canvas.stop] froze it."""
    self._require_own_presence()
    self._canvas._time.resume()

quit ¶

quit() -> None

Ask the canvas's loop to end.

Safe from any thread, including from a hook. A running iter(), run(), wait_for_key() or prompt() ends. On a canvas from new() the canvas stays open for writing and rendering; on a canvas that runs by itself (realtime=True, or on the screen) the loop ends and the canvas closes.

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - run
    - stop
  - Terminal
    - iter
    - run
    - stop
  - active
- xnano.canvas canvas
  - Canvas
    - iter
    - run
    - stop
  - active
- xnano.terminal terminal Terminal
  - iter
  - run
  - stop

Source code in xnano/canvas.py

def quit(self) -> None:
    """
    Ask the canvas's loop to end.

    Safe from any thread, including from a hook. A running ``iter()``, ``run()``,
    ``wait_for_key()`` or ``prompt()`` ends. On a canvas from ``new()`` the canvas stays
    open for writing and rendering; on a canvas that runs by itself (``realtime=True``, or
    on the screen) the loop ends and the canvas closes.
    """
    self._require_own_presence()
    canvas = self._canvas
    canvas._stop_requested.set()
    if not canvas._is_closed and canvas._host.is_autonomous:
        canvas._host.post(lambda: canvas._stop_runtime())

run ¶

run(*, quit_on: KeyName | Sequence[KeyName] | None = 'ctrl+c') -> None

Wait until the canvas's loop ends.

A canvas that runs by itself draws and listens on its own, so this only keeps your program alive until a quit key is pressed, or something calls quit (a hook, another thread). Declare what you want before calling it.

Parameters:

quit_on (KeyName | Sequence[KeyName] | None, default: 'ctrl+c' ) –

The key, or keys, that end the loop, such as 'q' or ('q', 'escape'). 'ctrl+c' by default; give None to leave ending to your own code.

Raises:

TerminalError –

A callback raised on the canvas's loop, or the canvas has a clock that only moves when you move it, so waiting would never end.

Referenced by:

API Reference xnano
- xnano Canvas
- xnano.canvas canvas Canvas

Source code in xnano/canvas.py

def run(self, *, quit_on: KeyName | Sequence[KeyName] | None = 'ctrl+c') -> None:
    """
    Wait until the canvas's loop ends.

    A canvas that runs by itself draws and listens on its own, so this only keeps your
    program alive until a quit key is pressed, or something calls
    [`quit`][xnano.canvas.Canvas.quit] (a hook, another thread). Declare what you want
    before calling it.

    Args:
        quit_on: The key, or keys, that end the loop, such as ``'q'`` or
            ``('q', 'escape')``. ``'ctrl+c'`` by default; give ``None`` to leave ending
            to your own code.

    Raises:
        TerminalError: A callback raised on the canvas's loop, or the canvas has a clock
            that only moves when you move it, so waiting would never end.
    """
    canvas = self._canvas
    canvas._require_open()
    host = canvas._host
    if not isinstance(host, _ThreadHost):
        raise TerminalError(
            'A canvas with a manual clock never moves by itself, so run() would wait '
            'forever. Drive it with canvas.iter() or canvas.step(), open it on the screen '
            'with canvas.open(), or create it with realtime=True.'
        )
    if quit_on is not None:
        keys = (quit_on,) if isinstance(quit_on, str) else tuple(quit_on)
        if canvas._is_live and canvas._resolved_gates.get('keyboard') is False:
            # With the keyboard off, only the interrupt gate can end the loop on Ctrl-C.
            keys = tuple(key for key in keys if key != 'ctrl+c')
        if keys:

            @canvas.hook(on='key', keys=keys)
            def quit_key(context: Context[DepsT, StateT]) -> None:
                context.canvas.quit()

    try:
        while not host.wait(0.1):
            pass
    except KeyboardInterrupt:
        canvas.quit()
        raise
    failure = canvas._failure
    if failure is not None:
        canvas._failure = None
        raise TerminalError(canvas._failure_text(failure)) from failure

wait_for_key ¶

wait_for_key(*keys: KeyName) -> str

Wait until a key is pressed, and return its name.

Your program waits here while the canvas goes on drawing and animating. It reads like input(): nothing else runs on your thread until the key arrives.

Parameters:

keys (KeyName, default: () ) –

The keys to wait for, such as 'enter' or 'q'. Give none to take any key.

Returns:

str –

The name of the key that was pressed.

Raises:

TerminalError –

The canvas ended, or has a manual clock, so no key could arrive.

Examples:

In a program: canvas.wait_for_key() after adding "Press any key to start". Here a timer plays the part of the person pressing the key:

import xnano
from xnano.events import Event

with xnano.new(realtime=True, width=30, height=2) as canvas:
    canvas.write('Press enter to start')

    @canvas.hook(on='tick', after=0.05)
    def press(context: xnano.Context) -> None:
        canvas.push(Event.key_press('enter'))

    assert canvas.wait_for_key('enter') == 'enter'

Source code in xnano/canvas.py

def wait_for_key(self, *keys: KeyName) -> str:
    """
    Wait until a key is pressed, and return its name.

    Your program waits here while the canvas goes on drawing and animating. It reads
    like ``input()``: nothing else runs on your thread until the key arrives.

    Args:
        keys: The keys to wait for, such as ``'enter'`` or ``'q'``. Give none to take any key.

    Returns:
        The name of the key that was pressed.

    Raises:
        TerminalError: The canvas ended, or has a manual clock, so no key could arrive.

    Examples:
        In a program: ``canvas.wait_for_key()`` after adding "Press any key to start".
        Here a timer plays the part of the person pressing the key:

        ```python
        import xnano
        from xnano.events import Event

        with xnano.new(realtime=True, width=30, height=2) as canvas:
            canvas.write('Press enter to start')

            @canvas.hook(on='tick', after=0.05)
            def press(context: xnano.Context) -> None:
                canvas.push(Event.key_press('enter'))

            assert canvas.wait_for_key('enter') == 'enter'
        ```
    """
    pressed: list[str] = []
    done = threading.Event()

    @self.hook(on='key', keys=keys or None)
    def hear(context: Context[DepsT, StateT]) -> None:
        key = context.keyboard.key
        if key is not None:
            pressed.append(key)
        context.hook.remove()
        done.set()

    self._wait_until(done, 'a key')
    return pressed[0]

prompt ¶

prompt(text: str, *, x: int = 0, y: int = 0, default: str = '') -> str

Prompt for a line of text, and return what was typed.

The prompt and the answer appear on the canvas while your program waits, like input(). Enter submits and Backspace deletes.

Parameters:

text (str) –

What to ask, such as 'Your name: '.
x (int, default: 0 ) –

The column of the prompt.
y (int, default: 0 ) –

The row of the prompt.
default (str, default: '' ) –

Text already in the answer, which the user can edit.

Returns:

str –

What was typed, without the prompt.

Raises:

TerminalError –

The canvas ended, or has a manual clock, so no answer could arrive.

Examples:

In a program: name = canvas.prompt('Your name: '). Here a timer plays the part of the person typing:

import xnano
from xnano.events import Event

with xnano.new(realtime=True, width=30, height=2) as canvas:

    @canvas.hook(on='tick', after=0.05)
    def type_answer(context: xnano.Context) -> None:
        for letter in 'Ada':
            canvas.push(Event.key_press(letter))
        canvas.push(Event.key_press('enter'))

    assert canvas.prompt('Your name: ') == 'Ada'

Source code in xnano/canvas.py

def prompt(self, text: str, *, x: int = 0, y: int = 0, default: str = '') -> str:
    """
    Prompt for a line of text, and return what was typed.

    The prompt and the answer appear on the canvas while your program waits, like
    ``input()``. ``Enter`` submits and ``Backspace`` deletes.

    Args:
        text: What to ask, such as ``'Your name: '``.
        x: The column of the prompt.
        y: The row of the prompt.
        default: Text already in the answer, which the user can edit.

    Returns:
        What was typed, without the prompt.

    Raises:
        TerminalError: The canvas ended, or has a manual clock, so no answer could arrive.

    Examples:
        In a program: ``name = canvas.prompt('Your name: ')``. Here a timer plays the part
        of the person typing:

        ```python
        import xnano
        from xnano.events import Event

        with xnano.new(realtime=True, width=30, height=2) as canvas:

            @canvas.hook(on='tick', after=0.05)
            def type_answer(context: xnano.Context) -> None:
                for letter in 'Ada':
                    canvas.push(Event.key_press(letter))
                canvas.push(Event.key_press('enter'))

            assert canvas.prompt('Your name: ') == 'Ada'
        ```
    """
    answer = [default]
    done = threading.Event()

    shown = self.write(text + default + ' ', x=x, y=y)

    def show() -> None:
        line = text + answer[0]
        shown.text = line + ' '
        self.cursor.position = (x + _core.display_width(line), y)

    cursor = self.cursor
    previous = (cursor.shape, cursor.is_blinking, cursor.is_visible, cursor.position)
    following = cursor._canvas._cursor_follow
    self.cursor.shape = 'bar'
    self.cursor.is_blinking = True
    self.cursor.is_visible = True
    show()

    @self.hook(on='key', when="keyboard.kind != 'release'")
    def edit(context: Context[DepsT, StateT]) -> None:
        key = context.keyboard
        if key.key is None:
            return
        if key.key == 'enter':
            done.set()
            return
        if key.key == 'backspace':
            answer[0] = answer[0][:-1]
        elif key.text is not None and not key.modifiers - {'shift'}:
            answer[0] += key.text
        show()

    try:
        self._wait_until(done, 'an answer')
    finally:
        edit.remove()
        cursor.is_visible = False
        cursor.is_blinking = previous[1]
        cursor.shape = previous[0]
        if following is None:
            cursor.position = previous[3]
        else:
            cursor.follow(following[0], x=following[1], y=following[2])
        cursor.is_visible = previous[2]
        shown.remove()
    return answer[0]

render ¶

render(*, format: Literal['text', 'ansi'] = 'text') -> str

Draw the current frame and return it, without a screen.

A canvas that was written into another one returns its own cells alone, at its own size, as they stand in the outer canvas's current frame.

Parameters:

format (Literal['text', 'ansi'], default: 'text' ) –

'text' for the characters alone, 'ansi' for the characters with their colors and styles as escape codes.

Raises:

ValueError –

format is neither 'text' nor 'ansi'.

Examples:

import xnano

with xnano.new(width=6, height=2) as canvas:
    canvas.write('hello', y=1)
    assert canvas.render().splitlines() == ['', 'hello']
    assert 'hello' in canvas.render(format='ansi')

Referenced by:

API Reference xnano xnano.output output Output

Source code in xnano/canvas.py

def render(self, *, format: Literal['text', 'ansi'] = 'text') -> str:
    """
    Draw the current frame and return it, without a screen.

    A canvas that was written into another one returns its own cells alone, at its own
    size, as they stand in the outer canvas's current frame.

    Args:
        format: ``'text'`` for the characters alone, ``'ansi'`` for the characters with
            their colors and styles as escape codes.

    Raises:
        ValueError: ``format`` is neither ``'text'`` nor ``'ansi'``.

    Examples:
        ```python
        import xnano

        with xnano.new(width=6, height=2) as canvas:
            canvas.write('hello', y=1)
            assert canvas.render().splitlines() == ['', 'hello']
            assert 'hello' in canvas.render(format='ansi')
        ```
    """
    if format not in ('text', 'ansi'):
        raise ValueError(
            f"format must be 'text' or 'ansi', but was {format!r}. 'text' gives the "
            f"characters, 'ansi' the characters with their colors."
        )
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    if canvas is not self:
        root_buffer = self._root

        def render_child() -> str:
            canvas._runtime.render()
            return root_buffer.render(format=format)

        return canvas._host.call(render_child)
    snapshot = canvas._host.call(lambda: canvas._runtime.render())
    if format == 'ansi':
        return snapshot.ansi
    return '\n'.join(snapshot.lines())

push ¶

push(event: Event) -> None

Deliver an event to the canvas as if it had been typed, clicked or reported.

Hooks hear it the same way as input from the keyboard and mouse, at the canvas's next step, whatever the input gates say. Build events with Event; Event.custom(name, data=...) makes one of your own.

Parameters:

event (Event) –

The event to deliver.

Raises:

TypeError –

The value is not an Event.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:
    heard = []
    canvas.hook(
        lambda context: heard.append(context.event.custom_name),
        when=lambda context: context.event.kind == 'custom',
    )
    canvas.push(Event.custom('volume_changed'))
    canvas.deliver_events()
assert heard == ['volume_changed']

Referenced by:

API Reference xnano

Source code in xnano/canvas.py

def push(self, event: _core.Event) -> None:
    """
    Deliver an event to the canvas as if it had been typed, clicked or reported.

    Hooks hear it the same way as input from the keyboard and mouse, at the canvas's
    next step, whatever the input gates say. Build events with
    [`Event`][xnano_core.Event]; ``Event.custom(name, data=...)`` makes one of your own.

    Args:
        event: The event to deliver.

    Raises:
        TypeError: The value is not an [`Event`][xnano_core.Event].

    Examples:
        ```python
        import xnano
        from xnano_core import Event

        with xnano.new(width=8, height=1) as canvas:
            heard = []
            canvas.hook(
                lambda context: heard.append(context.event.custom_name),
                when=lambda context: context.event.kind == 'custom',
            )
            canvas.push(Event.custom('volume_changed'))
            canvas.deliver_events()
        assert heard == ['volume_changed']
        ```
    """
    if not isinstance(event, _core.Event):
        raise TypeError(
            f'push() takes an Event such as xnano_core.Event.custom("ping"), but got '
            f'{event!r}. To press a key, push xnano_core.Event.key_press("q"), or call '
            f'context.keyboard.push("q") inside a hook.'
        )
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    canvas._host.post(lambda: canvas._runtime.inject(event))

play ¶

play(playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle

Play a note, a sound, a symbol name, a melody or a sequence of those, and return at once.

This is audio.play; see it for what playable may be and for every option. On a canvas from new() the sound is recorded instead of played; read it with audio.render_sound.

Parameters:

playable (PlaySource) –

What to play: a note, a sound, a symbol name, melody text such as 'C4 E4 G4:2', a MIDI number, a frequency, or a sequence of those.
options (Unpack[PlayOptions], default: {} ) –

The settings of PlayOptions, such as instrument, volume, pan, beats and at_beat.

Returns:

PlayHandle –

A PlayHandle that tells when the sound is over.

Examples:

import xnano

with xnano.new(width=8, height=1, bpm=100) as canvas:
    canvas.play('C4 E4 G4:2 rest C5+E5+G5', instrument='bell')
    canvas.step(delta_seconds=1.0)
    assert canvas.audio.render_sound().duration_milliseconds == 1000.0

Referenced by:

API Reference xnano
- xnano
  - Audio
  - Note
  - note
- xnano.audio audio
  - PlaySource
  - Audio
- xnano.music music
  - Note
  - note
- xnano.types types
  - PlaySource
  - Playable

Source code in xnano/canvas.py

def play(self, playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle:
    """
    Play a note, a sound, a symbol name, a melody or a sequence of those, and return at once.

    This is [`audio.play`][xnano.audio.AudioDevice.play]; see it for what ``playable`` may
    be and for every option. On a canvas from ``new()`` the sound is recorded instead of
    played; read it with [`audio.render_sound`][xnano.audio.AudioDevice.render_sound].

    Args:
        playable: What to play: a note, a sound, a symbol name, melody text such as
            ``'C4 E4 G4:2'``, a MIDI number, a frequency, or a sequence of those.
        options: The settings of [`PlayOptions`][xnano.types.PlayOptions], such as
            ``instrument``, ``volume``, ``pan``, ``beats`` and ``at_beat``.

    Returns:
        A [`PlayHandle`][xnano.music.PlayHandle] that tells when the sound is over.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1, bpm=100) as canvas:
            canvas.play('C4 E4 G4:2 rest C5+E5+G5', instrument='bell')
            canvas.step(delta_seconds=1.0)
            assert canvas.audio.render_sound().duration_milliseconds == 1000.0
        ```
    """
    self._require_own_presence()
    if hasattr(playable, '__xnano_play__') or not isinstance(playable, str):
        handle = _play_component(
            cast('Canvas[object, object]', self._canvas), playable, options
        )
        if handle is not None:
            return handle
    return self.audio.play(playable, **options)

state_reference ¶

state_reference(reader: Callable[[StateT], ValueT]) -> StateReference[ValueT]

A core reference for one field of the canvas's state.

The reference can be used as an axis, a range bound or a widget parameter.

Parameters:

reader (Callable[[StateT], ValueT]) –

A function or lambda that reads the field, such as lambda state: state.volume.

Raises:

TypeError –

reader is not a function.
TerminalError –

The canvas was created without state.

Source code in xnano/canvas.py

def state_reference(
    self, reader: Callable[[StateT], ValueT]
) -> _core.StateReference[ValueT]:
    """
    A core reference for one field of the canvas's state.

    The reference can be used as an axis, a range bound or a widget parameter.

    Args:
        reader: A function or lambda that reads the field, such as
            ``lambda state: state.volume``.

    Raises:
        TypeError: ``reader`` is not a function.
        TerminalError: The canvas was created without ``state``.
    """
    if not callable(reader):
        raise TypeError(
            f'state_reference() takes a function that reads one field, but got '
            f'{reader!r}. Pass a function such as lambda state: state.volume.'
        )
    store = self._canvas._state_store
    if store is None:
        raise TerminalError(
            'This canvas has no state, so state_reference() has nothing to read. Create it with '
            'xnano.new(state=YourDataclass()).'
        )
    return _reference_for(store, reader)

Context ¶

Context(canvas: Canvas[DepsT_co, StateT_co], owner: Canvas[object, object] | Placement[object, object], hook: HookHandle[object, object], event: Event | TerminalStateChange | Frame | Update | None, core: CoreContext | None, log: ReadLog | None = None)

Bases: Generic[DepsT_co, StateT_co]

What a hook is called with.

The context carries the event and live views of where the hook is attached. Its members are read when you use them, so a context costs almost nothing to receive. A generator hook receives a new context each time it resumes, so context.mouse.position is always the newest event's.

buffer, parent and root are live objects with concrete values: context.parent.width is an int, and context.buffer has the verbs of a placement (move, up, down, left and right). On a placement or canvas themselves, parent and root are formula scopes whose members are expressions, such as placement.parent.width.

keyboard, mouse, scroll and clipboard are always there; each member is None (or 0 for the wheel) unless the event the hook is handling is of that kind. Each has get() and push(value).

Attributes:

canvas (Canvas[DepsT_co, StateT_co]) –

The root canvas the hook belongs to.
event (Event | TerminalStateChange | Frame | Update | None) –

The event, a Frame for hook(on='frame'), an Update for hook(on='tick'), a TerminalStateChange for hook(on='state'), or None when no event caused the call.
hook (HookHandle[object, object]) –

The registration, so the hook can call hook.remove().
keyboard (KeyboardInput) –

The key of the event, with key, kind and modifiers.
mouse (MouseInput) –

The mouse button or movement of the event, with position, button, kind and is_down.
scroll (ScrollInput) –

The wheel steps of the event, x and y.
clipboard (ClipboardInput) –

The pasted text of the event.
buffer (Placement[object, object] | Canvas[object, object]) –

The placement (or the canvas) the hook is attached to.
parent (Placement[object, object] | Canvas[object, object]) –

What contains the placement; the canvas itself for a hook on the canvas.
root (Canvas[DepsT_co, StateT_co]) –

The root canvas.
plugin (Plugin) –

The attachment of the hook that is running.
deps (DepsT_co) –

The dependencies given to new(deps=...).
fx (EffectController) –

Applies effects to the hook's buffer while the hook is active.
time (Time) –

The canvas's Time.
audio (AudioDevice) –

The canvas's AudioDevice.
cursor (Cursor) –

The canvas's cursor.
size (Size) –

The canvas's size in cells.
input (Input) –

The keys and mouse buttons held down right now.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=20, height=3) as canvas:
    label = canvas.write('hi', x=2)
    heard = []

    @label.hook(on='mouse', when="mouse.kind == 'press'")
    def pressed(context: xnano.Context) -> None:
        heard.append((context.mouse.position.x, context.buffer.x))

    canvas.push(Event.mouse_event(column=3, row=0, kind='press', button='left'))
    canvas.deliver_events()
    assert heard == [(3, 2)]

Create a context. The runtime does this for you; hooks receive one.

Parameters:

canvas (Canvas[DepsT_co, StateT_co]) –

The root canvas.
owner (Canvas[object, object] | Placement[object, object]) –

The canvas or placement the hook is attached to.
hook (HookHandle[object, object]) –

The hook that is called.
event (Event | TerminalStateChange | Frame | Update | None) –

The event, or None.
core (CoreContext | None) –

The runtime's context for the event, or None.
log (ReadLog | None, default: None ) –

Where to record what is read, for a component; None for a hook.

Referenced by:

API Reference xnano

Returned by:

API Reference xnano xnano.types types
- EffectController context
- HookHandle function

Used by:

API Reference xnano

Methods:

local –

Convert a cell of the screen into a cell of the hook's buffer.

Source code in xnano/context.py

def __init__(
    self,
    canvas: Canvas[DepsT_co, StateT_co],
    owner: Canvas[object, object] | Placement[object, object],
    hook: HookHandle[object, object],
    event: _core.Event | _core.TerminalStateChange | Frame | Update | None,
    core: _core.CoreContext | None,
    log: ReadLog | None = None,
) -> None:
    """
    Create a context. The runtime does this for you; hooks receive one.

    Args:
        canvas: The root canvas.
        owner: The canvas or placement the hook is attached to.
        hook: The hook that is called.
        event: The event, or ``None``.
        core: The runtime's context for the event, or ``None``.
        log: Where to record what is read, for a component; ``None`` for a hook.
    """
    self.canvas = canvas
    self._owner = owner
    self.hook = hook
    self._event = event
    self._core = core
    self._log = log

canvas `instance-attribute` ¶

canvas: Canvas[DepsT_co, StateT_co] = canvas

The root canvas the hook belongs to.

hook `instance-attribute` ¶

hook: HookHandle[object, object] = hook

The registration, so the hook can call hook.remove().

event `property` ¶

event: Event | TerminalStateChange | Frame | Update | None

The event: a core event for input, a Frame for hook(on='frame'), an Update for hook(on='tick'), a state change for hook(on='state'), or None when no event caused the call.

keyboard `property` ¶

keyboard: KeyboardInput

The key of the event; key is None unless the event is a key.

mouse `property` ¶

mouse: MouseInput

The mouse button or movement of the event; position is None for any other.

scroll `property` ¶

scroll: ScrollInput

The mouse wheel steps of the event; x and y are 0 unless it is a wheel.

clipboard `property` ¶

clipboard: ClipboardInput

The pasted text of the event; text is None unless the event is a paste.

buffer `property` ¶

buffer: Placement[object, object] | Canvas[object, object]

The placement the hook is attached to, or the canvas for a hook on the canvas.

parent `property` ¶

parent: Placement[object, object] | Canvas[object, object]

What contains the hook's placement: another placement, or the canvas.

root `property` ¶

root: Canvas[DepsT_co, StateT_co]

The root canvas.

plugin `property` ¶

plugin: Plugin

The attachment of the hook that is running.

deps `property` ¶

deps: DepsT_co

The dependencies given to new(deps=...), or None.

fx `property` ¶

fx: EffectController

Applies effects to the hook's buffer while the hook is active.

time `property` ¶

time: Time

The canvas's Time.

audio `property` ¶

audio: AudioDevice

The canvas's AudioDevice.

cursor `property` ¶

cursor: Cursor

The canvas's cursor.

size `property` ¶

size: Size

The canvas's size in cells.

input `property` ¶

input: Input

The keys and mouse buttons held down right now.

local ¶

local(point: Point) -> Point

Convert a cell of the screen into a cell of the hook's buffer.

Parameters:

point (Point) –

A cell in screen coordinates, such as context.mouse.position.

Examples:

import xnano
from xnano_core import Point

with xnano.new(width=20, height=4) as canvas:
    placement = canvas.write('hi', x=10, y=1)

    @placement.hook(on='mouse')
    def pressed(context: xnano.Context) -> None:
        if context.mouse.position is not None:
            context.local(context.mouse.position)

    assert placement.local(Point(11, 1)) == Point(1, 0)

Source code in xnano/context.py

def local(self, point: _core.Point) -> _core.Point:
    """
    Convert a cell of the screen into a cell of the hook's buffer.

    Args:
        point: A cell in screen coordinates, such as ``context.mouse.position``.

    Examples:
        ```python
        import xnano
        from xnano_core import Point

        with xnano.new(width=20, height=4) as canvas:
            placement = canvas.write('hi', x=10, y=1)

            @placement.hook(on='mouse')
            def pressed(context: xnano.Context) -> None:
                if context.mouse.position is not None:
                    context.local(context.mouse.position)

            assert placement.local(Point(11, 1)) == Point(1, 0)
        ```
    """
    point = check_point(point)
    bounds = self._owner._buffer._absolute_bounds
    return _core.Point(point.x - bounds.x, point.y - bounds.y)

Note `dataclass` ¶

Note(pitch: Pitch | tuple[Pitch, ...], beats: float = 1.0, instrument: InstrumentName = 'piano', velocity: float = 0.8, effects: tuple[PlayableEffectSpecification, ...] = (), symbol: str | None = None)

A note, or a chord, to play: a pitch, how long it lasts and how it sounds.

A note is a plain value. It needs no sound device, no canvas and not even the audio extra to be created, so a song can be defined at the top of a module and played later with play or Canvas.play. A sequence of notes plays one after another. symbol registers the note under a name, so play('kick') finds it.

Attributes:

pitch (Pitch | tuple[Pitch, ...]) –

A note name such as 'C#4', a MIDI number from 0 to 127 (60 is middle C), or a tuple of them for a chord.
beats (float) –

How long the note is held, in beats at the canvas's tempo. A beat is half a second at 120 beats per minute.
instrument (InstrumentName) –

A built-in instrument, from instrument_names.
velocity (float) –

How hard the note is played, from 0.0 to 1.0.
effects (tuple[PlayableEffectSpecification, ...]) –

Sound effects as dictionaries with a kind key, such as {'kind': 'audio.reverb', 'mix': 0.4}.
symbol (str | None) –

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

Raises:

TypeError –

The pitch is not a note name or a number, or an effect is not a dictionary.
ValueError –

The pitch is not valid, beats is not above 0, velocity is not from 0.0 to 1.0, or the instrument is unknown (checked when the audio extra is installed, and otherwise when the note is played).

Examples:

import xnano

chord = xnano.Note(('C4', 'E4', 'G4'), beats=2.0, instrument='bell')
assert chord.beats == 2.0
with xnano.new(width=8, height=1) as canvas:
    canvas.play([chord, xnano.note('C5')])
    canvas.step(delta_seconds=1.0)
    assert canvas.audio.render_sound().duration_milliseconds == 1000.0

Referenced by:

API Reference xnano
- xnano
  - note
  - play
- xnano.audio audio
  - PlaySource
  - AudioDevice play
- xnano.music music
  - note
  - play
- xnano.types types

Returned by:

API Reference xnano
- xnano
  - Note __xnano_play__
  - note
- xnano.music music
  - Note __xnano_play__
  - note

Methods:

__post_init__ –

Check the values and register the symbol.
__xnano_play__ –

Return this note, so a note is playable like any other component.

pitch `instance-attribute` ¶

pitch: Pitch | tuple[Pitch, ...]

A note name, a MIDI number, or a tuple of them for a chord.

beats `class-attribute` `instance-attribute` ¶

beats: float = 1.0

How long the note is held, in beats.

instrument `class-attribute` `instance-attribute` ¶

instrument: InstrumentName = 'piano'

The built-in instrument.

velocity `class-attribute` `instance-attribute` ¶

velocity: float = 0.8

How hard the note is played, from 0.0 to 1.0.

effects `class-attribute` `instance-attribute` ¶

effects: tuple[PlayableEffectSpecification, ...] = ()

The sound effects, as dictionaries with a kind key.

symbol `class-attribute` `instance-attribute` ¶

symbol: str | None = None

The registered symbol name, or None.

__post_init__ ¶

__post_init__() -> None

Check the values and register the symbol.

Source code in xnano/music.py

def __post_init__(self) -> None:
    """Check the values and register the symbol."""
    pitch = self.pitch
    if isinstance(pitch, (list, tuple)):
        if not pitch:
            raise ValueError(
                'A chord needs at least one pitch, but got an empty one. Pass '
                'note(("C4", "E4", "G4")) for a chord or note("C4") for one note.'
            )
        pitch = tuple(pitch)
        for each in pitch:
            _check_pitch(each)
        object.__setattr__(self, 'pitch', pitch)
    else:
        _check_pitch(pitch)
    if (
        isinstance(self.beats, bool)
        or not isinstance(self.beats, (int, float))
        or not math.isfinite(self.beats)
        or self.beats <= 0
    ):
        raise ValueError(
            f'beats must be a number above 0, but was {self.beats!r}. Use 1.0 for one '
            f'beat or 0.5 for half a beat.'
        )
    if isinstance(self.velocity, bool) or not isinstance(self.velocity, (int, float)):
        raise ValueError(
            f'velocity must be a number from 0.0 to 1.0, but was {self.velocity!r}. Use '
            f'0.8 for an ordinary note.'
        )
    if not isinstance(self.instrument, str):
        raise ValueError(
            f'instrument must be the name of a built-in instrument, such as "piano", '
            f'but was {self.instrument!r}.'
        )
    if not 0.0 <= self.velocity <= 1.0:
        raise ValueError(
            f'velocity must be from 0.0 to 1.0, but was {self.velocity!r}. Use 0.8 for '
            f'an ordinary note.'
        )
    audio = _installed_audio()
    if audio is not None:
        names = audio.instrument_names()
        if self.instrument not in names:
            raise ValueError(
                f'{self.instrument!r} is not an instrument. Use one of: '
                f'{", ".join(names)}.'
            )
    effects = effect_sequence(self.effects, 'playable')
    for effect in effects:
        normalize_effect(effect, 'playable')
    object.__setattr__(self, 'effects', effects)
    if self.symbol is not None:
        symbols.register(self.symbol, self)

__xnano_play__ ¶

__xnano_play__(context: Context) -> Note

Return this note, so a note is playable like any other component.

Source code in xnano/music.py

def __xnano_play__(self, context: Context) -> Note:
    """Return this note, so a note is playable like any other component."""
    return self

Pixel `dataclass` ¶

Pixel(preset_or_character: PixelPreset | str = 'block', *, foreground: ColorValue | None = None, background: ColorValue | None = None, symbol: str | None = None)

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.

Referenced by:

Returned by:

API Reference xnano xnano.region region Region __getitem__

Used by:

API Reference xnano xnano.region region Region __setitem__

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.

Source code in xnano/pixel.py

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 `instance-attribute` ¶

character: str

The glyph drawn in the cell or dot.

foreground `instance-attribute` ¶

foreground: ColorValue | None

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

background `instance-attribute` ¶

background: ColorValue | None

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

symbol `instance-attribute` ¶

symbol: str | None

The registered symbol name, or None.

cell ¶

cell() -> 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.

Source code in xnano/pixel.py

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__() -> str

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

Source code in xnano/pixel.py

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

__xnano_render__ ¶

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

Return a buffer of one cell that shows the pixel.

Source code in xnano/pixel.py

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

Terminal ¶

Terminal(*, width: int | str | None, height: int | str | None, fps: float, bpm: float, is_realtime: bool, deps: object, state: object, title: str | None, gates: Mapping[str, object], appearance: Mapping[str, object], effects: Sequence[RenderableEffectSpecification], enclosing: Canvas[object, object] | None = None, layout: CanvasLayout = 'overlay', edges: EdgeBehavior = 'clip')

Bases: Canvas[DepsT, StateT]

A canvas that draws on your screen and reads your keyboard and mouse.

A canvas becomes a terminal when it is opened, with open or Canvas.open: it is the same object, and isinstance(canvas, xnano.Terminal) is how to ask whether a canvas is on the screen. It has every member of Canvas. It runs by itself: opening it starts a loop on a thread of its own, and everything you write, remove or draw appears the moment it is declared, however slowly the rest of your program runs, because declaring only changes buffers and the loop draws them. A program has one screen, so only one terminal is open at a time.

Attributes:

is_closed (bool) –

Whether the terminal has been closed, or its loop has ended.
is_running (bool) –

Whether the loop is running and has not been asked to end.

Examples:

with xnano.open(width=20, height=2) as terminal:
    terminal.write('hello')
    assert isinstance(terminal, xnano.Terminal)
    terminal.run(quit_on='q')

Create a canvas. Use new instead of calling this.

Parameters:

width (int | str | None) –

The width in cells or as a percentage of the window, or None for 80.
height (int | str | None) –

The height in cells or as a percentage of the window, or None for 24.
fps (float) –

The most frames drawn per second.
bpm (float) –

Beats per minute.
is_realtime (bool) –

Whether the canvas runs on the wall clock, on a thread of its own.
deps (object) –

The dependencies, or the unset marker when none were given.
state (object) –

A dataclass instance the canvas keeps and validates, or the unset marker.
title (str | None) –

The window title, or None.
gates (Mapping[str, object]) –

The input gates that were given, by name.
appearance (Mapping[str, object]) –

The appearance keywords of the canvas itself, by name.
effects (Sequence[RenderableEffectSpecification]) –

Effects to apply to the canvas, as dictionaries with a kind key.
enclosing (Canvas[object, object] | None, default: None ) –

The canvas whose with block this one was created in, which its sizes are measured in and which closes it, or None.
layout (CanvasLayout, default: 'overlay' ) –

How the canvas places what is written on it.
edges (EdgeBehavior, default: 'clip' ) –

What content written on the canvas does at the edges of its area.

Referenced by:

API Reference xnano
- xnano
  - Canvas open
  - Terminal open
  - open
- xnano.canvas canvas Canvas open
- xnano.terminal terminal
  - Terminal open
  - open
Getting Started Put it on your screen

Returned by:

API Reference xnano
- xnano
  - Canvas open
  - Terminal open
  - open
- xnano.canvas canvas Canvas open
- xnano.terminal terminal
  - Terminal open
  - open

Methods:

__setattr__ –

Set an attribute, or raise AttributeError for an unknown public name.
bold –

Make the text bold, or undo it with False; the same as setting is_bold.
dim –

Dim the text, or undo it with False; the same as setting is_dim.
italic –

Make the text italic, or undo it with False; the same as setting is_italic.
underline –

Underline the text, or undo it with False; the same as setting is_underlined.
blink –

Make the text blink, or undo it with False; the same as setting is_blinking.
reverse –

Swap the foreground and background, or undo it with False; the same as setting is_reversed.
hidden –

Hide the text, or undo it with False; the same as setting is_hidden.
crossed_out –

Strike the text through, or undo it with False; the same as setting is_crossed_out.
hook –

Call a function when something happens on this canvas or placement.
__new__ –

Refuse a direct call: a canvas is created with xnano.new.
open –

Put this canvas on your screen, and return it as a Terminal.
close –

Release everything the canvas holds, and give the screen back if it has one.
local –

Convert a cell of the screen into a cell of this canvas.
move –

Move a canvas that is written into another one by a number of cells along each axis.
up –

Move a written canvas up by count rows; see move.
down –

Move a written canvas down by count rows; see move.
left –

Move a written canvas left by count columns; see move.
right –

Move a written canvas right by count columns; see move.
new –

Create a canvas inside this one and draw it here at once, at the top-left corner.
write –

Put something on the canvas: text, a widget, a buffer, another canvas or an image.
clear –

Erase everything written or drawn directly on the canvas's cells.
update –

Change the canvas's own cells with operations, styles or effects.
__or__ –

Apply an operation, customization or style with canvas | operation.
__ior__ –

Apply an operation, customization or style in place with canvas |= operation.
inspect –

Evaluate an expression against the canvas and return its value.
iter –

Iterate over the canvas's frames, drawing between them; pass count= or seconds=,
step –

Move time by delta_seconds, one frame by default, and draw exactly one frame.
deliver_events –

Deliver pushed events to their hooks and draw a frame, without moving time.
stop –

Freeze time: the same as Time.stop.
resume –

Let time run on from where stop froze it.
quit –

Ask the canvas's loop to end.
run –

Wait until the canvas's loop ends.
wait_for_key –

Wait until a key is pressed, and return its name.
prompt –

Prompt for a line of text, and return what was typed.
render –

Draw the current frame and return it, without a screen.
push –

Deliver an event to the canvas as if it had been typed, clicked or reported.
play –

Play a note, a sound, a symbol name, a melody or a sequence of those, and return at once.
state_reference –

A core reference for one field of the canvas's state.

Source code in xnano/canvas.py

def __init__(
    self,
    *,
    width: int | str | None,
    height: int | str | None,
    fps: float,
    bpm: float,
    is_realtime: bool,
    deps: object,
    state: object,
    title: str | None,
    gates: Mapping[str, object],
    appearance: Mapping[str, object],
    effects: Sequence[RenderableEffectSpecification],
    enclosing: Canvas[object, object] | None = None,
    layout: CanvasLayout = 'overlay',
    edges: EdgeBehavior = 'clip',
) -> None:
    """
    Create a canvas. Use [`new`][xnano.new] instead of calling this.

    Args:
        width: The width in cells or as a percentage of the window, or ``None`` for 80.
        height: The height in cells or as a percentage of the window, or ``None`` for 24.
        fps: The most frames drawn per second.
        bpm: Beats per minute.
        is_realtime: Whether the canvas runs on the wall clock, on a thread of its own.
        deps: The dependencies, or the unset marker when none were given.
        state: A dataclass instance the canvas keeps and validates, or the unset marker.
        title: The window title, or ``None``.
        gates: The input gates that were given, by name.
        appearance: The appearance keywords of the canvas itself, by name.
        effects: Effects to apply to the canvas, as dictionaries with a ``kind`` key.
        enclosing: The canvas whose ``with`` block this one was created in, which its
            sizes are measured in and which closes it, or ``None``.
        layout: How the canvas places what is written on it.
        edges: What content written on the canvas does at the edges of its area.
    """
    super().__init__()
    self._canvas = self
    self._root_canvas = self
    self._lock = threading.RLock()
    self._root = _core.Buffer()
    self._buffer = self._root
    self._fps = fps
    self._bpm = bpm
    self._is_realtime = is_realtime
    self._requested_width = width
    self._requested_height = height
    self._deps_given = deps is not _UNSET
    self._deps = cast('DepsT', None if deps is _UNSET else deps)
    self._state_given = state is not _UNSET
    self._title = title
    self._gates: dict[str, object] = dict(gates)
    self._resolved_gates: dict[str, object] = {}
    self._appearance = (
        Appearance(**cast('dict[str, object]', _plain_appearance(appearance)))  # type: ignore[arg-type]
        if appearance
        else None
    )
    self._decorated: Decorated | None = None
    self._dirty_looks: dict[int, _Looked] = {}
    self._placements: list[Placement[DepsT, StateT]] = []
    self._ledger: list[_Registration] = []
    self._effects: list[
        tuple[Customization, Canvas[object, object] | Placement[object, object]]
    ] = []
    self._frame_listeners: dict[int, Callable[[FrameContext], None]] = {}
    self._frame_listener_tokens = itertools.count()
    self._frame_demand = 0
    self._frame_registration: _Registration | None = None
    self._size_hook: _core.Hook | None = None
    self._parent_placement: Placement[object, object] | None = None
    self._children: list[Canvas[object, object]] = []
    self._enclosing: weakref.ref[Canvas[object, object]] | None = None
    self._enclosing_size: tuple[int, int] | None = None
    self._nested_canvases: list[weakref.ref[Canvas[object, object]]] = []
    self._areas: dict[int, Placement[object, object]] = {}
    self._is_hidden_until_written = False
    self._layout: CanvasLayout = layout
    self._edges: EdgeBehavior = edges
    self._slots: list[
        tuple[Placement[object, object] | None, _core.Buffer, _core.SizeRule]
    ] = []
    self._is_layout_pending = False
    self._pending_layouts: dict[int, Canvas[object, object]] = {}
    if enclosing is not None:
        self._enclosing = weakref.ref(enclosing)
        self._enclosing_size = (enclosing.width, enclosing.height)
        with enclosing._lock:
            enclosing._nested_canvases.append(
                weakref.ref(cast('Canvas[object, object]', self))
            )
    self._is_closed = False
    self._is_finalized = False
    self._stop_requested = threading.Event()
    self._failure: BaseException | None = None
    self._is_failure_reported = False
    self._failure_report = ''
    self._moved = 0
    self._carried: dict[str, object] | None = None
    self._cursor_follow: tuple[_core.Buffer, int, int] | None = None
    self._state_namespace: StateNamespace | None = None
    self._state_fields: dict[str, object] = {}
    self._state_store: _core.TerminalStateStore | None = None
    if state is not _UNSET and state is not None:
        self._state_store = _prepare_state(cast('DataclassInstance', state))
        self._state_fields = _state_field_types(cast('DataclassInstance', state))
    self._state_followers: _StateFollowers | None = None
    self._state_subscription: _core.TerminalStateSubscription | None = None
    self._state_hook: _core.Hook | None = None
    self._state_marked: dict[_StateFollower, _core.TerminalStateChange] = {}
    self._internal_revisions: deque[int] = deque(maxlen=16)
    self._namespace_identifiers = itertools.count(1)
    self._active_run_by_thread = threading.local()
    self._images: dict[int, ImageSource] = {}
    # Only placements with a formula or a range need looking at before each frame.
    self._dynamic: dict[int, Placement[DepsT, StateT]] = {}
    self._time = Time(cast('Canvas[object, object]', self))
    self._cursor_view = Cursor(cast('Canvas[object, object]', self))
    self.output = Output(cast('Canvas[object, object]', self))
    self._audio: AudioDevice | None = None
    self._input: Input | None = None
    self._runtime_object: _core.Runtime | None = None
    self._clock: _core.Clock | None = None
    self._cursor: _core.Cursor | None = None
    self._input_state: _core.InputState | None = None
    self._pushed_pointer: tuple[tuple[int, int], object, int] | None = None
    self._size = _core.Size(0, 0)
    self._previous_chain = tuple(
        reference for reference in _active_canvas.get() if reference() is not None
    )
    _active_canvas.set(
        (weakref.ref(cast('Canvas[object, object]', self)), *self._previous_chain)
    )
    self._host: _Host
    columns, rows = _canvas_size(width, height, self._enclosing_size)
    interval_milliseconds = max(1, round(1000.0 / fps))

    def create_runtime() -> _core.Runtime:
        runtime = _core.Runtime.offscreen(
            width=columns,
            height=rows,
            frame_interval_milliseconds=interval_milliseconds,
            clock=_core.Clock.monotonic() if is_realtime else None,
        )
        if title is not None:
            runtime.title = title
        return runtime

    try:
        if is_realtime:
            _ThreadHost(cast('Canvas[object, object]', self), create_runtime)
        else:
            _InlineHost(cast('Canvas[object, object]', self), create_runtime)
    except BaseException:
        _active_canvas.set(self._previous_chain)
        self._finalize()
        raise
    try:
        if effects:
            apply_effects(cast('Canvas[object, object]', self), effects)
    except BaseException:
        self.close(raise_failure=False)
        raise
    self._renderable_effects = RenderableEffects(cast('Canvas[object, object]', self))
    self._seal()

region `property` ¶

region: Region

The cells of the canvas as a Region: read and write canvas.region[x, y].

The default resolution is one cell. canvas.region.half_blocks addresses two pixels per cell and canvas.region.braille eight dots.

Examples:

import xnano

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

color `property` ¶

color: Colors

The colors: color.fg for the text and color.bg for what is behind it.

Each is a ColorSlot. Assign a color name, an (red, green, blue) tuple, a Color or another slot; 'reset' clears the color.

Examples:

import xnano

with xnano.new(width=10, height=3) as canvas:
    label = canvas.write('hi')
    label.color.fg = 'red'
    label.color.bg = (0, 0, 80)
    label.color.bg.lighten(0.1)
    assert label.color.fg.value == xnano.Color('red')

border `property` `writable` ¶

border: BorderAppearance

The border: its kind, a setting for each side, its color and its title.

Assign 'plain', 'rounded', 'double' or 'thick' to draw a border on every side, True for 'plain' and False to remove it. It works on any content, not only on text.

The border, padding and margin are drawn around the content, so the placement grows by the cells they take. A widget with no size of its own is shrunk to fit its parent, border included.

Examples:

import xnano

with xnano.new(width=12, height=5) as canvas:
    card = canvas.write('hi', border='rounded')
    card.border.top = 'double'
    card.border.left = False
    card.border.color = 'cyan'
    card.border = False
    assert not card.border

padding `property` `writable` ¶

padding: PaddingAppearance

The space between the border and the content, edge by edge.

Assign a number of cells, a percentage such as '10%' or a dictionary such as {'vertical': 1, 'horizontal': 2}, or set one edge with padding.left = 2.

margin `property` `writable` ¶

margin: MarginAppearance

The transparent space outside the border, edge by edge, set like padding.

is_bold `property` `writable` ¶

is_bold: bool

Whether the text is bold.

is_dim `property` `writable` ¶

is_dim: bool

Whether the text is dimmed.

is_italic `property` `writable` ¶

is_italic: bool

Whether the text is italic.

is_underlined `property` `writable` ¶

is_underlined: bool

Whether the text is underlined.

is_blinking `property` `writable` ¶

is_blinking: bool

Whether the text blinks.

is_reversed `property` `writable` ¶

is_reversed: bool

Whether foreground and background are swapped.

is_hidden `property` `writable` ¶

is_hidden: bool

Whether the text is hidden.

is_crossed_out `property` `writable` ¶

is_crossed_out: bool

Whether the text is struck through.

output `instance-attribute` ¶

output: Output = Output(cast('Canvas[object, object]', self))

The canvas's drawn frames and captured text.

is_closed `property` ¶

is_closed: bool

Whether the canvas has been torn down: closed, or its loop has ended.

is_running `property` ¶

is_running: bool

Whether the canvas is open and its loop has not been asked to end.

core_buffer `property` ¶

core_buffer: Buffer

The core buffer the canvas draws, as large as the canvas.

Everything you write is a child of this buffer, and everything drawn directly on the canvas is stored in it. A canvas with a border, padding or margin draws them around a buffer of its own; this is the buffer inside them.

parent `property` ¶

parent: ParentExpressionScope

Symbolic expressions for the parent container's width, height and size.

root `property` ¶

root: RootExpressionScope

Symbolic expressions for the root canvas's width, height, size and time.

size `property` ¶

size: Size

The size of the canvas in cells.

width `property` ¶

width: int

The width of the canvas in cells.

height `property` ¶

height: int

The height of the canvas in cells.

x `property` ¶

x: int

The column of the canvas: 0, unless it was written into another canvas.

y `property` ¶

y: int

The row of the canvas: 0, unless it was written into another canvas.

fps `property` ¶

fps: float

The most frames drawn per second, and the rate iter aims for.

Referenced by:

API Reference xnano xnano.time time Time

bpm `property` `writable` ¶

bpm: float

Beats per minute: the length of a beat for beat timers, notes and melodies.

It is 120 unless new(bpm=...) said otherwise, and it can change while things are playing; the change applies from the next beat.

Raises:

ValueError –

The tempo is not above 0 and at most 600000.

Referenced by:

API Reference xnano xnano.audio audio AudioDevice

deps `property` ¶

deps: DepsT

The dependencies given to new(deps=...), or None. Hooks read them.

title `property` `writable` ¶

title: str | None

The window title last set on this canvas.

Assign a single line of printable text to set the title of the window a canvas on the screen draws in, or None to clear it. A canvas without a screen keeps the value and shows it when it is opened.

time `property` ¶

time: Time

The canvas's Time: how long it has run, stopping, and formulas.

Referenced by:

API Reference xnano xnano.time time Time

cursor `property` ¶

cursor: Cursor

The canvas's Cursor.

A canvas has exactly one cursor. Set its position (a cell, or None to hide it), shape, is_blinking and is_visible, move it with up, down, left, right and move, or follow a placement. It can be changed from any thread, and on the screen the cursor you had before is restored when the canvas closes.

Examples:

import xnano

with xnano.new(width=10, height=2) as canvas:
    canvas.cursor.position = (3, 0)
    canvas.cursor.shape = 'bar'
    assert canvas.cursor.position.x == 3

Referenced by:

API Reference xnano xnano.cursor cursor Cursor

layout `property` ¶

layout: CanvasLayout

How the canvas places what is written on it, chosen when the canvas is created.

'overlay' places every piece on its own over the whole canvas. 'column' stacks the pieces from top to bottom in the order they are written, and 'row' from left to right. Each piece then takes a slot: one with a size on the stacking axis (height in a column, width in a row, in cells or as a percentage) gets exactly that, and the others share what is left equally. Inside its slot a piece is positioned as on any canvas, so y='center' and y='50%' are measured in the slot. Removing a piece gives its slot back. A canvas created inside the with block of a stacking canvas takes a slot only once it is written.

Examples:

import xnano

with xnano.new(width=20, height=10, layout='column') as terminal:
    terminal.write('top half', y='center')
    panel = terminal.new(height='50%')
    panel.write('bottom half')
    rows = terminal.render().splitlines()
    assert (rows[2], rows[5]) == ('top half', 'bottom half')

edges `property` `writable` ¶

edges: EdgeBehavior

What content written on the canvas does at the edges of its area, unless given its own.

'clip' lets it move past the edge, where it is not drawn; 'stop' holds it inside its area when it moves; 'wrap' continues text on the next rows of its area. A piece written with edges=... keeps its own; see Placement.edges.

Raises:

ValueError –

The value is not 'clip', 'stop' or 'wrap'.

audio `property` ¶

audio: AudioDevice

The canvas's AudioDevice: notes, melodies, sounds and the microphone.

It needs the optional xnano-audio package, which is imported the first time this is read.

Raises:

ImportError –

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

Referenced by:

API Reference xnano xnano.audio audio AudioDevice

fx `property` ¶

fx: RenderableEffects

The visual effects of the canvas itself, one method for each effect.

canvas.fx.fade_to(background='navy') starts a fade over the whole canvas at once, and canvas.fx.clear() stops what was started here. A placement has its own fx, and the sound effects of what the canvas plays are canvas.audio.fx. See RenderableEffects.

Examples:

import xnano

with xnano.new('hello', width=8, height=1) as canvas:
    canvas.fx.dissolve(duration_milliseconds=300)
    assert len(canvas.fx.active) == 1

Referenced by:

API Reference xnano xnano.types types RenderableEffects

input `property` ¶

input: Input

The keys held down right now, for programs that poll instead of listening.

Read it anywhere, from any thread. A canvas opened with keyboard='release_events' knows exactly when a key is let go.

Referenced by:

API Reference xnano xnano.input input Input

state `class-attribute` `instance-attribute` ¶

state = _StateAccessor()

The canvas's state: values that hooks and your code share, read and written by path.

canvas.state.get('player.score') reads a value and canvas.state.push('player.score', 3) writes one; see StateNamespace for the path rules. A canvas created with new(state=Settings()) also gives the fields of the dataclass as attributes with their declared types, so canvas.state.volume is an int for a field declared volume: int; a write is checked against the field's type. A type checker sees get and push only on a canvas without a state dataclass, but both exist on every canvas.

The state can be used from any thread. A write updates every expression that reads the field and draws a frame.

Referenced by:

API Reference xnano xnano.placement placement Placement state

setattr ¶

__setattr__(name: str, value: object) -> None

Set an attribute, or raise AttributeError for an unknown public name.

Source code in xnano/_attributes.py

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)

bold ¶

bold(value: bool = True) -> Self

Make the text bold, or undo it with False; the same as setting is_bold.

Parameters:

value (bool, default: True ) –

Whether the text is bold.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Examples:

import xnano

with xnano.new(width=12, height=1) as canvas:
    title = canvas.write('Ready').bold().underline()
    assert title.is_bold and title.is_underlined
    title.bold(False)
    assert not title.is_bold

Source code in xnano/appearance.py

def bold(self, value: bool = True) -> Self:
    """
    Make the text bold, or undo it with ``False``; the same as setting ``is_bold``.

    Args:
        value: Whether the text is bold.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.

    Examples:
        ```python
        import xnano

        with xnano.new(width=12, height=1) as canvas:
            title = canvas.write('Ready').bold().underline()
            assert title.is_bold and title.is_underlined
            title.bold(False)
            assert not title.is_bold
        ```
    """
    self.is_bold = value
    return self

dim ¶

dim(value: bool = True) -> Self

Dim the text, or undo it with False; the same as setting is_dim.

Parameters:

value (bool, default: True ) –

Whether the text is dimmed.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def dim(self, value: bool = True) -> Self:
    """
    Dim the text, or undo it with ``False``; the same as setting ``is_dim``.

    Args:
        value: Whether the text is dimmed.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_dim = value
    return self

italic ¶

italic(value: bool = True) -> Self

Make the text italic, or undo it with False; the same as setting is_italic.

Parameters:

value (bool, default: True ) –

Whether the text is italic.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def italic(self, value: bool = True) -> Self:
    """
    Make the text italic, or undo it with ``False``; the same as setting ``is_italic``.

    Args:
        value: Whether the text is italic.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_italic = value
    return self

underline ¶

underline(value: bool = True) -> Self

Underline the text, or undo it with False; the same as setting is_underlined.

Parameters:

value (bool, default: True ) –

Whether the text is underlined.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def underline(self, value: bool = True) -> Self:
    """
    Underline the text, or undo it with ``False``; the same as setting ``is_underlined``.

    Args:
        value: Whether the text is underlined.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_underlined = value
    return self

blink ¶

blink(value: bool = True) -> Self

Make the text blink, or undo it with False; the same as setting is_blinking.

Parameters:

value (bool, default: True ) –

Whether the text blinks.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def blink(self, value: bool = True) -> Self:
    """
    Make the text blink, or undo it with ``False``; the same as setting ``is_blinking``.

    Args:
        value: Whether the text blinks.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_blinking = value
    return self

reverse ¶

reverse(value: bool = True) -> Self

Swap the foreground and background, or undo it with False; the same as setting is_reversed.

Parameters:

value (bool, default: True ) –

Whether foreground and background are swapped.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def reverse(self, value: bool = True) -> Self:
    """
    Swap the foreground and background, or undo it with ``False``; the same as setting ``is_reversed``.

    Args:
        value: Whether foreground and background are swapped.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_reversed = value
    return self

hidden ¶

hidden(value: bool = True) -> Self

Hide the text, or undo it with False; the same as setting is_hidden.

Parameters:

value (bool, default: True ) –

Whether the text is hidden.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def hidden(self, value: bool = True) -> Self:
    """
    Hide the text, or undo it with ``False``; the same as setting ``is_hidden``.

    Args:
        value: Whether the text is hidden.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_hidden = value
    return self

crossed_out ¶

crossed_out(value: bool = True) -> Self

Strike the text through, or undo it with False; the same as setting is_crossed_out.

Parameters:

value (bool, default: True ) –

Whether the text is struck through.

Returns:

Self –

This canvas or placement, so calls can chain.

Raises:

TypeError –

value is not True or False.

Source code in xnano/appearance.py

def crossed_out(self, value: bool = True) -> Self:
    """
    Strike the text through, or undo it with ``False``; the same as setting ``is_crossed_out``.

    Args:
        value: Whether the text is struck through.

    Returns:
        This canvas or placement, so calls can chain.

    Raises:
        TypeError: ``value`` is not ``True`` or ``False``.
    """
    self.is_crossed_out = value
    return self

hook ¶

hook(function: Hook[DepsT, StateT], /, *, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> HookHandle[DepsT, StateT]

hook(*, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]]

hook(function: Hook[DepsT, StateT] | None = None, /, *, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> HookHandle[DepsT, StateT] | Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]]

Call a function when something happens on this canvas or placement.

on says what to listen to. A hook without on hears every input event. A mouse, scroll or drag hook on a placement hears only the pointer inside the placement, and a press inside holds the pointer for the hook until the button is released. A pointer hook that matches an event stops it from reaching the parent; a hook that does not match lets it through. Keys are not consumed: while nothing has focus, every key hook hears a key.

hook(function, ...) attaches one function, and @target.hook(...) decorates the function that follows. A hook function may be a generator that receives a new context at each bare yield: write context = yield. A drag is a loop that runs while context.mouse.is_down.

every and after are seconds for on='tick' and beats for on='beat': every=2 means 2 seconds for a tick hook and 2 beats for a beat hook. On a canvas from new() a hook that is due several times in one step runs once for each interval, up to 100,000 times in one step; the intervals that remain run in the steps that follow. The function's return value is ignored, unless it is an operation, a style or an effect, which is applied to this target.

Parameters:

function (Hook[DepsT, StateT] | None, default: None ) –

The function to call with a Context, or a function with no parameters, which is called without it.
on (HookKind | None, default: None ) –

What to listen to: 'frame', 'tick', 'beat', 'key', 'mouse', 'scroll', 'drag', 'paste', 'focus', 'resize', 'state' or 'custom'. See HookKind.
when (When[DepsT, StateT] | None, default: None ) –

A condition that must hold: an expression, a function of the context, or a string. See When. A string tells xnano which input the hook needs, so the mouse, scroll and key-release gates it reads are turned on when the canvas opens. An expression or a function does not, so a condition that reads Mouse, Scroll or key releases needs the gate set on new() or open() yourself: mouse=True, scroll=True or keyboard='release_events'. A comparison with an input the event does not carry, such as keyboard.key on a paste, does not hold; != is one of them, so keyboard.key != 'q' hears only key events. not and not in negate the whole comparison, so not keyboard.key == 'q' and keyboard.key not in ['q'] also hold for events that have no key.
every (float | None, default: None ) –

Repeat every this many seconds ('tick') or beats ('beat').
after (float | None, default: None ) –

Run once after this many seconds ('tick') or beats ('beat').
keys (KeyName | Sequence[KeyName] | None, default: None ) –

The key or keys an on='key' hook reacts to, such as 'q' or 'ctrl+s'. A key hook with keys hears presses and repeats; omit them and test keyboard.kind to hear releases.
requires_deps (bool, default: False ) –

Whether the hook needs the dependencies given to new(deps=...).

Returns:

HookHandle[DepsT, StateT] | Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]] –

The hook, whose remove stops it; or, without a function, the decorator.

Raises:

ValueError –

The combination of arguments does not make sense, a key name is unknown, or a when string is not a condition. The message says what to write instead.
TypeError –

on is not text, when is a plain bool, or the function is not callable with a context, or is an async function.
TerminalError –

requires_deps is true and the canvas was created without deps, or the canvas is on a screen with an input gate this hook needs turned off.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:
    heard = []

    @canvas.hook(on='key', keys=['q', 'escape'])
    def leave(context: xnano.Context) -> None:
        heard.append(context.keyboard.key)

    @canvas.hook(on='tick', every=0.5)
    def blink(context: xnano.Context) -> None:
        heard.append('tick')

    canvas.push(Event.key_press('q'))
    canvas.step(delta_seconds=1.0)
    assert heard == ['q', 'tick', 'tick']

Referenced by:

Source code in xnano/_hooks.py

def hook(
    self,
    function: Hook[DepsT, StateT] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[DepsT, StateT] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> (
    HookHandle[DepsT, StateT]
    | Callable[[Hook[DepsT, StateT]], HookHandle[DepsT, StateT]]
):
    """
    Call a function when something happens on this canvas or placement.

    ``on`` says what to listen to. A hook without ``on`` hears every input event. A mouse,
    scroll or drag hook on a placement hears only the pointer inside the placement, and a
    press inside holds the pointer for the hook until the button is released. A pointer hook
    that matches an event stops it from reaching the parent; a hook that does not match lets
    it through. Keys are not consumed: while nothing has focus, every key hook hears a key.

    ``hook(function, ...)`` attaches one function, and ``@target.hook(...)`` decorates the
    function that follows. A hook function may be a generator that receives a new context
    at each bare ``yield``: write ``context = yield``. A drag is a loop that runs while
    ``context.mouse.is_down``.

    ``every`` and ``after`` are seconds for ``on='tick'`` and beats for ``on='beat'``:
    ``every=2`` means 2 seconds for a tick hook and 2 beats for a beat hook. On a canvas
    from ``new()`` a hook that is due several times in one ``step`` runs once for each
    interval, up to 100,000 times in one step; the intervals that remain run in the steps
    that follow. The function's return value is ignored, unless it is an operation, a
    style or an effect, which is applied to this target.

    Args:
        function: The function to call with a [`Context`][xnano.context.Context], or a
            function with no parameters, which is called without it.
        on: What to listen to: ``'frame'``, ``'tick'``, ``'beat'``, ``'key'``, ``'mouse'``,
            ``'scroll'``, ``'drag'``, ``'paste'``, ``'focus'``, ``'resize'``, ``'state'``
            or ``'custom'``. See [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold: an expression, a function of the context, or a
            string. See [`When`][xnano.types.When]. A string tells xnano which input
            the hook needs, so the mouse, scroll and key-release gates it reads are
            turned on when the canvas opens. An expression or a function does not, so a
            condition that reads ``Mouse``, ``Scroll`` or key releases needs the gate set
            on ``new()`` or ``open()`` yourself: ``mouse=True``, ``scroll=True`` or
            ``keyboard='release_events'``. A comparison with an input the event does not
            carry, such as ``keyboard.key`` on a paste, does not hold; ``!=`` is one of
            them, so ``keyboard.key != 'q'`` hears only key events. ``not`` and ``not in``
            negate the whole comparison, so ``not keyboard.key == 'q'`` and
            ``keyboard.key not in ['q']`` also hold for events that have no key.
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds (``'tick'``) or beats (``'beat'``).
        keys: The key or keys an ``on='key'`` hook reacts to, such as ``'q'`` or
            ``'ctrl+s'``. A key hook with keys hears presses and repeats; omit them and
            test ``keyboard.kind`` to hear releases.
        requires_deps: Whether the hook needs the dependencies given to
            ``new(deps=...)``.

    Returns:
        The hook, whose ``remove`` stops it; or, without a function, the decorator.

    Raises:
        ValueError: The combination of arguments does not make sense, a key name is
            unknown, or a ``when`` string is not a condition. The message says what to
            write instead.
        TypeError: ``on`` is not text, ``when`` is a plain ``bool``, or the function is not callable with a
            context, or is an ``async`` function.
        TerminalError: ``requires_deps`` is true and the canvas was created without
            ``deps``, or the canvas is on a screen with an input gate this hook needs
            turned off.

    Examples:
        ```python
        import xnano
        from xnano_core import Event

        with xnano.new(width=8, height=1) as canvas:
            heard = []

            @canvas.hook(on='key', keys=['q', 'escape'])
            def leave(context: xnano.Context) -> None:
                heard.append(context.keyboard.key)

            @canvas.hook(on='tick', every=0.5)
            def blink(context: xnano.Context) -> None:
                heard.append('tick')

            canvas.push(Event.key_press('q'))
            canvas.step(delta_seconds=1.0)
            assert heard == ['q', 'tick', 'tick']
        ```
    """
    canvas = self._canvas
    self._require_attached()
    owner = cast('_Hooked[object, object]', self)
    normalized_keys = _check_hook_arguments(owner, on, every, after, keys)
    compiled = compile_when(when)
    if on is None and not compiled.is_opaque and compiled.reads:
        if not compiled.reads & {'keyboard', 'mouse', 'scroll'}:
            raise ValueError(
                'when reads time, the size of the parent or deps, but a hook with no on= is '
                'only checked when an input event arrives. Add on="tick" or '
                'on="frame" so it is checked as time passes, or read an input in the '
                'condition.'
            )
    if requires_deps and not canvas._deps_given:
        raise TerminalError(
            'This hook needs dependencies (requires_deps=True), but the canvas has none '
            'yet. Give them when you create the canvas: xnano.new(deps=your_dependencies) '
            'or xnano.open(deps=your_dependencies), or open the canvas with '
            'canvas.open(deps=your_dependencies) before you register this hook.'
        )

    def attach(
        callback: Hook[DepsT, StateT],
    ) -> HookHandle[DepsT, StateT]:
        return self._attach_hook(
            cast(
                'Callable[[Context[DepsT, StateT]], object]',
                _check_hook_function(callback),
            ),
            on=on,
            when=compiled,
            every=every,
            after=after,
            keys=normalized_keys,
        )

    if function is None:
        return attach
    return attach(function)

new ¶

__new__(*arguments: object, **keywords: object) -> Self

Refuse a direct call: a canvas is created with xnano.new.

Source code in xnano/canvas.py

def __new__(cls, *arguments: object, **keywords: object) -> Self:
    """Refuse a direct call: a canvas is created with ``xnano.new``."""
    if arguments or 'is_realtime' not in keywords:
        raise TypeError(
            f'{cls.__name__} is not created by calling it. Create a canvas with '
            f'xnano.new(...), or put one on the screen with xnano.open(...).'
        )
    return super().__new__(cls)

open ¶

open(*, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, **settings: Unpack[OpenSettings]) -> Terminal[DepsT, StateT]

Put this canvas on your screen, and return it as a Terminal.

The same object is returned: after this, isinstance(canvas, xnano.Terminal) is true. From then on it runs by itself on a thread of its own and on the wall clock, which continues from the time the canvas had: elapsed time, the frame count, every and after timers and a stopped clock carry over, and so do the cursor, the title, everything written and every hook. Effects that were running start again from their beginning, and keyboard focus and a captured pointer are released.

width and height are the size of the canvas: the ones given here, else the ones given to new(), draw in a region of that size below the cursor; a canvas created without a size, or with '100%' for both, fills the whole window. A percentage such as '50%' is a share of the window when the canvas is opened. Any other keyword of new() except realtime may be given and applies before the canvas is shown; a gate given here wins over the one given to new(). title is the window title.

Parameters:

title (str | None, default: None ) –

The window title; None keeps the canvas's title.
width (int | Percentage | str | None, default: None ) –

The width of the region to draw in: cells, or a percentage of the window.
height (int | Percentage | str | None, default: None ) –

The height of the region to draw in: cells, or a percentage of the window.
settings (Unpack[OpenSettings], default: {} ) –

Gates, appearance keywords, fps, bpm, effects, and deps and state for a canvas that was created without them; see OpenSettings.

Returns:

Terminal[DepsT, StateT] –

This canvas, now attached to the screen.

Raises:

TerminalAlreadyOpenError –

Another canvas is already on the screen.
TerminalError –

This canvas is already on the screen, was written into another canvas, has a hook that needs a gate given as False, or there is no terminal to draw on; the canvas stays as it was.
TypeError –

realtime was given, deps or state that the canvas already has, or an effect that is not a visual effect dictionary.
ValueError –

A width was given without a height, or a value is out of range.

Examples:

with xnano.new(width=40, height=5) as canvas:
    canvas.write('hello', border='rounded')
    canvas.step()
    canvas.open(mouse=True)        # now a xnano.Terminal, 40 by 5 below the prompt
    canvas.run(quit_on='q')

Referenced by:

API Reference xnano
- xnano
  - Canvas
  - Terminal
  - new
  - open
- xnano.canvas canvas
  - Canvas
  - new
- xnano.terminal terminal
  - Terminal
  - open
- xnano.types types OpenSettings

Source code in xnano/canvas.py

def open(
    self,
    *,
    title: str | None = None,
    width: int | Percentage | str | None = None,
    height: int | Percentage | str | None = None,
    **settings: Unpack[OpenSettings],
) -> Terminal[DepsT, StateT]:
    """
    Put this canvas on your screen, and return it as a [`Terminal`][xnano.Terminal].

    The same object is returned: after this, ``isinstance(canvas, xnano.Terminal)`` is
    true. From then on it runs by itself on a thread of its own and on the wall clock, which
    continues from the time the canvas had: elapsed time, the frame count, ``every`` and
    ``after`` timers and a stopped clock carry over, and so do the cursor, the title,
    everything written and every hook. Effects that were running start again from their
    beginning, and keyboard focus and a captured pointer are released.

    ``width`` and ``height`` are the size of the canvas: the ones given here, else the
    ones given to ``new()``, draw in a region of that size below the cursor; a canvas
    created without a size, or with ``'100%'`` for both, fills the whole window. A
    percentage such as ``'50%'`` is a share of the window when the canvas is opened. Any other keyword of ``new()`` except
    ``realtime`` may be given and applies before the canvas is shown; a gate given here
    wins over the one given to ``new()``. ``title`` is the window title.

    Args:
        title: The window title; ``None`` keeps the canvas's title.
        width: The width of the region to draw in: cells, or a percentage of the window.
        height: The height of the region to draw in: cells, or a percentage of the window.
        settings: Gates, appearance keywords, ``fps``, ``bpm``, ``effects``, and ``deps``
            and ``state`` for a canvas that was created without them; see
            [`OpenSettings`][xnano.types.OpenSettings].

    Returns:
        This canvas, now attached to the screen.

    Raises:
        TerminalAlreadyOpenError: Another canvas is already on the screen.
        TerminalError: This canvas is already on the screen, was written into another
            canvas, has a hook that needs a gate given as ``False``, or there is no
            terminal to draw on; the canvas stays as it was.
        TypeError: ``realtime`` was given, ``deps`` or ``state`` that the canvas already
            has, or an effect that is not a visual effect dictionary.
        ValueError: A ``width`` was given without a ``height``, or a value is out of
            range.

    Examples:
        ```text
        with xnano.new(width=40, height=5) as canvas:
            canvas.write('hello', border='rounded')
            canvas.step()
            canvas.open(mouse=True)        # now a xnano.Terminal, 40 by 5 below the prompt
            canvas.run(quit_on='q')
        ```
    """
    self._attach_screen(title=title, width=width, height=height, settings=settings)
    from xnano.terminal import Terminal

    assert isinstance(self, Terminal)
    return self

close ¶

close(*, raise_failure: bool = True) -> None

Release everything the canvas holds, and give the screen back if it has one.

Closing twice is harmless. Leaving a with block closes the canvas, unless it is part of another canvas or was created inside another canvas's with block: then it stays usable and closes with that canvas. Closing a canvas closes the canvases created inside its block that were not written anywhere. Closing a canvas that was written into another one takes it off and leaves that one running.

Parameters:

raise_failure (bool, default: True ) –

Whether to raise the error a callback raised on the loop, which stopped the canvas. A with block passes False while another error is already propagating.

Raises:

TerminalError –

A callback raised on the canvas's loop, or the loop would not stop.

Referenced by:

API Reference xnano
- xnano Canvas
- xnano.canvas canvas Canvas

Source code in xnano/canvas.py

def close(self, *, raise_failure: bool = True) -> None:
    """
    Release everything the canvas holds, and give the screen back if it has one.

    Closing twice is harmless. Leaving a ``with`` block closes the canvas, unless it is
    part of another canvas or was created inside another canvas's ``with`` block: then it
    stays usable and closes with that canvas. Closing a canvas closes the canvases created
    inside its block that were not written anywhere. Closing a canvas that was written into
    another one takes it off and leaves that one running.

    Args:
        raise_failure: Whether to raise the error a callback raised on the loop, which
            stopped the canvas. A ``with`` block passes ``False`` while another error is
            already propagating.

    Raises:
        TerminalError: A callback raised on the canvas's loop, or the loop would not stop.
    """
    self._close_nested_canvases()
    if self._canvas is not self:
        if not self._is_closed:
            self._is_closed = True
            root = self._canvas
            closing: list[Canvas[object, object]] = [
                cast('Canvas[object, object]', self)
            ]
            with root._lock:
                # A canvas written into this one is part of it, so it ends with it.
                closing.extend(
                    inner
                    for inner in list(root._children)
                    if inner is not self
                    and inner._is_inside(cast('Canvas[object, object]', self))
                )
                for canvas in closing:
                    canvas._is_closed = True
                    if canvas in root._children:
                        root._children.remove(canvas)
            placement = self._parent_placement
            if placement is not None and not root.is_closed:
                for canvas in closing:
                    root._host.post(canvas._cancel_hooks)
                placement.remove()
        if _current_canvas() is self:
            _active_canvas.set(self._previous_chain)
        return
    if not self._stop_requested.is_set() or not self._is_finalized:
        host = getattr(self, '_host', None)
        if host is not None:
            host.require_closable()
        self._stop_requested.set()
        try:
            if host is not None:
                host.shutdown()
        finally:
            self._finalize()
    if _current_canvas() is self:
        _active_canvas.set(self._previous_chain)
    failure = self._failure
    if failure is not None and raise_failure and not self._is_failure_reported:
        self._failure = None
        raise TerminalError(self._failure_text(failure)) from failure

local ¶

local(point: Point) -> Point

Convert a cell of the screen into a cell of this canvas.

Parameters:

point (Point) –

A cell in screen coordinates, such as context.mouse.position.

Examples:

import xnano
from xnano_core import Point

with xnano.new(width=10, height=3) as canvas:
    assert canvas.local(Point(4, 1)) == Point(4, 1)

Source code in xnano/canvas.py

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

    Args:
        point: A cell in screen coordinates, such as ``context.mouse.position``.

    Examples:
        ```python
        import xnano
        from xnano_core import Point

        with xnano.new(width=10, height=3) as canvas:
            assert canvas.local(Point(4, 1)) == Point(4, 1)
        ```
    """
    point = check_point(point)
    if self._canvas is self:
        return _core.Point(point.x, point.y)
    bounds = self._root._absolute_bounds
    return _core.Point(point.x - bounds.x, point.y - bounds.y)

move ¶

move(x: int = 0, y: int = 0) -> Self

Move a canvas that is written into another one by a number of cells along each axis.

This moves the placement the canvas is drawn in; see Placement.move.

Parameters:

x (int, default: 0 ) –

Columns to move right; a negative number moves left.
y (int, default: 0 ) –

Rows to move down; a negative number moves up.

Returns:

Self –

The canvas, so calls can chain.

Raises:

TerminalError –

The canvas is not written into another canvas, so it sits at the origin and cannot move.
TypeError –

An amount is not a whole number.

Examples:

import xnano

with xnano.new(width=20, height=3) as outer:
    inner = outer.new('box', width=4, height=1)
    inner.move(x=2, y=1)
    assert (inner.x, inner.y) == (2, 1)
    assert outer.render().splitlines()[1] == '  box'

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - down
    - left
    - new
    - right
    - up
  - Terminal
    - down
    - left
    - new
    - right
    - up
- xnano.canvas canvas Canvas
  - down
  - left
  - new
  - right
  - up
- xnano.terminal terminal Terminal
  - down
  - left
  - new
  - right
  - up

Source code in xnano/canvas.py

def move(self, x: int = 0, y: int = 0) -> Self:
    """
    Move a canvas that is written into another one by a number of cells along each axis.

    This moves the placement the canvas is drawn in; see
    [`Placement.move`][xnano.placement.Placement.move].

    Args:
        x: Columns to move right; a negative number moves left.
        y: Rows to move down; a negative number moves up.

    Returns:
        The canvas, so calls can chain.

    Raises:
        TerminalError: The canvas is not written into another canvas, so it sits at the
            origin and cannot move.
        TypeError: An amount is not a whole number.

    Examples:
        ```python
        import xnano

        with xnano.new(width=20, height=3) as outer:
            inner = outer.new('box', width=4, height=1)
            inner.move(x=2, y=1)
            assert (inner.x, inner.y) == (2, 1)
            assert outer.render().splitlines()[1] == '  box'
        ```
    """
    self._written_placement().move(x=x, y=y)
    return self

up ¶

up(count: int = 1) -> Self

Move a written canvas up by count rows; see move.

Parameters:

count (int, default: 1 ) –

How many rows to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def up(self, count: int = 1) -> Self:
    """
    Move a written canvas up by ``count`` rows; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many rows to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().up(count)
    return self

down ¶

down(count: int = 1) -> Self

Move a written canvas down by count rows; see move.

Parameters:

count (int, default: 1 ) –

How many rows to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def down(self, count: int = 1) -> Self:
    """
    Move a written canvas down by ``count`` rows; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many rows to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().down(count)
    return self

left ¶

left(count: int = 1) -> Self

Move a written canvas left by count columns; see move.

Parameters:

count (int, default: 1 ) –

How many columns to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def left(self, count: int = 1) -> Self:
    """
    Move a written canvas left by ``count`` columns; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many columns to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().left(count)
    return self

right ¶

right(count: int = 1) -> Self

Move a written canvas right by count columns; see move.

Parameters:

count (int, default: 1 ) –

How many columns to move.

Raises:

TerminalError –

The canvas is not written into another canvas.
TypeError –

count is not a whole number.
ValueError –

count is negative.

Source code in xnano/canvas.py

def right(self, count: int = 1) -> Self:
    """
    Move a written canvas right by ``count`` columns; see [`move`][xnano.canvas.Canvas.move].

    Args:
        count: How many columns to move.

    Raises:
        TerminalError: The canvas is not written into another canvas.
        TypeError: ``count`` is not a whole number.
        ValueError: ``count`` is negative.
    """
    self._written_placement().right(count)
    return self

new ¶

new(content: Content | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, effects: Sequence[RenderableEffectSpecification] = (), **settings: Unpack[CanvasSettings]) -> Canvas[DepsT, StateT]

Create a canvas inside this one and draw it here at once, at the top-left corner.

This is new followed by canvas.write(child): the child's size is measured in this canvas ('50%' is half of it, and no size fills it), it runs on this canvas's time and hears its input, and it closes with this canvas. Move it with move and its relatives, or create it with new and write it with x and y to place it elsewhere.

Parameters:

content (Content | None, default: None ) –

Something to write into the new canvas at once, such as text.
width (int | Percentage | str | None, default: None ) –

The width in cells, or a percentage of this canvas such as '50%'.
height (int | Percentage | str | None, default: None ) –

The height in cells, or a percentage of this canvas.
effects (Sequence[RenderableEffectSpecification], default: () ) –

Effects to apply to the new canvas, as dictionaries with a kind key.
settings (Unpack[CanvasSettings], default: {} ) –

The input gates and the new canvas's own look; see CanvasSettings.

Returns:

Canvas[DepsT, StateT] –

The new Canvas, already drawn in this one.

Raises:

TypeError –

An appearance keyword was given with content, or a keyword is unknown.
ValueError –

A size, gate or border kind is out of range.
TerminalError –

This canvas is closed, or a hook of the new canvas needs a gate this canvas turned off.

Examples:

import xnano

with xnano.new(width=12, height=4) as outer:
    panel = outer.new(height='50%', border='plain')
    assert (panel.width, panel.height) == (12, 2)
    assert outer.render().splitlines()[0] == '┌──────────┐'

Referenced by:

API Reference xnano
- xnano new
- xnano.canvas canvas new

Source code in xnano/canvas.py

def new(
    self,
    content: Content | None = None,
    /,
    *,
    width: int | Percentage | str | None = None,
    height: int | Percentage | str | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
    **settings: Unpack[CanvasSettings],
) -> Canvas[DepsT, StateT]:
    """
    Create a canvas inside this one and draw it here at once, at the top-left corner.

    This is [`new`][xnano.new] followed by ``canvas.write(child)``: the child's size is
    measured in this canvas (``'50%'`` is half of it, and no size fills it), it runs on
    this canvas's time and hears its input, and it closes with this canvas. Move it with
    [`move`][xnano.canvas.Canvas.move] and its relatives, or create it with
    [`new`][xnano.new] and write it with ``x`` and ``y`` to place it elsewhere.

    Args:
        content: Something to write into the new canvas at once, such as text.
        width: The width in cells, or a percentage of this canvas such as ``'50%'``.
        height: The height in cells, or a percentage of this canvas.
        effects: Effects to apply to the new canvas, as dictionaries with a ``kind`` key.
        settings: The input gates and the new canvas's own look; see
            [`CanvasSettings`][xnano.types.CanvasSettings].

    Returns:
        The new [`Canvas`][xnano.canvas.Canvas], already drawn in this one.

    Raises:
        TypeError: An appearance keyword was given with content, or a keyword is unknown.
        ValueError: A size, gate or border kind is out of range.
        TerminalError: This canvas is closed, or a hook of the new canvas needs a gate
            this canvas turned off.

    Examples:
        ```python
        import xnano

        with xnano.new(width=12, height=4) as outer:
            panel = outer.new(height='50%', border='plain')
            assert (panel.width, panel.height) == (12, 2)
            assert outer.render().splitlines()[0] == '┌──────────┐'
        ```
    """
    self._require_open()
    canvas: Canvas[DepsT, StateT] = _create(
        content,
        width=width,
        height=height,
        fps=self.fps,
        bpm=self.bpm,
        effects=effects,
        enclosing=cast('Canvas[object, object]', self),
        **settings,
    )
    try:
        self.write(cast('Canvas[object, object]', canvas))
    except BaseException:
        canvas.close(raise_failure=False)
        raise
    return canvas

write ¶

write(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, x: Axis | None = None, y: Axis | None = None, width: Axis | None = None, height: Axis | None = None, layer: int = 0, lock: bool = False, edges: EdgeBehavior | None = None, effects: Sequence[RenderableEffectSpecification] = (), style: Style | None = None, foreground: ColorValue | None = None, background: ColorValue | None = None, bold: bool = False, dim: bool = False, italic: bool = False, underline: bool = False, blink: bool = False, reverse: bool = False, hidden: bool = False, crossed_out: bool = False, title: str | None = None, border: BorderKind | bool | None = None, border_style: Style | None = None, padding: Spacing | None = None, margin: Spacing | None = None) -> Placement[DepsT, StateT]

Put something on the canvas: text, a widget, a buffer, another canvas or an image.

On a canvas that runs by itself it appears at once: this only declares it, and the canvas's own loop draws it. Anything you leave out is taken from the content: x and y default to the top-left corner, and width and height to the size of the content, so canvas.write('hello') shows five cells of text where it is. Change the text later by assigning the placement's text.

Inside the with block of a canvas created in this one's block, what is written here is placed and clipped within that canvas's area of this one: where it is written, or the top-left corner while it is not. Positions such as y='center' are measured in that area, and that canvas's edges applies there.

A canvas from new that is written here becomes part of this one: it draws inside the placement, its own clock is set aside and it runs on this canvas's time. It may not have been given state or deps, which belong to the outermost canvas. Its audio is not carried over: a musical clock it started and a note it was playing stop, and a formula that reads its audio.beat follows the outer canvas's musical clock, which starts at the first beat.

An image is added as an Image (never a file path or a bare TerminalImage; load one with from_image). With neither width nor height it keeps its own proportions at its own size, shrunk to fit the canvas. With one of them the other follows the image's proportions, and with both the image fits inside that box. An image sized by a percentage, or by the canvas because you gave no size, is converted again when the canvas is resized, unless it is locked. An animated image plays on the canvas's clock.

Parameters:

content (Content | Canvas[WrittenDepsT, WrittenStateT] | None, default: None ) –

Text (or a list of lines), a Buffer or widget, a canvas from new(), an image, or any Renderable; None for an empty placement.
x (Axis | None, default: None ) –

The column of the left edge: a number of cells, a percentage string, a word ('left', 'center' or 'right'), an expression, or a range ((0, 20)) that limits how far it may travel. See Axis.
y (Axis | None, default: None ) –

The row of the top edge, in the same forms ('top', 'center', 'bottom').
width (Axis | None, default: None ) –

The width, in the same forms; the content's own width when None.
height (Axis | None, default: None ) –

The height, in the same forms; the content's own height when None.
layer (int, default: 0 ) –

Content with a higher layer is drawn over content with a lower one.
lock (bool, default: False ) –

Keep the position and size the content has now, whatever the canvas's size does afterwards: percentages, words and formulas are read once.
edges (EdgeBehavior | None, default: None ) –

What the content does at the edges of its area: 'clip', 'stop' or 'wrap'; see Placement.edges. Left out, it follows what it is written on.
effects (Sequence[RenderableEffectSpecification], default: () ) –

Effects to start on the placement, as dictionaries with a kind key, such as [{'kind': 'effect.fade_to', 'foreground': 'red'}].
style (Style | None, default: None ) –

A ready-made Style for text. The parameters below are applied over it.
foreground (ColorValue | None, default: None ) –

The text color.
background (ColorValue | None, default: None ) –

The color behind the text.
bold (bool, default: False ) –

Whether the text is bold.
dim (bool, default: False ) –

Whether the text is dimmed.
italic (bool, default: False ) –

Whether the text is italic.
underline (bool, default: False ) –

Whether the text is underlined.
blink (bool, default: False ) –

Whether the text blinks.
reverse (bool, default: False ) –

Whether foreground and background are swapped.
hidden (bool, default: False ) –

Whether the text is hidden.
crossed_out (bool, default: False ) –

Whether the text is struck through.
title (str | None, default: None ) –

A title on the border of a box around the text.
border (BorderKind | bool | None, default: None ) –

The kind of border for a box around the content, a BorderKind such as 'plain', 'rounded', 'double' or 'thick'; True for 'plain' and False for none. Giving a title alone draws a plain one.
border_style (Style | None, default: None ) –

The style of the box's border.
padding (Spacing | None, default: None ) –

Space between the border and the text: a number of cells, a float or a percentage of the text's size, or a dictionary with top, right, bottom, left, vertical and horizontal. Giving it draws the text in a box without a border unless border or title is also given.
margin (Spacing | None, default: None ) –

Space outside the box, in the same forms.

Returns:

Placement[DepsT, StateT] –

A Placement to move, resize, listen on or remove.

Raises:

TypeError –

The content is a file path, raw bytes, or an operation, style or effect (apply those with canvas.update(...) instead).
TerminalError –

The content is a canvas that cannot be written here.

Examples:

import xnano

with xnano.new(width=20, height=4) as canvas:
    box = canvas.write('hello', x='50%', y=1)
    assert box.x == 10
    assert (box.width, box.height) == (5, 1)
    canvas.write(
        'Ready',
        x='center',
        y='bottom',
        foreground='green',
        bold=True,
        border='rounded',
        title='Status',
    )

Referenced by:

API Reference xnano

Source code in xnano/canvas.py

@refuse_unknown_keywords
def write(
    self,
    content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None,
    /,
    *,
    x: Axis | None = None,
    y: Axis | None = None,
    width: Axis | None = None,
    height: Axis | None = None,
    layer: int = 0,
    lock: bool = False,
    edges: EdgeBehavior | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
    style: _core.Style | None = None,
    foreground: ColorValue | None = None,
    background: ColorValue | None = None,
    bold: bool = False,
    dim: bool = False,
    italic: bool = False,
    underline: bool = False,
    blink: bool = False,
    reverse: bool = False,
    hidden: bool = False,
    crossed_out: bool = False,
    title: str | None = None,
    border: _core.BorderKind | bool | None = None,
    border_style: _core.Style | None = None,
    padding: Spacing | None = None,
    margin: Spacing | None = None,
) -> Placement[DepsT, StateT]:
    """
    Put something on the canvas: text, a widget, a buffer, another canvas or an image.

    On a canvas that runs by itself it appears at once: this only declares it, and the
    canvas's own loop draws it. Anything you leave out is taken from the content: ``x``
    and ``y`` default to the top-left corner, and ``width`` and ``height`` to the size of
    the content, so ``canvas.write('hello')`` shows five cells of text where it is.
    Change the text later by assigning the placement's
    [`text`][xnano.placement.Placement.text].

    Inside the ``with`` block of a canvas created in this one's block, what is written here
    is placed and clipped within that canvas's area of this one: where it is written, or
    the top-left corner while it is not. Positions such as ``y='center'`` are measured in
    that area, and that canvas's ``edges`` applies there.

    A canvas from [`new`][xnano.new] that is written here becomes part of this one: it
    draws inside the placement, its own clock is set aside and it runs on this canvas's
    time. It may not have been given ``state`` or ``deps``, which belong to the outermost
    canvas. Its audio is not carried over: a musical clock it started and a note it was
    playing stop, and a formula that reads its ``audio.beat`` follows the outer canvas's
    musical clock, which starts at the first beat.

    An image is added as an [`Image`][xnano.Image] (never a file path or a bare
    [`TerminalImage`][xnano_image.TerminalImage]; load one with
    [`from_image`][xnano.from_image]). With neither ``width`` nor ``height`` it keeps
    its own proportions at its own size, shrunk to fit the canvas. With one of them the
    other follows the image's proportions, and with both the image fits inside that box. An
    image sized by a percentage, or by the canvas because you gave no size, is converted
    again when the canvas is resized, unless it is locked. An animated image plays on the
    canvas's clock.

    Args:
        content: Text (or a list of lines), a [`Buffer`][xnano_core.Buffer] or widget, a
            canvas from ``new()``, an image, or any
            [`Renderable`][xnano.types.Renderable]; ``None`` for an empty placement.
        x: The column of the left edge: a number of cells, a percentage string, a word
            (``'left'``, ``'center'`` or ``'right'``), an expression, or a range
            (``(0, 20)``) that limits how far it may travel. See
            [`Axis`][xnano.types.Axis].
        y: The row of the top edge, in the same forms (``'top'``, ``'center'``,
            ``'bottom'``).
        width: The width, in the same forms; the content's own width when ``None``.
        height: The height, in the same forms; the content's own height when ``None``.
        layer: Content with a higher layer is drawn over content with a lower one.
        lock: Keep the position and size the content has now, whatever the canvas's
            size does afterwards: percentages, words and formulas are read once.
        edges: What the content does at the edges of its area: ``'clip'``, ``'stop'`` or
            ``'wrap'``; see [`Placement.edges`][xnano.placement.Placement.edges]. Left
            out, it follows what it is written on.
        effects: Effects to start on the placement, as dictionaries with a ``kind``
            key, such as ``[{'kind': 'effect.fade_to', 'foreground': 'red'}]``.
        style: A ready-made [`Style`][xnano.styles.Style] for text. The parameters below
            are applied over it.
        foreground: The text color.
        background: The color behind the text.
        bold: Whether the text is bold.
        dim: Whether the text is dimmed.
        italic: Whether the text is italic.
        underline: Whether the text is underlined.
        blink: Whether the text blinks.
        reverse: Whether foreground and background are swapped.
        hidden: Whether the text is hidden.
        crossed_out: Whether the text is struck through.
        title: A title on the border of a box around the text.
        border: The kind of border for a box around the content, a
            [`BorderKind`][xnano.types.BorderKind] such as ``'plain'``, ``'rounded'``,
            ``'double'`` or ``'thick'``; ``True`` for ``'plain'`` and ``False`` for none.
            Giving a ``title`` alone draws a plain one.
        border_style: The style of the box's border.
        padding: Space between the border and the text: a number of cells, a float or a
            percentage of the text's size, or a dictionary with ``top``, ``right``,
            ``bottom``, ``left``, ``vertical`` and ``horizontal``. Giving it draws the
            text in a box without a border unless ``border`` or ``title`` is also given.
        margin: Space outside the box, in the same forms.

    Returns:
        A [`Placement`][xnano.placement.Placement] to move, resize, listen on or remove.

    Raises:
        TypeError: The content is a file path, raw bytes, or an operation, style or effect
            (apply those with ``canvas.update(...)`` instead).
        TerminalError: The content is a canvas that cannot be written here.

    Examples:
        ```python
        import xnano

        with xnano.new(width=20, height=4) as canvas:
            box = canvas.write('hello', x='50%', y=1)
            assert box.x == 10
            assert (box.width, box.height) == (5, 1)
            canvas.write(
                'Ready',
                x='center',
                y='bottom',
                foreground='green',
                bold=True,
                border='rounded',
                title='Status',
            )
        ```
    """
    self._require_open()
    if edges is not None:
        edges = check_edges(edges)
    area = self._area_for_write(content)
    if area is not None:
        return area.write(  # type: ignore[return-value]
            content,
            x=x,
            y=y,
            width=width,
            height=height,
            layer=layer,
            lock=lock,
            edges=edges,
            effects=effects,
            style=style,
            foreground=foreground,
            background=background,
            bold=bold,
            dim=dim,
            italic=italic,
            underline=underline,
            blink=blink,
            reverse=reverse,
            hidden=hidden,
            crossed_out=crossed_out,
            title=title,
            border=border,
            border_style=border_style,
            padding=padding,
            margin=margin,
        )
    parent_buffer = self._content
    slot: _core.Buffer | None = None
    if self._layout != 'overlay':
        slot, width, height = self._open_slot(content, width, height)
        parent_buffer = slot
    try:
        placement = self._canvas._place_on(
            parent_buffer,
            content,
            parent_owner=cast('Canvas[object, object]', self),
            x=x,
            y=y,
            width=width,
            height=height,
            layer=layer,
            lock=lock,
            style=style,
            foreground=foreground,
            background=background,
            bold=bold,
            dim=dim,
            italic=italic,
            underline=underline,
            blink=blink,
            reverse=reverse,
            hidden=hidden,
            crossed_out=crossed_out,
            title=title,
            border=border,
            border_style=border_style,
            padding=padding,
            margin=margin,
        )
    except BaseException:
        if slot is not None:
            self._close_slot(slot)
        raise
    if slot is not None:
        self._slots[-1] = (
            cast('Placement[object, object]', placement),
            *self._slots[-1][1:],
        )
    if effects:
        apply_effects(cast('Placement[object, object]', placement), effects)
    placement._take_edges(edges, content)
    return placement

clear ¶

clear() -> None

Erase everything written or drawn directly on the canvas's cells.

Source code in xnano/canvas.py

def clear(self) -> None:
    """Erase everything written or drawn directly on the canvas's cells."""
    self._require_open()
    self._flush_look()
    self._content.update(_core.Fill(' '))

update ¶

update(*operations: Operation | Style) -> Self

Change the canvas's own cells with operations, styles or effects.

canvas | operation does the same. To put content on the canvas, use write instead.

Parameters:

operations (Operation | Style, default: () ) –

What to apply, in order: a core operation such as Fill or Write, a style, or an xnano customization such as an effect.

Returns:

Self –

The canvas, so calls chain.

Examples:

import xnano
from xnano_core import Fill

with xnano.new(width=4, height=1) as canvas:
    canvas.update(Fill('.'))
    assert canvas.render() == '....'
    canvas | Fill('#')
    assert canvas.render() == '####'

Source code in xnano/canvas.py

def update(self, *operations: _core.Operation | _core.Style) -> Self:
    """
    Change the canvas's own cells with operations, styles or effects.

    ``canvas | operation`` does the same. To put content on the canvas, use
    [`write`][xnano.canvas.Canvas.write] instead.

    Args:
        operations: What to apply, in order: a core operation such as ``Fill`` or
            ``Write``, a style, or an xnano customization such as an effect.

    Returns:
        The canvas, so calls chain.

    Examples:
        ```python
        import xnano
        from xnano_core import Fill

        with xnano.new(width=4, height=1) as canvas:
            canvas.update(Fill('.'))
            assert canvas.render() == '....'
            canvas | Fill('#')
            assert canvas.render() == '####'
        ```
    """
    self._require_open()
    for item in operations:
        if isinstance(item, ContextualOperation):
            cast('ContextualOperation[DepsT, StateT]', item).apply_to(self)
        elif isinstance(item, Customization):
            item.apply_to(cast('Canvas[object, object]', self))
        elif isinstance(item, _core.Style):
            self._content.update(_core.ApplyStyle(item))
        else:
            self._content.update(item)
    return self

or ¶

__or__(other: Operation | Style | Sequence[Operation]) -> Self

Apply an operation, customization or style with canvas | operation.

Source code in xnano/canvas.py

def __or__(
    self,
    other: _core.Operation | _core.Style | Sequence[_core.Operation],
) -> Self:
    """Apply an operation, customization or style with ``canvas | operation``."""
    if isinstance(other, (_core.Operation, _core.Style)):
        self.update(other)
    else:
        self.update(*other)
    return self

ior ¶

__ior__(other: Operation | Style | Sequence[Operation]) -> Self

Apply an operation, customization or style in place with canvas |= operation.

Source code in xnano/canvas.py

def __ior__(
    self,
    other: _core.Operation | _core.Style | Sequence[_core.Operation],
) -> Self:
    """Apply an operation, customization or style in place with ``canvas |= operation``."""
    return self.__or__(other)

inspect ¶

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

Evaluate an expression against the canvas and return its value.

Parameters:

expression (Expression[ValueT]) –

Any expression, such as Width, TimeElapsed % 1 or canvas.audio.level.

Examples:

import xnano
from xnano_core import Width

with xnano.new(width=12, height=2) as canvas:
    assert canvas.inspect(Width) == 12

Source code in xnano/canvas.py

def inspect(self, expression: _core.Expression[ValueT]) -> ValueT:
    """
    Evaluate an expression against the canvas and return its value.

    Args:
        expression: Any expression, such as ``Width``, ``TimeElapsed % 1`` or
            ``canvas.audio.level``.

    Examples:
        ```python
        import xnano
        from xnano_core import Width

        with xnano.new(width=12, height=2) as canvas:
            assert canvas.inspect(Width) == 12
        ```
    """
    self._require_open()
    return self._canvas._host.call(lambda: self._root.inspect(expression))

iter ¶

iter(*, count: int | None = None, seconds: float | None = None) -> Iterator[Frame]

Iterate over the canvas's frames, drawing between them; pass count= or seconds=, or break out of the loop.

Each iteration yields a Frame, and whatever you change before asking for the next one is drawn. On a canvas from new() each iteration moves the clock by one frame of its fps, so the same loop produces the same frames every run; without count or seconds it runs as fast as your code. A canvas that runs by itself draws as you declare, so there this only paces your code at its fps: if you are slow, frames are skipped rather than queued.

stop freezes the time iter() follows: the iterations go on drawing and hooks still run, but the clock stands still until resume. To move a stopped canvas one frame, call step.

The iteration ends when count frames have been yielded, when the canvas's time has run for seconds (whichever comes first), when the canvas is asked to quit or closed, or when you break out of the loop.

Parameters:

count (int | None, default: None ) –

The most frames to yield.
seconds (float | None, default: None ) –

The most seconds of the canvas's time to run for.

Raises:

TerminalError –

seconds without count on a stopped canvas, which would never reach the end.
TerminalClosedError –

The canvas is closed.

Examples:

import xnano

with xnano.new(width=8, height=1, fps=10) as canvas:
    frames = list(canvas.iter(count=3))
assert [frame.elapsed_seconds for frame in frames] == [0.0, 0.1, 0.2]

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - fps
    - step
  - Terminal
    - fps
    - step
  - iter
  - new
- xnano.canvas canvas
  - Canvas
    - fps
    - step
  - iter
  - new
- xnano.terminal terminal Terminal
  - fps
  - step

Source code in xnano/canvas.py

def iter(
    self, *, count: int | None = None, seconds: float | None = None
) -> Iterator[Frame]:
    """
    Iterate over the canvas's frames, drawing between them; pass ``count=`` or ``seconds=``,
    or break out of the loop.

    Each iteration yields a [`Frame`][xnano.context.Frame], and whatever you change
    before asking for the next one is drawn. On a canvas from ``new()`` each iteration
    moves the clock by one frame of its ``fps``, so the same loop produces the same
    frames every run; without ``count`` or ``seconds`` it runs as fast as your code. A
    canvas that runs by itself draws as you declare, so there this only paces your code
    at its ``fps``: if you are slow, frames are skipped rather than queued.

    [`stop`][xnano.canvas.Canvas.stop] freezes the time ``iter()`` follows: the
    iterations go on drawing and hooks still run, but the clock stands still until
    [`resume`][xnano.canvas.Canvas.resume]. To move a stopped canvas one frame, call
    [`step`][xnano.canvas.Canvas.step].

    The iteration ends when ``count`` frames have been yielded, when the canvas's time has
    run for ``seconds`` (whichever comes first), when the canvas is asked to
    [`quit`][xnano.canvas.Canvas.quit] or closed, or when you break out of the loop.

    Args:
        count: The most frames to yield.
        seconds: The most seconds of the canvas's time to run for.

    Raises:
        TerminalError: ``seconds`` without ``count`` on a stopped canvas, which would
            never reach the end.
        TerminalClosedError: The canvas is closed.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1, fps=10) as canvas:
            frames = list(canvas.iter(count=3))
        assert [frame.elapsed_seconds for frame in frames] == [0.0, 0.1, 0.2]
        ```
    """
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    if count is not None and (
        isinstance(count, bool) or not isinstance(count, int) or count < 0
    ):
        raise ValueError(
            f'count must be a whole number of frames, 0 or more, but was {count!r}.'
        )
    if seconds is not None and (
        isinstance(seconds, bool)
        or not isinstance(seconds, (int, float))
        or not seconds > 0
    ):
        raise ValueError(
            f'seconds must be a number above zero, but was {seconds!r}. Pass count= to '
            f'stop after a number of frames instead.'
        )
    if seconds is not None and count is None:
        canvas._refuse_endless_seconds(seconds)
    return canvas._frames(count, seconds)

step ¶

step(*, delta_seconds: float | None = None) -> Frame

Move time by delta_seconds, one frame by default, and draw exactly one frame.

On a canvas from new() this always works, and it moves time even while the canvas is stopped, which leaves it stopped: it is how a stopped canvas is walked one frame at a time. A canvas that runs by itself can be stepped only while it is stopped. One frame is 1 / fps seconds; default steps and the frames of iter share one count, so sixty of them at fps=60 are exactly one second. A large delta_seconds is one jump: timers that it crossed all run, and so do fixed-step every hooks, at most 100000 of their steps in one step; the steps that remain run in the steps that follow.

Parameters:

delta_seconds (float | None, default: None ) –

How far to move, in seconds, above zero; one frame when None.

Returns:

Frame –

The Frame that was drawn.

Raises:

ValueError –

delta_seconds is not above zero.
TerminalError –

The canvas runs by itself and is not stopped.
TerminalClosedError –

The canvas was closed.

Examples:

import xnano

with xnano.new(width=8, height=1, fps=10) as canvas:
    frame = canvas.step()
    assert frame.elapsed_seconds == 0.1
    canvas.stop()
    canvas.step(delta_seconds=0.5)
    assert canvas.time.elapsed == 0.6
    assert canvas.time.is_stopped

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - stop
  - Terminal
    - iter
    - stop
  - new
- xnano.audio audio AudioDevice render_sound
- xnano.canvas canvas
  - Canvas
    - iter
    - stop
  - new
- xnano.terminal terminal Terminal
  - iter
  - stop
- xnano.time time Time step
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def step(self, *, delta_seconds: float | None = None) -> Frame:
    """
    Move time by ``delta_seconds``, one frame by default, and draw exactly one frame.

    On a canvas from ``new()`` this always works, and it moves time even while the
    canvas is stopped, which leaves it stopped: it is how a stopped canvas is walked one
    frame at a time. A canvas that runs by itself can be stepped only while it is
    stopped. One frame is ``1 / fps`` seconds; default steps and the frames of
    [`iter`][xnano.canvas.Canvas.iter] share one count, so sixty of them at ``fps=60``
    are exactly one second. A large ``delta_seconds`` is one jump: timers that it crossed
    all run, and so do fixed-step ``every`` hooks, at most 100000 of their steps in one
    step; the steps that remain run in the steps that follow.

    Args:
        delta_seconds: How far to move, in seconds, above zero; one frame when ``None``.

    Returns:
        The [`Frame`][xnano.context.Frame] that was drawn.

    Raises:
        ValueError: ``delta_seconds`` is not above zero.
        TerminalError: The canvas runs by itself and is not stopped.
        TerminalClosedError: The canvas was closed.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1, fps=10) as canvas:
            frame = canvas.step()
            assert frame.elapsed_seconds == 0.1
            canvas.stop()
            canvas.step(delta_seconds=0.5)
            assert canvas.time.elapsed == 0.6
            assert canvas.time.is_stopped
        ```
    """
    self._require_own_presence()
    return self._canvas._step(delta_seconds)

deliver_events ¶

deliver_events() -> None

Deliver pushed events to their hooks and draw a frame, without moving time.

Events pushed with push reach their hooks at the canvas's next step; this is that step on a canvas whose clock you move. A canvas that runs by itself delivers them on its own.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:
    heard = []
    canvas.hook(lambda context: heard.append(context.event.kind))
    canvas.push(Event.custom('ping'))
    canvas.deliver_events()
    assert heard == ['custom']
    assert canvas.time.elapsed == 0.0

Source code in xnano/canvas.py

def deliver_events(self) -> None:
    """
    Deliver pushed events to their hooks and draw a frame, without moving time.

    Events pushed with [`push`][xnano.canvas.Canvas.push] reach their hooks at the
    canvas's next step; this is that step on a canvas whose clock you move. A canvas that
    runs by itself delivers them on its own.

    Examples:
        ```python
        import xnano
        from xnano_core import Event

        with xnano.new(width=8, height=1) as canvas:
            heard = []
            canvas.hook(lambda context: heard.append(context.event.kind))
            canvas.push(Event.custom('ping'))
            canvas.deliver_events()
            assert heard == ['custom']
            assert canvas.time.elapsed == 0.0
        ```
    """
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    if canvas._host.is_autonomous:
        canvas._host.call(lambda: canvas._runtime.request_frame())
        return
    canvas._raise_failure()
    canvas._runtime.step()
    canvas._pushed_pointer = None
    canvas._raise_failure()

stop ¶

stop() -> None

Freeze time: the same as Time.stop.

The canvas keeps drawing and hooks still hear input, but animations, effects, formulas, timers and the beat stand still until resume. step moves a stopped canvas one frame at a time. To end a loop, call quit.

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - resume
  - Terminal
    - iter
    - resume
- xnano.audio audio AudioDevice stop
- xnano.canvas canvas Canvas
  - iter
  - resume
- xnano.terminal terminal Terminal
  - iter
  - resume
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def stop(self) -> None:
    """
    Freeze time: the same as [`Time.stop`][xnano.time.Time.stop].

    The canvas keeps drawing and hooks still hear input, but animations, effects,
    formulas, timers and the beat stand still until [`resume`][xnano.canvas.Canvas.resume].
    [`step`][xnano.canvas.Canvas.step] moves a stopped canvas one frame at a time. To end a
    loop, call [`quit`][xnano.canvas.Canvas.quit].
    """
    self._require_own_presence()
    self._canvas._time.stop()

resume ¶

resume() -> None

Let time run on from where stop froze it.

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - stop
  - Terminal
    - iter
    - stop
- xnano.audio audio AudioDevice stop
- xnano.canvas canvas Canvas
  - iter
  - stop
- xnano.terminal terminal Terminal
  - iter
  - stop
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def resume(self) -> None:
    """Let time run on from where [`stop`][xnano.canvas.Canvas.stop] froze it."""
    self._require_own_presence()
    self._canvas._time.resume()

quit ¶

quit() -> None

Ask the canvas's loop to end.

Safe from any thread, including from a hook. A running iter(), run(), wait_for_key() or prompt() ends. On a canvas from new() the canvas stays open for writing and rendering; on a canvas that runs by itself (realtime=True, or on the screen) the loop ends and the canvas closes.

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - iter
    - run
    - stop
  - Terminal
    - iter
    - run
    - stop
  - active
- xnano.canvas canvas
  - Canvas
    - iter
    - run
    - stop
  - active
- xnano.terminal terminal Terminal
  - iter
  - run
  - stop

Source code in xnano/canvas.py

def quit(self) -> None:
    """
    Ask the canvas's loop to end.

    Safe from any thread, including from a hook. A running ``iter()``, ``run()``,
    ``wait_for_key()`` or ``prompt()`` ends. On a canvas from ``new()`` the canvas stays
    open for writing and rendering; on a canvas that runs by itself (``realtime=True``, or
    on the screen) the loop ends and the canvas closes.
    """
    self._require_own_presence()
    canvas = self._canvas
    canvas._stop_requested.set()
    if not canvas._is_closed and canvas._host.is_autonomous:
        canvas._host.post(lambda: canvas._stop_runtime())

run ¶

run(*, quit_on: KeyName | Sequence[KeyName] | None = 'ctrl+c') -> None

Wait until the canvas's loop ends.

A canvas that runs by itself draws and listens on its own, so this only keeps your program alive until a quit key is pressed, or something calls quit (a hook, another thread). Declare what you want before calling it.

Parameters:

quit_on (KeyName | Sequence[KeyName] | None, default: 'ctrl+c' ) –

The key, or keys, that end the loop, such as 'q' or ('q', 'escape'). 'ctrl+c' by default; give None to leave ending to your own code.

Raises:

TerminalError –

A callback raised on the canvas's loop, or the canvas has a clock that only moves when you move it, so waiting would never end.

Referenced by:

API Reference xnano
- xnano Canvas
- xnano.canvas canvas Canvas

Source code in xnano/canvas.py

def run(self, *, quit_on: KeyName | Sequence[KeyName] | None = 'ctrl+c') -> None:
    """
    Wait until the canvas's loop ends.

    A canvas that runs by itself draws and listens on its own, so this only keeps your
    program alive until a quit key is pressed, or something calls
    [`quit`][xnano.canvas.Canvas.quit] (a hook, another thread). Declare what you want
    before calling it.

    Args:
        quit_on: The key, or keys, that end the loop, such as ``'q'`` or
            ``('q', 'escape')``. ``'ctrl+c'`` by default; give ``None`` to leave ending
            to your own code.

    Raises:
        TerminalError: A callback raised on the canvas's loop, or the canvas has a clock
            that only moves when you move it, so waiting would never end.
    """
    canvas = self._canvas
    canvas._require_open()
    host = canvas._host
    if not isinstance(host, _ThreadHost):
        raise TerminalError(
            'A canvas with a manual clock never moves by itself, so run() would wait '
            'forever. Drive it with canvas.iter() or canvas.step(), open it on the screen '
            'with canvas.open(), or create it with realtime=True.'
        )
    if quit_on is not None:
        keys = (quit_on,) if isinstance(quit_on, str) else tuple(quit_on)
        if canvas._is_live and canvas._resolved_gates.get('keyboard') is False:
            # With the keyboard off, only the interrupt gate can end the loop on Ctrl-C.
            keys = tuple(key for key in keys if key != 'ctrl+c')
        if keys:

            @canvas.hook(on='key', keys=keys)
            def quit_key(context: Context[DepsT, StateT]) -> None:
                context.canvas.quit()

    try:
        while not host.wait(0.1):
            pass
    except KeyboardInterrupt:
        canvas.quit()
        raise
    failure = canvas._failure
    if failure is not None:
        canvas._failure = None
        raise TerminalError(canvas._failure_text(failure)) from failure

wait_for_key ¶

wait_for_key(*keys: KeyName) -> str

Wait until a key is pressed, and return its name.

Your program waits here while the canvas goes on drawing and animating. It reads like input(): nothing else runs on your thread until the key arrives.

Parameters:

keys (KeyName, default: () ) –

The keys to wait for, such as 'enter' or 'q'. Give none to take any key.

Returns:

str –

The name of the key that was pressed.

Raises:

TerminalError –

The canvas ended, or has a manual clock, so no key could arrive.

Examples:

In a program: canvas.wait_for_key() after adding "Press any key to start". Here a timer plays the part of the person pressing the key:

import xnano
from xnano.events import Event

with xnano.new(realtime=True, width=30, height=2) as canvas:
    canvas.write('Press enter to start')

    @canvas.hook(on='tick', after=0.05)
    def press(context: xnano.Context) -> None:
        canvas.push(Event.key_press('enter'))

    assert canvas.wait_for_key('enter') == 'enter'

Source code in xnano/canvas.py

def wait_for_key(self, *keys: KeyName) -> str:
    """
    Wait until a key is pressed, and return its name.

    Your program waits here while the canvas goes on drawing and animating. It reads
    like ``input()``: nothing else runs on your thread until the key arrives.

    Args:
        keys: The keys to wait for, such as ``'enter'`` or ``'q'``. Give none to take any key.

    Returns:
        The name of the key that was pressed.

    Raises:
        TerminalError: The canvas ended, or has a manual clock, so no key could arrive.

    Examples:
        In a program: ``canvas.wait_for_key()`` after adding "Press any key to start".
        Here a timer plays the part of the person pressing the key:

        ```python
        import xnano
        from xnano.events import Event

        with xnano.new(realtime=True, width=30, height=2) as canvas:
            canvas.write('Press enter to start')

            @canvas.hook(on='tick', after=0.05)
            def press(context: xnano.Context) -> None:
                canvas.push(Event.key_press('enter'))

            assert canvas.wait_for_key('enter') == 'enter'
        ```
    """
    pressed: list[str] = []
    done = threading.Event()

    @self.hook(on='key', keys=keys or None)
    def hear(context: Context[DepsT, StateT]) -> None:
        key = context.keyboard.key
        if key is not None:
            pressed.append(key)
        context.hook.remove()
        done.set()

    self._wait_until(done, 'a key')
    return pressed[0]

prompt ¶

prompt(text: str, *, x: int = 0, y: int = 0, default: str = '') -> str

Prompt for a line of text, and return what was typed.

The prompt and the answer appear on the canvas while your program waits, like input(). Enter submits and Backspace deletes.

Parameters:

text (str) –

What to ask, such as 'Your name: '.
x (int, default: 0 ) –

The column of the prompt.
y (int, default: 0 ) –

The row of the prompt.
default (str, default: '' ) –

Text already in the answer, which the user can edit.

Returns:

str –

What was typed, without the prompt.

Raises:

TerminalError –

The canvas ended, or has a manual clock, so no answer could arrive.

Examples:

In a program: name = canvas.prompt('Your name: '). Here a timer plays the part of the person typing:

import xnano
from xnano.events import Event

with xnano.new(realtime=True, width=30, height=2) as canvas:

    @canvas.hook(on='tick', after=0.05)
    def type_answer(context: xnano.Context) -> None:
        for letter in 'Ada':
            canvas.push(Event.key_press(letter))
        canvas.push(Event.key_press('enter'))

    assert canvas.prompt('Your name: ') == 'Ada'

Source code in xnano/canvas.py

def prompt(self, text: str, *, x: int = 0, y: int = 0, default: str = '') -> str:
    """
    Prompt for a line of text, and return what was typed.

    The prompt and the answer appear on the canvas while your program waits, like
    ``input()``. ``Enter`` submits and ``Backspace`` deletes.

    Args:
        text: What to ask, such as ``'Your name: '``.
        x: The column of the prompt.
        y: The row of the prompt.
        default: Text already in the answer, which the user can edit.

    Returns:
        What was typed, without the prompt.

    Raises:
        TerminalError: The canvas ended, or has a manual clock, so no answer could arrive.

    Examples:
        In a program: ``name = canvas.prompt('Your name: ')``. Here a timer plays the part
        of the person typing:

        ```python
        import xnano
        from xnano.events import Event

        with xnano.new(realtime=True, width=30, height=2) as canvas:

            @canvas.hook(on='tick', after=0.05)
            def type_answer(context: xnano.Context) -> None:
                for letter in 'Ada':
                    canvas.push(Event.key_press(letter))
                canvas.push(Event.key_press('enter'))

            assert canvas.prompt('Your name: ') == 'Ada'
        ```
    """
    answer = [default]
    done = threading.Event()

    shown = self.write(text + default + ' ', x=x, y=y)

    def show() -> None:
        line = text + answer[0]
        shown.text = line + ' '
        self.cursor.position = (x + _core.display_width(line), y)

    cursor = self.cursor
    previous = (cursor.shape, cursor.is_blinking, cursor.is_visible, cursor.position)
    following = cursor._canvas._cursor_follow
    self.cursor.shape = 'bar'
    self.cursor.is_blinking = True
    self.cursor.is_visible = True
    show()

    @self.hook(on='key', when="keyboard.kind != 'release'")
    def edit(context: Context[DepsT, StateT]) -> None:
        key = context.keyboard
        if key.key is None:
            return
        if key.key == 'enter':
            done.set()
            return
        if key.key == 'backspace':
            answer[0] = answer[0][:-1]
        elif key.text is not None and not key.modifiers - {'shift'}:
            answer[0] += key.text
        show()

    try:
        self._wait_until(done, 'an answer')
    finally:
        edit.remove()
        cursor.is_visible = False
        cursor.is_blinking = previous[1]
        cursor.shape = previous[0]
        if following is None:
            cursor.position = previous[3]
        else:
            cursor.follow(following[0], x=following[1], y=following[2])
        cursor.is_visible = previous[2]
        shown.remove()
    return answer[0]

render ¶

render(*, format: Literal['text', 'ansi'] = 'text') -> str

Draw the current frame and return it, without a screen.

A canvas that was written into another one returns its own cells alone, at its own size, as they stand in the outer canvas's current frame.

Parameters:

format (Literal['text', 'ansi'], default: 'text' ) –

'text' for the characters alone, 'ansi' for the characters with their colors and styles as escape codes.

Raises:

ValueError –

format is neither 'text' nor 'ansi'.

Examples:

import xnano

with xnano.new(width=6, height=2) as canvas:
    canvas.write('hello', y=1)
    assert canvas.render().splitlines() == ['', 'hello']
    assert 'hello' in canvas.render(format='ansi')

Referenced by:

API Reference xnano xnano.output output Output

Source code in xnano/canvas.py

def render(self, *, format: Literal['text', 'ansi'] = 'text') -> str:
    """
    Draw the current frame and return it, without a screen.

    A canvas that was written into another one returns its own cells alone, at its own
    size, as they stand in the outer canvas's current frame.

    Args:
        format: ``'text'`` for the characters alone, ``'ansi'`` for the characters with
            their colors and styles as escape codes.

    Raises:
        ValueError: ``format`` is neither ``'text'`` nor ``'ansi'``.

    Examples:
        ```python
        import xnano

        with xnano.new(width=6, height=2) as canvas:
            canvas.write('hello', y=1)
            assert canvas.render().splitlines() == ['', 'hello']
            assert 'hello' in canvas.render(format='ansi')
        ```
    """
    if format not in ('text', 'ansi'):
        raise ValueError(
            f"format must be 'text' or 'ansi', but was {format!r}. 'text' gives the "
            f"characters, 'ansi' the characters with their colors."
        )
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    if canvas is not self:
        root_buffer = self._root

        def render_child() -> str:
            canvas._runtime.render()
            return root_buffer.render(format=format)

        return canvas._host.call(render_child)
    snapshot = canvas._host.call(lambda: canvas._runtime.render())
    if format == 'ansi':
        return snapshot.ansi
    return '\n'.join(snapshot.lines())

push ¶

push(event: Event) -> None

Deliver an event to the canvas as if it had been typed, clicked or reported.

Hooks hear it the same way as input from the keyboard and mouse, at the canvas's next step, whatever the input gates say. Build events with Event; Event.custom(name, data=...) makes one of your own.

Parameters:

event (Event) –

The event to deliver.

Raises:

TypeError –

The value is not an Event.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:
    heard = []
    canvas.hook(
        lambda context: heard.append(context.event.custom_name),
        when=lambda context: context.event.kind == 'custom',
    )
    canvas.push(Event.custom('volume_changed'))
    canvas.deliver_events()
assert heard == ['volume_changed']

Referenced by:

API Reference xnano

Source code in xnano/canvas.py

def push(self, event: _core.Event) -> None:
    """
    Deliver an event to the canvas as if it had been typed, clicked or reported.

    Hooks hear it the same way as input from the keyboard and mouse, at the canvas's
    next step, whatever the input gates say. Build events with
    [`Event`][xnano_core.Event]; ``Event.custom(name, data=...)`` makes one of your own.

    Args:
        event: The event to deliver.

    Raises:
        TypeError: The value is not an [`Event`][xnano_core.Event].

    Examples:
        ```python
        import xnano
        from xnano_core import Event

        with xnano.new(width=8, height=1) as canvas:
            heard = []
            canvas.hook(
                lambda context: heard.append(context.event.custom_name),
                when=lambda context: context.event.kind == 'custom',
            )
            canvas.push(Event.custom('volume_changed'))
            canvas.deliver_events()
        assert heard == ['volume_changed']
        ```
    """
    if not isinstance(event, _core.Event):
        raise TypeError(
            f'push() takes an Event such as xnano_core.Event.custom("ping"), but got '
            f'{event!r}. To press a key, push xnano_core.Event.key_press("q"), or call '
            f'context.keyboard.push("q") inside a hook.'
        )
    self._require_own_presence()
    canvas = self._canvas
    canvas._require_open()
    canvas._host.post(lambda: canvas._runtime.inject(event))

play ¶

play(playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle

Play a note, a sound, a symbol name, a melody or a sequence of those, and return at once.

This is audio.play; see it for what playable may be and for every option. On a canvas from new() the sound is recorded instead of played; read it with audio.render_sound.

Parameters:

playable (PlaySource) –

What to play: a note, a sound, a symbol name, melody text such as 'C4 E4 G4:2', a MIDI number, a frequency, or a sequence of those.
options (Unpack[PlayOptions], default: {} ) –

The settings of PlayOptions, such as instrument, volume, pan, beats and at_beat.

Returns:

PlayHandle –

A PlayHandle that tells when the sound is over.

Examples:

import xnano

with xnano.new(width=8, height=1, bpm=100) as canvas:
    canvas.play('C4 E4 G4:2 rest C5+E5+G5', instrument='bell')
    canvas.step(delta_seconds=1.0)
    assert canvas.audio.render_sound().duration_milliseconds == 1000.0

Referenced by:

API Reference xnano
- xnano
  - Audio
  - Note
  - note
- xnano.audio audio
  - PlaySource
  - Audio
- xnano.music music
  - Note
  - note
- xnano.types types
  - PlaySource
  - Playable

Source code in xnano/canvas.py

def play(self, playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle:
    """
    Play a note, a sound, a symbol name, a melody or a sequence of those, and return at once.

    This is [`audio.play`][xnano.audio.AudioDevice.play]; see it for what ``playable`` may
    be and for every option. On a canvas from ``new()`` the sound is recorded instead of
    played; read it with [`audio.render_sound`][xnano.audio.AudioDevice.render_sound].

    Args:
        playable: What to play: a note, a sound, a symbol name, melody text such as
            ``'C4 E4 G4:2'``, a MIDI number, a frequency, or a sequence of those.
        options: The settings of [`PlayOptions`][xnano.types.PlayOptions], such as
            ``instrument``, ``volume``, ``pan``, ``beats`` and ``at_beat``.

    Returns:
        A [`PlayHandle`][xnano.music.PlayHandle] that tells when the sound is over.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1, bpm=100) as canvas:
            canvas.play('C4 E4 G4:2 rest C5+E5+G5', instrument='bell')
            canvas.step(delta_seconds=1.0)
            assert canvas.audio.render_sound().duration_milliseconds == 1000.0
        ```
    """
    self._require_own_presence()
    if hasattr(playable, '__xnano_play__') or not isinstance(playable, str):
        handle = _play_component(
            cast('Canvas[object, object]', self._canvas), playable, options
        )
        if handle is not None:
            return handle
    return self.audio.play(playable, **options)

state_reference ¶

state_reference(reader: Callable[[StateT], ValueT]) -> StateReference[ValueT]

A core reference for one field of the canvas's state.

The reference can be used as an axis, a range bound or a widget parameter.

Parameters:

reader (Callable[[StateT], ValueT]) –

A function or lambda that reads the field, such as lambda state: state.volume.

Raises:

TypeError –

reader is not a function.
TerminalError –

The canvas was created without state.

Source code in xnano/canvas.py

def state_reference(
    self, reader: Callable[[StateT], ValueT]
) -> _core.StateReference[ValueT]:
    """
    A core reference for one field of the canvas's state.

    The reference can be used as an axis, a range bound or a widget parameter.

    Args:
        reader: A function or lambda that reads the field, such as
            ``lambda state: state.volume``.

    Raises:
        TypeError: ``reader`` is not a function.
        TerminalError: The canvas was created without ``state``.
    """
    if not callable(reader):
        raise TypeError(
            f'state_reference() takes a function that reads one field, but got '
            f'{reader!r}. Pass a function such as lambda state: state.volume.'
        )
    store = self._canvas._state_store
    if store is None:
        raise TerminalError(
            'This canvas has no state, so state_reference() has nothing to read. Create it with '
            'xnano.new(state=YourDataclass()).'
        )
    return _reference_for(store, reader)

Color ¶

Color(value: ColorName | str | tuple[int, int, int])

A terminal color: a named palette color, a palette index or a true color.

Maps to ratatui::style::Color.

Parameters:

value (ColorName | str | tuple[int, int, int]) –

A color name such as 'red' or 'light_blue', a hex string such as '#ff8800', a palette index string such as '4', or a (red, green, blue) tuple.

Attributes:

black (Color) –

The black terminal color.
red (Color) –

The red terminal color.
green (Color) –

The green terminal color.
yellow (Color) –

The yellow terminal color.
blue (Color) –

The blue terminal color.
magenta (Color) –

The magenta terminal color.
cyan (Color) –

The cyan terminal color.
gray (Color) –

The gray terminal color.
dark_gray (Color) –

The dark gray terminal color.
light_red (Color) –

The light red terminal color.
light_green (Color) –

The light green terminal color.
light_yellow (Color) –

The light yellow terminal color.
light_blue (Color) –

The light blue terminal color.
light_magenta (Color) –

The light magenta terminal color.
light_cyan (Color) –

The light cyan terminal color.
white (Color) –

The white terminal color.
reset (Color) –

The reset terminal color, which follows the terminal theme.
is_reset (bool) –

Whether this is the reset color.

Raises:

ValueError –

value is not a recognized color.

Examples:

assert Color('#ff8800').to_rgb() == (255, 136, 0)
assert Color((1, 2, 3)) == Color.from_rgb(1, 2, 3)
assert Color('red').to_rgb() is None

Create a Color.

Parameters:

value (ColorName | str | tuple[int, int, int]) –

ColorName | str | tuple[int, int, int].

Referenced by:

API Reference
- xnano
- xnano_core

Returned by:

API Reference
- xnano
  - xnano Color
    - black
    - blue
    - cyan
    - dark_gray
    - gray
    - green
    - light_blue
    - light_cyan
    - light_green
    - light_magenta
    - light_red
    - light_yellow
    - magenta
    - red
    - reset
    - white
    - yellow
    - darken
    - from_hsl
    - from_hsv
    - from_rgb
    - from_tailwind
    - indexed
    - inverse
    - lerp
    - lighten
    - parse
    - random
    - saturate
  - xnano.appearance appearance
    - BorderSide color
    - ColorSlot
      - value
      - random
  - xnano.art art Art background
  - xnano.buffers buffers Cell
    - background
    - foreground
  - xnano.styles styles
    - Color
      - black
      - blue
      - cyan
      - dark_gray
      - gray
      - green
      - light_blue
      - light_cyan
      - light_green
      - light_magenta
      - light_red
      - light_yellow
      - magenta
      - red
      - reset
      - white
      - yellow
      - darken
      - from_hsl
      - from_hsv
      - from_rgb
      - from_tailwind
      - indexed
      - inverse
      - lerp
      - lighten
      - parse
      - random
      - saturate
    - Style
      - background
      - foreground
  - xnano.widgets widgets
- xnano_core
  - xnano_core
    - Canvas background_color
    - CanvasCircle color
    - CanvasLine color
    - CanvasMap color
    - CanvasPoints color
    - CanvasRectangle color
    - Cell
      - background
      - foreground
    - Color
      - black
      - blue
      - cyan
      - dark_gray
      - gray
      - green
      - light_blue
      - light_cyan
      - light_green
      - light_magenta
      - light_red
      - light_yellow
      - magenta
      - red
      - reset
      - white
      - yellow
      - darken
      - from_hsl
      - from_hsv
      - from_rgb
      - from_tailwind
      - indexed
      - inverse
      - lerp
      - lighten
      - parse
      - random
      - saturate
    - Style
      - background
      - foreground
  - xnano_core._xnano_core _xnano_core
    - Canvas background_color
    - CanvasCircle color
    - CanvasLine color
    - CanvasMap color
    - CanvasPoints color
    - CanvasRectangle color
    - Cell
      - background
      - foreground
    - Color
      - black
      - blue
      - cyan
      - dark_gray
      - gray
      - green
      - light_blue
      - light_cyan
      - light_green
      - light_magenta
      - light_red
      - light_yellow
      - magenta
      - red
      - reset
      - white
      - yellow
      - darken
      - from_hsl
      - from_hsv
      - from_rgb
      - from_tailwind
      - indexed
      - inverse
      - lerp
      - lighten
      - parse
      - random
      - saturate
    - Style
      - background
      - foreground

Used by:

API Reference
- xnano
  - xnano Color
    - lerp
    - random
  - xnano.region region Region __setitem__
  - xnano.styles styles Color
    - lerp
    - random
- xnano_core
  - xnano_core Color
    - lerp
    - random
  - xnano_core._xnano_core _xnano_core Color
    - lerp
    - random

Methods:

parse –

Parse a color name, hex string or palette index string.
from_tailwind –

A true color from a Tailwind palette and shade.
indexed –

A color from the 256-color palette.
from_rgb –

A true color from red, green and blue values between 0 and 255.
to_rgb –

The (red, green, blue) values of a true color, or None for named and indexed colors.
to_hex –

The color as a '#rrggbb' string.
from_hsl –

A true color from hue, saturation and lightness.
from_hsv –

A true color from hue, saturation and value.
random –

A random true color, or a random shade of base.
to_hsl –

The hue (degrees), saturation and lightness (percentages) of the color.
to_hsv –

The hue (degrees), saturation and value (percentages) of the color.
lerp –

The color between this one and other.
lighten –

A lighter color for a positive amount, a darker one for a negative amount.
darken –

A darker color.
inverse –

The color that has each red, green and blue channel inverted.
saturate –

The color with its saturation scaled.

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def __init__(self, value: ColorName | str | tuple[int, int, int]) -> None:
    """
    Create a Color.

    Args:
        value: ``ColorName | str | tuple[int, int, int]``.
    """

black `class-attribute` ¶

black: Color

The black terminal color.

red `class-attribute` ¶

red: Color

The red terminal color.

green `class-attribute` ¶

green: Color

The green terminal color.

yellow `class-attribute` ¶

yellow: Color

The yellow terminal color.

blue `class-attribute` ¶

blue: Color

The blue terminal color.

magenta `class-attribute` ¶

magenta: Color

The magenta terminal color.

cyan `class-attribute` ¶

cyan: Color

The cyan terminal color.

gray `class-attribute` ¶

gray: Color

The gray terminal color.

dark_gray `class-attribute` ¶

dark_gray: Color

The dark gray terminal color.

light_red `class-attribute` ¶

light_red: Color

The light red terminal color.

light_green `class-attribute` ¶

light_green: Color

The light green terminal color.

light_yellow `class-attribute` ¶

light_yellow: Color

The light yellow terminal color.

light_blue `class-attribute` ¶

light_blue: Color

The light blue terminal color.

light_magenta `class-attribute` ¶

light_magenta: Color

The light magenta terminal color.

light_cyan `class-attribute` ¶

light_cyan: Color

The light cyan terminal color.

white `class-attribute` ¶

white: Color

The white terminal color.

reset `class-attribute` ¶

reset: Color

The reset terminal color, which follows the terminal theme.

is_reset `property` ¶

is_reset: bool

Whether this is the reset color, which follows the terminal's theme.

parse `classmethod` ¶

parse(value: ColorName | str) -> Color

Parse a color name, hex string or palette index string.

Examples:

assert Color.parse('light_blue') == Color('light_blue')

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def parse(cls, value: ColorName | str) -> Color:
    """
    Parse a color name, hex string or palette index string.

    Examples:
        ```python
        assert Color.parse('light_blue') == Color('light_blue')
        ```
    """

from_tailwind `classmethod` ¶

from_tailwind(palette: TailwindColorName, shade: TailwindColorShade) -> Color

A true color from a Tailwind palette and shade.

Color does not read a name such as 'slate-400'. Pass the palette and the shade here.

Parameters:

palette (TailwindColorName) –

A palette such as 'slate' or 'red'.
shade (TailwindColorShade) –

50, 100 through 900, or 950.

Raises:

ValueError –

palette is not a palette, or shade is not a shade.

Examples:

assert Color.from_tailwind('red', 500).to_rgb() == (239, 68, 68)

Referenced by:

API Reference xnano_core
- xnano_core TailwindColorBinding
- xnano_core._xnano_core._core_types _core_types TailwindColorBinding

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def from_tailwind(
    cls, palette: TailwindColorName, shade: TailwindColorShade
) -> Color:
    """
    A true color from a Tailwind palette and shade.

    ``Color`` does not read a name such as ``'slate-400'``. Pass the palette and the
    shade here.

    Args:
        palette: A palette such as ``'slate'`` or ``'red'``.
        shade: ``50``, ``100`` through ``900``, or ``950``.

    Raises:
        ValueError: ``palette`` is not a palette, or ``shade`` is not a shade.

    Examples:
        ```python
        assert Color.from_tailwind('red', 500).to_rgb() == (239, 68, 68)
        ```
    """

indexed `classmethod` ¶

indexed(index: int) -> Color

A color from the 256-color palette.

Examples:

color = Color.indexed(202)
assert color.to_rgb() is None

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def indexed(cls, index: int) -> Color:
    """
    A color from the 256-color palette.

    Examples:
        ```python
        color = Color.indexed(202)
        assert color.to_rgb() is None
        ```
    """

from_rgb `classmethod` ¶

from_rgb(red: int, green: int, blue: int) -> Color

A true color from red, green and blue values between 0 and 255.

Examples:

assert Color.from_rgb(255, 0, 0).to_rgb() == (255, 0, 0)

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def from_rgb(cls, red: int, green: int, blue: int) -> Color:
    """
    A true color from red, green and blue values between 0 and 255.

    Examples:
        ```python
        assert Color.from_rgb(255, 0, 0).to_rgb() == (255, 0, 0)
        ```
    """

to_rgb ¶

to_rgb() -> tuple[int, int, int] | None

The (red, green, blue) values of a true color, or None for named and indexed colors.

Examples:

assert Color('#010203').to_rgb() == (1, 2, 3)
assert Color.indexed(4).to_rgb() is None

Referenced by:

API Reference
- xnano
  - xnano Color to_hex
  - xnano.styles styles Color to_hex
- xnano_core
  - xnano_core Color to_hex
  - xnano_core._xnano_core _xnano_core Color to_hex

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def to_rgb(self) -> tuple[int, int, int] | None:
    """
    The ``(red, green, blue)`` values of a true color, or ``None`` for named and indexed colors.

    Examples:
        ```python
        assert Color('#010203').to_rgb() == (1, 2, 3)
        assert Color.indexed(4).to_rgb() is None
        ```
    """

to_hex ¶

to_hex() -> str

The color as a '#rrggbb' string.

Only a true color has one, as with to_rgb.

Raises:

ValueError –

The color is named, indexed or reset, which the terminal's theme chooses.

Examples:

assert Color((255, 136, 0)).to_hex() == '#ff8800'
assert Color('#FF8800').to_hex() == '#ff8800'

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def to_hex(self) -> str:
    """
    The color as a ``'#rrggbb'`` string.

    Only a true color has one, as with [`to_rgb`][xnano_core._xnano_core.Color.to_rgb].

    Raises:
        ValueError: The color is named, indexed or ``reset``, which the terminal's theme
            chooses.

    Examples:
        ```python
        assert Color((255, 136, 0)).to_hex() == '#ff8800'
        assert Color('#FF8800').to_hex() == '#ff8800'
        ```
    """

from_hsl `classmethod` ¶

from_hsl(hue: float, saturation: float, lightness: float) -> Color

A true color from hue, saturation and lightness.

Parameters:

hue (float) –

Degrees from 0 to 360.
saturation (float) –

A percentage from 0 to 100.
lightness (float) –

A percentage from 0 to 100.

Raises:

ValueError –

A value is out of range.

Examples:

assert Color.from_hsl(0, 100, 50).to_hex() == '#ff0000'

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def from_hsl(cls, hue: float, saturation: float, lightness: float) -> Color:
    """
    A true color from hue, saturation and lightness.

    Args:
        hue: Degrees from 0 to 360.
        saturation: A percentage from 0 to 100.
        lightness: A percentage from 0 to 100.

    Raises:
        ValueError: A value is out of range.

    Examples:
        ```python
        assert Color.from_hsl(0, 100, 50).to_hex() == '#ff0000'
        ```
    """

from_hsv `classmethod` ¶

from_hsv(hue: float, saturation: float, value: float) -> Color

A true color from hue, saturation and value.

Parameters:

hue (float) –

Degrees from 0 to 360.
saturation (float) –

A percentage from 0 to 100.
value (float) –

A percentage from 0 to 100.

Raises:

ValueError –

A value is out of range.

Examples:

assert Color.from_hsv(120, 100, 100).to_hex() == '#00ff00'

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def from_hsv(cls, hue: float, saturation: float, value: float) -> Color:
    """
    A true color from hue, saturation and value.

    Args:
        hue: Degrees from 0 to 360.
        saturation: A percentage from 0 to 100.
        value: A percentage from 0 to 100.

    Raises:
        ValueError: A value is out of range.

    Examples:
        ```python
        assert Color.from_hsv(120, 100, 100).to_hex() == '#00ff00'
        ```
    """

random `classmethod` ¶

random(base: Color | ColorName | str | tuple[int, int, int] | None = None) -> Color

A random true color, or a random shade of base.

Without base every red, green and blue channel is picked at random. With base the color keeps its hue and saturation and takes a random lightness from 15 to 85 percent, so every color it returns is a lighter or darker shade of base. The colors come from Python's random module, so random.seed(...) repeats them.

Parameters:

base (Color | ColorName | str | tuple[int, int, int] | None, default: None ) –

The color to pick shades of, or None for any color.

Raises:

ValueError –

base is Color.reset, or not a color.

Examples:

import random

random.seed(7)
first = Color.random()
random.seed(7)
assert Color.random() == first

hue, saturation, _ = Color.random('#3366cc').to_hsl()
assert round(hue) == 220 and round(saturation) == 60

Referenced by:

API Reference xnano xnano.appearance appearance ColorSlot random

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

@classmethod
def random(
    cls, base: Color | ColorName | str | tuple[int, int, int] | None = None
) -> Color:
    """
    A random true color, or a random shade of ``base``.

    Without ``base`` every red, green and blue channel is picked at random. With ``base``
    the color keeps its hue and saturation and takes a random lightness from 15 to 85
    percent, so every color it returns is a lighter or darker shade of ``base``. The
    colors come from Python's [`random`](https://docs.python.org/3/library/random.html)
    module, so ``random.seed(...)`` repeats them.

    Args:
        base: The color to pick shades of, or ``None`` for any color.

    Raises:
        ValueError: ``base`` is ``Color.reset``, or not a color.

    Examples:
        ```python
        import random

        random.seed(7)
        first = Color.random()
        random.seed(7)
        assert Color.random() == first

        hue, saturation, _ = Color.random('#3366cc').to_hsl()
        assert round(hue) == 220 and round(saturation) == 60
        ```
    """

to_hsl ¶

to_hsl() -> tuple[float, float, float]

The hue (degrees), saturation and lightness (percentages) of the color.

Named and indexed colors use their standard values.

Raises:

ValueError –

The color is reset.

Examples:

hue, saturation, lightness = Color('#ff0000').to_hsl()
assert round(hue) == 0
assert round(saturation) == 100
assert round(lightness) == 50

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def to_hsl(self) -> tuple[float, float, float]:
    """
    The hue (degrees), saturation and lightness (percentages) of the color.

    Named and indexed colors use their standard values.

    Raises:
        ValueError: The color is ``reset``.

    Examples:
        ```python
        hue, saturation, lightness = Color('#ff0000').to_hsl()
        assert round(hue) == 0
        assert round(saturation) == 100
        assert round(lightness) == 50
        ```
    """

to_hsv ¶

to_hsv() -> tuple[float, float, float]

The hue (degrees), saturation and value (percentages) of the color.

Named and indexed colors use their standard values.

Raises:

ValueError –

The color is reset.

Examples:

hue, saturation, value = Color('#00ff00').to_hsv()
assert round(hue) == 120
assert round(saturation) == 100
assert round(value) == 100

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def to_hsv(self) -> tuple[float, float, float]:
    """
    The hue (degrees), saturation and value (percentages) of the color.

    Named and indexed colors use their standard values.

    Raises:
        ValueError: The color is ``reset``.

    Examples:
        ```python
        hue, saturation, value = Color('#00ff00').to_hsv()
        assert round(hue) == 120
        assert round(saturation) == 100
        assert round(value) == 100
        ```
    """

lerp ¶

lerp(other: Color | ColorName | str | tuple[int, int, int], ratio: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl') -> Color

The color between this one and other.

Parameters:

other (Color | ColorName | str | tuple[int, int, int]) –

The color to blend toward.
ratio (float) –

0.0 is this color and 1.0 is other.
color_space (Literal['rgb', 'hsl', 'hsv'], default: 'hsl' ) –

The space the blend runs through. 'hsl' and 'hsv' keep colors vivid in the middle; 'rgb' is the straight average.

Raises:

ValueError –

A color is reset, or color_space is not a color space.

Examples:

middle = Color('#000000').lerp('#ffffff', 0.5, color_space='rgb')
red, green, blue = middle.to_rgb()
assert red == green == blue
assert 126 <= red <= 129

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def lerp(
    self,
    other: Color | ColorName | str | tuple[int, int, int],
    ratio: float,
    *,
    color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl',
) -> Color:
    """
    The color between this one and ``other``.

    Args:
        other: The color to blend toward.
        ratio: ``0.0`` is this color and ``1.0`` is ``other``.
        color_space: The space the blend runs through. ``'hsl'`` and ``'hsv'`` keep colors
            vivid in the middle; ``'rgb'`` is the straight average.

    Raises:
        ValueError: A color is ``reset``, or ``color_space`` is not a color space.

    Examples:
        ```python
        middle = Color('#000000').lerp('#ffffff', 0.5, color_space='rgb')
        red, green, blue = middle.to_rgb()
        assert red == green == blue
        assert 126 <= red <= 129
        ```
    """

lighten ¶

lighten(amount: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl') -> Color

A lighter color for a positive amount, a darker one for a negative amount.

Parameters:

amount (float) –

A fraction from -1.0 (black) to 1.0 (white).
color_space (Literal['rgb', 'hsl', 'hsv'], default: 'hsl' ) –

The space the change runs through.

Raises:

ValueError –

The color is reset, or color_space is not a color space.

Examples:

base = Color('#336699')
assert base.lighten(0.2).to_hsl()[2] > base.to_hsl()[2]
assert base.lighten(-0.2).to_hsl()[2] < base.to_hsl()[2]

Referenced by:

API Reference
- xnano
  - xnano Color darken
  - xnano.styles styles Color darken
- xnano_core
  - xnano_core Color darken
  - xnano_core._xnano_core _xnano_core Color darken

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def lighten(
    self, amount: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl'
) -> Color:
    """
    A lighter color for a positive ``amount``, a darker one for a negative ``amount``.

    Args:
        amount: A fraction from -1.0 (black) to 1.0 (white).
        color_space: The space the change runs through.

    Raises:
        ValueError: The color is ``reset``, or ``color_space`` is not a color space.

    Examples:
        ```python
        base = Color('#336699')
        assert base.lighten(0.2).to_hsl()[2] > base.to_hsl()[2]
        assert base.lighten(-0.2).to_hsl()[2] < base.to_hsl()[2]
        ```
    """

darken ¶

darken(amount: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl') -> Color

A darker color.

Parameters:

amount (float) –

A fraction from 0.0 (unchanged) to 1.0 (black). Use lighten to make a color lighter.
color_space (Literal['rgb', 'hsl', 'hsv'], default: 'hsl' ) –

The space the change runs through.

Returns:

Color –

The darkened color; the original is unchanged.

Raises:

ValueError –

amount is outside 0.0 to 1.0, the color is reset, or color_space is not a color space.

Examples:

assert Color('#808080').darken(1.0).to_rgb() == (0, 0, 0)
base = Color('#336699')
assert base.darken(0.2).to_hsl()[2] < base.to_hsl()[2]
assert base.darken(0.0) == base

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def darken(
    self, amount: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl'
) -> Color:
    """
    A darker color.

    Args:
        amount: A fraction from 0.0 (unchanged) to 1.0 (black). Use
            [`lighten`][xnano_core._xnano_core.Color.lighten] to make a color lighter.
        color_space: The space the change runs through.

    Returns:
        The darkened color; the original is unchanged.

    Raises:
        ValueError: ``amount`` is outside 0.0 to 1.0, the color is ``reset``, or
            ``color_space`` is not a color space.

    Examples:
        ```python
        assert Color('#808080').darken(1.0).to_rgb() == (0, 0, 0)
        base = Color('#336699')
        assert base.darken(0.2).to_hsl()[2] < base.to_hsl()[2]
        assert base.darken(0.0) == base
        ```
    """

inverse ¶

inverse() -> Color

The color that has each red, green and blue channel inverted.

Named and indexed colors are inverted through their standard values, so the result is always a true color.

Returns:

Color –

The inverted true color; the original is unchanged.

Raises:

ValueError –

The color is reset, which has no fixed value.

Examples:

assert Color('#ff8000').inverse().to_hex() == '#007fff'
assert Color('#ff8000').inverse().inverse() == Color('#ff8000')

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def inverse(self) -> Color:
    """
    The color that has each red, green and blue channel inverted.

    Named and indexed colors are inverted through their standard values, so the result
    is always a true color.

    Returns:
        The inverted true color; the original is unchanged.

    Raises:
        ValueError: The color is ``reset``, which has no fixed value.

    Examples:
        ```python
        assert Color('#ff8000').inverse().to_hex() == '#007fff'
        assert Color('#ff8000').inverse().inverse() == Color('#ff8000')
        ```
    """

saturate ¶

saturate(factor: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl') -> Color

The color with its saturation scaled.

Parameters:

factor (float) –

0.0 removes the saturation, 1.0 keeps it and more than 1.0 boosts it.
color_space (Literal['rgb', 'hsl', 'hsv'], default: 'hsl' ) –

The space the change runs through.

Raises:

ValueError –

The color is reset, or color_space is not a color space.

Examples:

gray = Color('#336699').saturate(0.0)
assert round(gray.to_hsl()[1]) == 0

Source code in packages/xnano-core/src/xnano_core/_xnano_core/__init__.pyi

def saturate(
    self, factor: float, *, color_space: Literal['rgb', 'hsl', 'hsv'] = 'hsl'
) -> Color:
    """
    The color with its saturation scaled.

    Args:
        factor: ``0.0`` removes the saturation, ``1.0`` keeps it and more than ``1.0``
            boosts it.
        color_space: The space the change runs through.

    Raises:
        ValueError: The color is ``reset``, or ``color_space`` is not a color space.

    Examples:
        ```python
        gray = Color('#336699').saturate(0.0)
        assert round(gray.to_hsl()[1]) == 0
        ```
    """

from_audio ¶

from_audio(source: TerminalSound | PathLike[str] | str | bytes, /, *, symbol: str | None = None) -> Audio

Load a sound from a WAV file path or from bytes.

This is Audio with the same arguments. Play the result with canvas.play(sound), or give it a symbol and play it by name.

Parameters:

source (TerminalSound | PathLike[str] | str | bytes) –

The path of a PCM WAV file, the bytes of one, or a TerminalSound.
symbol (str | None, default: None ) –

A name to register the sound under in symbols, so play(name) plays it.

Returns:

Audio –

The Audio.

Raises:

ImportError –

xnano-audio is not installed. Install it with pip install "xnano[audio]".
TypeError –

source is not a path, bytes or a sound.
ValueError –

The file is not a PCM WAV file that xnano can read.
FileNotFoundError –

The path does not exist.

Examples:

import xnano
from xnano_audio import TerminalSound

beep = xnano.from_audio(TerminalSound.from_samples([0.0, 0.5, -0.5, 0.0]), symbol='beep')
with xnano.new(width=8, height=1) as canvas:
    canvas.play('beep')
    canvas.step(delta_seconds=0.1)
    assert canvas.audio.render_sound().peak > 0.0

Source code in xnano/_media.py

def from_audio(
    source: TerminalSound | os.PathLike[str] | str | bytes,
    /,
    *,
    symbol: str | None = None,
) -> Audio:
    """
    Load a sound from a WAV file path or from bytes.

    This is [`Audio`][xnano.Audio] with the same arguments. Play the result with
    ``canvas.play(sound)``, or give it a ``symbol`` and play it by name.

    Args:
        source: The path of a PCM WAV file, the bytes of one, or a
            [`TerminalSound`][xnano_audio.TerminalSound].
        symbol: A name to register the sound under in [`symbols`][xnano.symbols], so
            ``play(name)`` plays it.

    Returns:
        The [`Audio`][xnano.Audio].

    Raises:
        ImportError: ``xnano-audio`` is not installed. Install it with
            ``pip install "xnano[audio]"``.
        TypeError: ``source`` is not a path, bytes or a sound.
        ValueError: The file is not a PCM WAV file that xnano can read.
        FileNotFoundError: The path does not exist.

    Examples:
        ```python
        import xnano
        from xnano_audio import TerminalSound

        beep = xnano.from_audio(TerminalSound.from_samples([0.0, 0.5, -0.5, 0.0]), symbol='beep')
        with xnano.new(width=8, height=1) as canvas:
            canvas.play('beep')
            canvas.step(delta_seconds=0.1)
            assert canvas.audio.render_sound().peak > 0.0
        ```
    """
    return Audio(source, symbol=symbol)

from_image ¶

from_image(source: TerminalImage | 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) -> Image

Load an image or an animation from a file path or from bytes.

This is Image with the same arguments: PNG, JPEG, GIF, WebP and XNI files are read, and an animated one plays on the canvas's clock. Write the result with canvas.write(picture).

Parameters:

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

The path of an image file, the bytes of one, or a TerminalImage.
x (Axis | None, default: None ) –

The column of the left edge; see Image.
y (Axis | None, default: None ) –

The row of the top edge.
width (Axis | None, default: None ) –

The width: cells, a percentage, an expression, or None for the picture's own.
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.
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.

Returns:

Image –

The Image.

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 –

The path does not exist.

Examples:

import xnano
from xnano.image import TerminalImage

picture = xnano.from_image(
    TerminalImage.from_rgba(1, 1, bytes([255, 0, 0, 255])), width=4, symbol='red_dot'
)
assert isinstance(picture, xnano.Image)
assert xnano.symbols.lookup('red_dot') is picture

Referenced by:

API Reference xnano

Source code in xnano/_media.py

def from_image(
    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,
) -> Image:
    """
    Load an image or an animation from a file path or from bytes.

    This is [`Image`][xnano.Image] with the same arguments: PNG, JPEG, GIF, WebP and XNI files
    are read, and an animated one plays on the canvas's clock. Write the result with
    ``canvas.write(picture)``.

    Args:
        source: The path of an image file, the bytes of one, or a
            [`TerminalImage`][xnano_image.TerminalImage].
        x: The column of the left edge; see [`Image`][xnano.Image].
        y: The row of the top edge.
        width: The width: cells, a percentage, an expression, or ``None`` for the picture's own.
        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.
        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].

    Returns:
        The [`Image`][xnano.Image].

    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: The path does not exist.

    Examples:
        ```python
        import xnano
        from xnano.image import TerminalImage

        picture = xnano.from_image(
            TerminalImage.from_rgba(1, 1, bytes([255, 0, 0, 255])), width=4, symbol='red_dot'
        )
        assert isinstance(picture, xnano.Image)
        assert xnano.symbols.lookup('red_dot') is picture
        ```
    """
    return Image(
        source,
        x=x,
        y=y,
        width=width,
        height=height,
        layer=layer,
        lock=lock,
        fit=fit,
        resampling_filter=resampling_filter,
        background=background,
        speed=speed,
        symbol=symbol,
    )

draw ¶

draw(source: str | Sequence[str] | Image | TerminalImage | bytes | bytearray | None = None, palette: Mapping[str, ColorValue] | str | None = None, *, width: int | None = None, height: int | None = None, background: ColorValue | None = None, symbol: str | None = None, effects: Sequence[RenderableEffectSpecification] = ()) -> Art

Build pixel art from text, a picture, bytes or nothing (does not draw).

This is how pixel-art sprites are written in code, one character per pixel. Nothing is drawn: the art is a value that you write into a canvas. Text rows (a multi-line string, which may be indented, or a list of rows) are painted with a palette that says what each character means; any character the palette does not name, such as '.', is a transparent pixel. The palette is a mapping, or one string of character=color pairs.

What source is decides what is made:

Text with a newline, or a list of rows: pixel art painted with palette.
Text without a newline: the name of a registered art or image (see symbols); you get a copy of the art, or the pixels of the image. A one-row picture is a list, draw(['GG'], palette), so that a call never changes meaning because a symbol was registered later.
An Image or a picture from xnano.image: its pixels are copied (the first frame of an animation).
bytes of red, green, blue and alpha, with width and height.
None: a blank world of width by height pixels filled with background.

Parameters:

source (str | Sequence[str] | Image | TerminalImage | bytes | bytearray | None, default: None ) –

What to draw.
palette (Mapping[str, ColorValue] | str | None, default: None ) –

The color of each character of text rows, as a mapping to names, '#rrggbb' strings or (red, green, blue) tuples, or as a string such as 'R=#e03040 G=green'.
width (int | None, default: None ) –

The width in pixels of bytes or of a blank world.
height (int | None, default: None ) –

The height in pixels.
background (ColorValue | None, default: None ) –

The color behind the art. Transparent pixels show it.
symbol (str | None, default: None ) –

A name to register the art under, so draw('name') returns a copy of it.
effects (Sequence[RenderableEffectSpecification], default: () ) –

Effects to start on the placement when the art is written, as dictionaries with a kind key.

Raises:

ValueError –

The rows are empty or differ in length, the palette or a color in it is not valid, a text without a newline is not a known symbol, or the sizes do not match the bytes.
TypeError –

source is not one of the kinds above.

Examples:

import xnano

heart = xnano.draw(
    '''
    .RR.RR.
    RRRRRRR
    .RRRRR.
    ..RRR..
    ...R...
    ''',
    'R=#e03040',
)
assert (heart.width, heart.height) == (7, 5)
print(heart.render())

xnano.draw(['G'], {'G': 'green'}, symbol='grass')
assert xnano.draw('grass').width == 1

Referenced by:

Source code in xnano/art.py

def draw(
    source: str | Sequence[str] | Image | TerminalImage | bytes | bytearray | None = None,
    palette: Mapping[str, ColorValue] | str | None = None,
    *,
    width: int | None = None,
    height: int | None = None,
    background: ColorValue | None = None,
    symbol: str | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
) -> Art:
    """
    Build pixel art from text, a picture, bytes or nothing (does not draw).

    This is how pixel-art sprites are written in code, one character per pixel. Nothing is
    drawn: the art is a value that you write into a canvas. Text rows (a multi-line string, which
    may be indented, or a list of rows) are painted with a palette that says what each
    character means; any character the palette does not name, such as ``'.'``, is a
    transparent pixel. The palette is a mapping, or one string of ``character=color`` pairs.

    What ``source`` is decides what is made:

    * Text with a newline, or a list of rows: pixel art painted with ``palette``.
    * Text without a newline: the name of a registered art or image (see
      [`symbols`][xnano.symbols]); you get a copy of the art, or the pixels of the image.
      A one-row picture is a list, ``draw(['GG'], palette)``, so that a call never changes
      meaning because a symbol was registered later.
    * An [`Image`][xnano.Image] or a picture from ``xnano.image``: its pixels are copied
      (the first frame of an animation).
    * ``bytes`` of red, green, blue and alpha, with ``width`` and ``height``.
    * ``None``: a blank world of ``width`` by ``height`` pixels filled with ``background``.

    Args:
        source: What to draw.
        palette: The color of each character of text rows, as a mapping to names,
            ``'#rrggbb'`` strings or ``(red, green, blue)`` tuples, or as a string such as
            ``'R=#e03040 G=green'``.
        width: The width in pixels of ``bytes`` or of a blank world.
        height: The height in pixels.
        background: The color behind the art. Transparent pixels show it.
        symbol: A name to register the art under, so ``draw('name')`` returns a copy of it.
        effects: Effects to start on the placement when the art is written, as dictionaries
            with a ``kind`` key.

    Raises:
        ValueError: The rows are empty or differ in length, the palette or a color in it is
            not valid, a text without a newline is not a known symbol, or the sizes do not
            match the bytes.
        TypeError: ``source`` is not one of the kinds above.

    Examples:
        ```python
        import xnano

        heart = xnano.draw(
            '''
            .RR.RR.
            RRRRRRR
            .RRRRR.
            ..RRR..
            ...R...
            ''',
            'R=#e03040',
        )
        assert (heart.width, heart.height) == (7, 5)
        print(heart.render())

        xnano.draw(['G'], {'G': 'green'}, symbol='grass')
        assert xnano.draw('grass').width == 1
        ```
    """
    if isinstance(source, str) and '\n' not in source:
        from xnano._media import Image as MediaImage

        if source in symbols.names(kind=MediaImage):
            # The name of a registered image draws that image.
            source = symbols.lookup(source, kind=MediaImage)
    if isinstance(source, str) and '\n' not in source:
        try:
            registered = symbols.lookup(source, kind=Art)
        except ValueError as error:
            raise ValueError(
                f'{error} To draw a one-row picture, pass a list: draw([{source!r}], '
                f'palette).'
            ) from None
        art = registered._copy()
        if background is not None:
            art.background = background
        effects = cast(
            'tuple[RenderableEffectSpecification, ...]',
            effect_sequence(effects, 'renderable'),
        )
        if effects:
            for effect in effects:
                normalize_effect(effect, 'renderable')
            art._effects = effects
        if symbol is not None:
            symbols.register(symbol, art)
            art._symbol = symbol
        return art
    rgba, pixel_width, pixel_height = _pixels_of(source, palette, width, height)
    return Art(
        rgba,
        pixel_width,
        pixel_height,
        background=background,
        symbol=symbol,
        effects=effects,
    )

active ¶

active() -> Canvas[object, object]

active(*, is_required: Literal[True]) -> Canvas[object, object]

active(*, is_required: Literal[False]) -> Canvas[object, object] | None

active(*, is_required: bool = True) -> Canvas[object, object] | None

Return the innermost canvas that is running in this thread or task.

A canvas is active from the moment it is created until it ends: the most recently created one wins, and a canvas that was asked to quit gives way to the one created before it. A canvas created inside the with block of another one belongs to that canvas, so the outer canvas stays active. Hooks run on a canvas's loop see that canvas.

Parameters:

is_required (bool, default: True ) –

Whether to raise when no canvas is running.

Raises:

TerminalClosedError –

No canvas is running and is_required is true.

Examples:

import xnano

assert xnano.active(is_required=False) is None
with xnano.new(width=4, height=1) as outer:
    assert xnano.active() is outer
    with xnano.new(width=4, height=1):
        assert xnano.active() is outer
assert xnano.active(is_required=False) is None

Referenced by:

API Reference xnano
- xnano
  - new
  - open
  - play
- xnano.canvas canvas new
- xnano.music music play
- xnano.terminal terminal open

Source code in xnano/canvas.py

def active(*, is_required: bool = True) -> Canvas[object, object] | None:
    """
    Return the innermost canvas that is running in this thread or task.

    A canvas is active from the moment it is created until it ends: the most recently created
    one wins, and a canvas that was asked to [`quit`][xnano.canvas.Canvas.quit] gives way to the
    one created before it. A canvas created inside the ``with`` block of another one belongs
    to that canvas, so the outer canvas stays active. Hooks run on a canvas's loop see that
    canvas.

    Args:
        is_required: Whether to raise when no canvas is running.

    Raises:
        TerminalClosedError: No canvas is running and ``is_required`` is true.

    Examples:
        ```python
        import xnano

        assert xnano.active(is_required=False) is None
        with xnano.new(width=4, height=1) as outer:
            assert xnano.active() is outer
            with xnano.new(width=4, height=1):
                assert xnano.active() is outer
        assert xnano.active(is_required=False) is None
        ```
    """
    canvas = next(
        (
            candidate
            for candidate in _live_canvases()
            if candidate.is_running and candidate._canvas is candidate
        ),
        None,
    )
    if canvas is None and is_required:
        raise TerminalClosedError(
            'No canvas is running. Create one with "with xnano.new() as canvas:" or '
            '"with xnano.open() as terminal:", and call this inside the block.'
        )
    return canvas

iter ¶

iter(*, count: int | None = None, seconds: float | None = None) -> Iterator[Frame]

Iterate over the frames of the active canvas, drawing between them.

This is Canvas.iter for the innermost running canvas, so a loop does not need the canvas in hand.

Parameters:

count (int | None, default: None ) –

The most frames to yield.
seconds (float | None, default: None ) –

The most seconds of the canvas's time to run for.

Raises:

TerminalClosedError –

No canvas is running.

Examples:

import xnano

with xnano.new(width=8, height=1) as canvas:
    ball = canvas.write('o')
    for frame in xnano.iter(count=3):
        ball.x = frame.index
    assert ball.x == 2

Source code in xnano/canvas.py

def iter(*, count: int | None = None, seconds: float | None = None) -> Iterator[Frame]:
    """
    Iterate over the frames of the active canvas, drawing between them.

    This is [`Canvas.iter`][xnano.canvas.Canvas.iter] for the innermost running canvas, so a
    loop does not need the canvas in hand.

    Args:
        count: The most frames to yield.
        seconds: The most seconds of the canvas's time to run for.

    Raises:
        TerminalClosedError: No canvas is running.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1) as canvas:
            ball = canvas.write('o')
            for frame in xnano.iter(count=3):
                ball.x = frame.index
            assert ball.x == 2
        ```
    """
    return active().iter(count=count, seconds=seconds)

new ¶

new(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float | None = None, bpm: float | None = None, realtime: bool = False, title: str | None = None, effects: Sequence[RenderableEffectSpecification] = (), **settings: Unpack[CanvasSettings]) -> Canvas[None, None]

new(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float | None = None, bpm: float | None = None, realtime: bool = False, title: str | None = None, effects: Sequence[RenderableEffectSpecification] = (), state: StateT, **settings: Unpack[CanvasSettings]) -> Canvas[None, StateT]

new(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float | None = None, bpm: float | None = None, realtime: bool = False, title: str | None = None, effects: Sequence[RenderableEffectSpecification] = (), deps: DepsT, **settings: Unpack[CanvasSettings]) -> Canvas[DepsT, None]

new(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float | None = None, bpm: float | None = None, realtime: bool = False, title: str | None = None, effects: Sequence[RenderableEffectSpecification] = (), deps: DepsT, state: StateT, **settings: Unpack[CanvasSettings]) -> Canvas[DepsT, StateT]

new(content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None, /, *, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float | None = None, bpm: float | None = None, realtime: bool = False, title: str | None = None, effects: Sequence[RenderableEffectSpecification] = (), deps: object = _UNSET, state: object = _UNSET, **settings: object) -> Canvas[DepsT, StateT]

Create a canvas: a virtual terminal with a clock, hooks, sound, a cursor and state.

It has no screen and draws into memory. Its clock moves only when you move it, with step or iter, so every run is the same; realtime=True runs it on the wall clock on a thread of its own instead. Canvas.open (or open) puts it on the screen. A with block closes it.

A canvas with a manual clock belongs to the thread that created it: use it, and close it, on that thread, for example with a with block in the worker that made it. A canvas that several threads use, or that is closed after its thread has ended, is created with realtime=True.

content, when given, is written at the top-left corner, as canvas.write(content) would. The appearance keywords (colors, text modifiers, border, border_style) style the canvas itself, not its content, so they are accepted only without content: new(border='rounded') borders the canvas, and new().write('hello', border='rounded') borders the text. A canvas's foreground and background color the cells no content covers. padding and margin pad and space the canvas itself. title is the window title.

Created inside the with block of another canvas, the new canvas belongs to that one from the start but is hidden in it: its size is measured in that canvas ('50%' is half of it, and no size fills it), it runs on that canvas's time and its hooks hear that canvas's input. outer.write(canvas, x=..., y=...) shows it, once, where it is written. Leaving its own with block keeps it; it closes with the canvas it belongs to. Inside its with block, outer.write(...) places content within the new canvas's area of outer. It takes that canvas's edges unless given its own. Canvas.new creates a canvas that is shown at once. A canvas given state or deps stays on its own, because those belong to the outermost canvas: it is measured in the canvas around it, takes its fps, bpm and edges unless given its own, and closes with it.

The input gates (mouse, scroll, keyboard, paste, focus, interrupt, capture, clear, alternate_screen) are stored and take effect when the canvas is opened on the screen; see GateSettings.

Parameters:

content (Content | Canvas[WrittenDepsT, WrittenStateT] | None, default: None ) –

Something to write into the canvas at once, such as text or a widget.
width (int | Percentage | str | None, default: None ) –

The width in cells, or a percentage of the window such as '50%', read when the canvas is created; 80 when None. On the screen it is the width of the region the canvas draws in, read again when it is opened.
height (int | Percentage | str | None, default: None ) –

The height in cells, or a percentage of the window such as '50%'; 24 when None. On the screen it is the height of the region the canvas draws in, and '100%' for both sizes fills the whole window.
fps (float | None, default: None ) –

The most frames drawn per second, and the length of one step of iter(); the enclosing canvas's, else 60, when None.
bpm (float | None, default: None ) –

Beats per minute for beat timers, notes and melodies; the enclosing canvas's, else 120, when None.
realtime (bool, default: False ) –

Whether the canvas runs by itself on the wall clock, on a thread of its own.
title (str | None, default: None ) –

The window title, shown when the canvas is on the screen.
effects (Sequence[RenderableEffectSpecification], default: () ) –

Effects to apply to the canvas, as dictionaries with a kind key.
deps (object, default: _UNSET ) –

Dependencies that hooks read as context.deps; the canvas never reads them.
state (object, default: _UNSET ) –

A dataclass instance the canvas keeps and validates. Hooks read and write it.
settings (object, default: {} ) –

The input gates and the canvas's own look; see CanvasSettings.

Returns:

Canvas[DepsT, StateT] –

The Canvas, which is also the one module-level functions such
Canvas[DepsT, StateT] –

as active find.

Raises:

TypeError –

An appearance keyword was given with content, or a keyword is unknown.
ValueError –

A size (1 to 65535 cells), fps, bpm, realtime, gate or border kind is out of range.

Examples:

import xnano

with xnano.new(width=16, height=3) as canvas:
    assert (canvas.width, canvas.height) == (16, 3)
    assert xnano.active() is canvas
    assert not canvas.time.is_realtime

with xnano.new('hello', width=8, height=1) as greeting:
    assert greeting.render() == 'hello'

with xnano.new(width=12, height=4) as outer:
    with xnano.new(height='50%') as inner:
        inner.write('inside')
    assert (inner.width, inner.height) == (12, 2)
    assert outer.render().strip() == ''
    outer.write(inner, y=2)
    assert outer.render().splitlines()[2] == 'inside'
    assert xnano.active() is outer

Referenced by:

API Reference xnano
- xnano
  - Canvas
    - new
    - write
  - Terminal
    - new
    - write
  - open
  - play
- xnano.canvas canvas Canvas
  - new
  - write
- xnano.music music
  - PlayHandle remove
  - play
- xnano.terminal terminal
  - Terminal
    - new
    - write
  - open
- xnano.types types CanvasSettings
Getting Started Put it on a canvas

Source code in xnano/canvas.py

def new(
    content: Content | Canvas[WrittenDepsT, WrittenStateT] | None = None,
    /,
    *,
    width: int | Percentage | str | None = None,
    height: int | Percentage | str | None = None,
    fps: float | None = None,
    bpm: float | None = None,
    realtime: bool = False,
    title: str | None = None,
    effects: Sequence[RenderableEffectSpecification] = (),
    deps: object = _UNSET,
    state: object = _UNSET,
    **settings: object,
) -> Canvas[DepsT, StateT]:
    """
    Create a canvas: a virtual terminal with a clock, hooks, sound, a cursor and state.

    It has no screen and draws into memory. Its clock moves only when you move it, with
    [`step`][xnano.canvas.Canvas.step] or [`iter`][xnano.canvas.Canvas.iter], so every run is
    the same; ``realtime=True`` runs it on the wall clock on a thread of its own instead.
    [`Canvas.open`][xnano.canvas.Canvas.open] (or [`open`][xnano.open]) puts it on the screen.
    A ``with`` block closes it.

    A canvas with a manual clock belongs to the thread that created it: use it, and close it,
    on that thread, for example with a ``with`` block in the worker that made it. A canvas
    that several threads use, or that is closed after its thread has ended, is created with
    ``realtime=True``.

    ``content``, when given, is written at the top-left corner, as ``canvas.write(content)``
    would. The appearance keywords (colors, text modifiers, ``border``, ``border_style``)
    style the canvas itself, not its content, so they are accepted only without content:
    ``new(border='rounded')`` borders the canvas, and ``new().write('hello', border='rounded')``
    borders the text. A canvas's ``foreground`` and ``background`` color the cells no content
    covers. ``padding`` and ``margin`` pad and space the canvas itself. ``title`` is the
    window title.

    Created inside the ``with`` block of another canvas, the new canvas belongs to that one
    from the start but is hidden in it: its size is measured in that canvas (``'50%'`` is
    half of it, and no size fills it), it runs on that canvas's time and its hooks hear that
    canvas's input. ``outer.write(canvas, x=..., y=...)`` shows it, once, where it is
    written. Leaving its own ``with`` block keeps it; it closes with the canvas it belongs
    to. Inside its ``with`` block, ``outer.write(...)`` places content within the new
    canvas's area of ``outer``. It takes that canvas's ``edges`` unless given its own.
    [`Canvas.new`][xnano.canvas.Canvas.new] creates a canvas that is shown at once. A canvas
    given ``state`` or ``deps`` stays on its own, because those belong to the outermost
    canvas: it is measured in the canvas around it, takes its ``fps``, ``bpm`` and ``edges``
    unless given its own, and closes with it.

    The input gates (``mouse``, ``scroll``, ``keyboard``, ``paste``, ``focus``, ``interrupt``,
    ``capture``, ``clear``, ``alternate_screen``) are stored and take effect when the canvas
    is opened on the screen; see [`GateSettings`][xnano.types.GateSettings].

    Args:
        content: Something to write into the canvas at once, such as text or a widget.
        width: The width in cells, or a percentage of the window such as ``'50%'``, read
            when the canvas is created; 80 when ``None``. On the screen it is the width of
            the region the canvas draws in, read again when it is opened.
        height: The height in cells, or a percentage of the window such as ``'50%'``; 24
            when ``None``. On the screen it is the height of the region the canvas draws
            in, and ``'100%'`` for both sizes fills the whole window.
        fps: The most frames drawn per second, and the length of one step of ``iter()``;
            the enclosing canvas's, else 60, when ``None``.
        bpm: Beats per minute for beat timers, notes and melodies; the enclosing canvas's,
            else 120, when ``None``.
        realtime: Whether the canvas runs by itself on the wall clock, on a thread of its own.
        title: The window title, shown when the canvas is on the screen.
        effects: Effects to apply to the canvas, as dictionaries with a ``kind`` key.
        deps: Dependencies that hooks read as ``context.deps``; the canvas never reads them.
        state: A dataclass instance the canvas keeps and validates. Hooks read and write it.
        settings: The input gates and the canvas's own look; see
            [`CanvasSettings`][xnano.types.CanvasSettings].

    Returns:
        The [`Canvas`][xnano.canvas.Canvas], which is also the one module-level functions such
        as [`active`][xnano.active] find.

    Raises:
        TypeError: An appearance keyword was given with content, or a keyword is unknown.
        ValueError: A size (1 to 65535 cells), ``fps``, ``bpm``, ``realtime``, gate or border kind is out of
            range.

    Examples:
        ```python
        import xnano

        with xnano.new(width=16, height=3) as canvas:
            assert (canvas.width, canvas.height) == (16, 3)
            assert xnano.active() is canvas
            assert not canvas.time.is_realtime

        with xnano.new('hello', width=8, height=1) as greeting:
            assert greeting.render() == 'hello'

        with xnano.new(width=12, height=4) as outer:
            with xnano.new(height='50%') as inner:
                inner.write('inside')
            assert (inner.width, inner.height) == (12, 2)
            assert outer.render().strip() == ''
            outer.write(inner, y=2)
            assert outer.render().splitlines()[2] == 'inside'
            assert xnano.active() is outer
        ```
    """
    enclosing = _enclosing_canvas()
    canvas: Canvas[DepsT, StateT] = _create(
        content,
        width=width,
        height=height,
        fps=fps,
        bpm=bpm,
        realtime=realtime,
        title=title,
        effects=effects,
        deps=deps,
        state=state,
        enclosing=enclosing,
        **settings,
    )
    if enclosing is not None and deps is _UNSET and state is _UNSET:
        try:
            placement = enclosing._canvas._place_on(
                enclosing._content,
                cast('Canvas[object, object]', canvas),
                parent_owner=enclosing,
            )
            placement.is_visible = False
        except BaseException:
            canvas.close(raise_failure=False)
            raise
        canvas._is_hidden_until_written = True
    return canvas

playable ¶

playable(function: Callable[[], Playable]) -> PlayableFunction[[], None, None]

playable(function: Callable[Concatenate[Context[DepsT, StateT], ParametersT], Playable]) -> PlayableFunction[ParametersT, DepsT, StateT]

playable(function: Callable[Concatenate[Context[DepsT, StateT], ParametersT], Playable] | Callable[[], Playable]) -> PlayableFunction[ParametersT, DepsT, StateT] | PlayableFunction[[], None, None]

Turn a function into a component that plays itself.

The function takes the Context first, then its own parameters, and returns anything canvas.play accepts; a function with no parameters at all is called without the context. It is evaluated once when played, and again on a beat only when it read something that changes (the time or the beat, a state path or an input), playing the new result each time. canvas.play returns a PlayHandle whose remove() stops it.

Parameters:

function (Callable[Concatenate[Context[DepsT, StateT], ParametersT], Playable] | Callable[[], Playable]) –

The function (context, **own_parameters) -> playable.

Raises:

TypeError –

The decorated object is a class or is not callable, or the function's first parameter is keyword-only or variadic, so it cannot take the context.

Examples:

import xnano

@xnano.playable
def chord(context: xnano.Context, root: str = 'C4') -> xnano.Note:
    return xnano.note(root, beats=0.5)

with xnano.new(width=8, height=1) as canvas:
    canvas.play(chord(root='E4'))
    canvas.step(delta_seconds=0.5)
    assert canvas.audio.render_sound().peak > 0.0

Referenced by:

Source code in xnano/components.py

def playable(  # pyright: ignore[reportGeneralTypeIssues]
    function: Callable[Concatenate[Context[DepsT, StateT], ParametersT], Playable]
    | Callable[[], Playable],
    /,
) -> PlayableFunction[ParametersT, DepsT, StateT] | PlayableFunction[[], None, None]:
    """
    Turn a function into a component that plays itself.

    The function takes the [`Context`][xnano.context.Context] first, then its own parameters,
    and returns anything ``canvas.play`` accepts; a function with no parameters at all is
    called without the context. It is evaluated once when played, and again
    on a beat only when it read something that changes (the time or the beat, a state path or
    an input), playing the new result each time. ``canvas.play`` returns a
    [`PlayHandle`][xnano.music.PlayHandle] whose ``remove()`` stops it.

    Args:
        function: The function ``(context, **own_parameters) -> playable``.

    Raises:
        TypeError: The decorated object is a class or is not callable, or the function's
            first parameter is keyword-only or variadic, so it cannot take the context.

    Examples:
        ```python
        import xnano

        @xnano.playable
        def chord(context: xnano.Context, root: str = 'C4') -> xnano.Note:
            return xnano.note(root, beats=0.5)

        with xnano.new(width=8, height=1) as canvas:
            canvas.play(chord(root='E4'))
            canvas.step(delta_seconds=0.5)
            assert canvas.audio.render_sound().peak > 0.0
        ```
    """
    return PlayableFunction(
        cast(
            'Callable[Concatenate[Context[DepsT, StateT], ParametersT], Playable]',
            function,
        )
    )

renderable ¶

renderable(function: Callable[[], Renderable]) -> RenderableFunction[[], None, None]

renderable(function: Callable[Concatenate[Context[DepsT, StateT], ParametersT], Renderable]) -> RenderableFunction[ParametersT, DepsT, StateT]

renderable(function: Callable[Concatenate[Context[DepsT, StateT], ParametersT], Renderable] | Callable[[], Renderable]) -> RenderableFunction[ParametersT, DepsT, StateT] | RenderableFunction[[], None, None]

Turn a function into a component that draws itself.

The function takes the Context first, then its own parameters, and returns anything canvas.write accepts; a function with no parameters at all is called without the context. The decorated object is the component: canvas.write(gauge) draws it with its defaults, canvas.write(gauge(ratio=0.7)) gives it parameters, and gauge.hook(...) adds behavior to its placements.

A component is evaluated once, and again only when it read something that changes: the time or the event (every frame), the size of its buffer, the parent or the canvas (when the screen is resized), a state path (when it changes), or an input such as context.keyboard (when it arrives). What it reads is recorded as it runs. Reads of context.deps and of mutable fields on self are not tracked: when they change, call placement.refresh().

Parameters:

function (Callable[Concatenate[Context[DepsT, StateT], ParametersT], Renderable] | Callable[[], Renderable]) –

The function (context, **own_parameters) -> content.

Raises:

TypeError –

The decorated object is a class or is not callable, or the function's first parameter is keyword-only or variadic, so it cannot take the context.

Examples:

import xnano

@xnano.renderable
def gauge(context: xnano.Context, ratio: float = 0.5) -> str:
    return '#' * round(ratio * 10)

with xnano.new(width=12, height=1) as canvas:
    canvas.write(gauge(ratio=0.3))
    assert canvas.render().strip() == '###'

Referenced by:

Source code in xnano/components.py

def renderable(  # pyright: ignore[reportGeneralTypeIssues]
    function: Callable[Concatenate[Context[DepsT, StateT], ParametersT], Renderable]
    | Callable[[], Renderable],
    /,
) -> RenderableFunction[ParametersT, DepsT, StateT] | RenderableFunction[[], None, None]:
    """
    Turn a function into a component that draws itself.

    The function takes the [`Context`][xnano.context.Context] first, then its own parameters,
    and returns anything ``canvas.write`` accepts; a function with no parameters at all is
    called without the context. The decorated object is the component:
    ``canvas.write(gauge)`` draws it with its defaults, ``canvas.write(gauge(ratio=0.7))`` gives
    it parameters, and ``gauge.hook(...)`` adds behavior to its placements.

    A component is evaluated once, and again only when it read something that changes: the
    time or the event (every frame), the size of its buffer, the parent or the canvas (when
    the screen is resized), a state path (when it changes), or an input such as
    ``context.keyboard`` (when it arrives). What it reads is recorded as it runs. Reads of
    ``context.deps`` and of mutable fields on ``self`` are not tracked: when they change, call
    [`placement.refresh()`][xnano.placement.Placement.refresh].

    Args:
        function: The function ``(context, **own_parameters) -> content``.

    Raises:
        TypeError: The decorated object is a class or is not callable, or the function's
            first parameter is keyword-only or variadic, so it cannot take the context.

    Examples:
        ```python
        import xnano

        @xnano.renderable
        def gauge(context: xnano.Context, ratio: float = 0.5) -> str:
            return '#' * round(ratio * 10)

        with xnano.new(width=12, height=1) as canvas:
            canvas.write(gauge(ratio=0.3))
            assert canvas.render().strip() == '###'
        ```
    """
    return RenderableFunction(
        cast(
            'Callable[Concatenate[Context[DepsT, StateT], ParametersT], Renderable]',
            function,
        )
    )

note ¶

note(pitch: Pitch | Sequence[Pitch], *, beats: float = 1.0, instrument: InstrumentName = 'piano', velocity: float = 0.8, effects: Sequence[PlayableEffectSpecification] = (), symbol: str | None = None) -> Note

Make a Note: a pitch, or several for a chord, with its length and sound.

Nothing is played and no sound device is needed. Play it with play or Canvas.play. symbol='kick' registers the note, and then play('kick') plays it.

Parameters:

pitch (Pitch | Sequence[Pitch]) –

A note name such as 'C#4', a MIDI number from 0 to 127, or a sequence of them for a chord.
beats (float, default: 1.0 ) –

How long the note is held, in beats.
instrument (InstrumentName, default: 'piano' ) –

A built-in instrument, from instrument_names.
velocity (float, default: 0.8 ) –

How hard the note is played, from 0.0 to 1.0.
effects (Sequence[PlayableEffectSpecification], default: () ) –

Sound effects as dictionaries with a kind key, such as {'kind': 'audio.reverb'}.
symbol (str | None, default: None ) –

A name to register the note under in symbols. A str given to play is looked up as a symbol name before it is read as a note name, so the name must not look like a note.

Raises:

TypeError –

The pitch is not a note name or a number.
ValueError –

A value is out of range or the instrument is unknown.

Examples:

import xnano

kick = xnano.note('C2', instrument='kick', symbol='kick_drum')
with xnano.new(width=8, height=1) as canvas:
    canvas.play('kick_drum')
    canvas.step(delta_seconds=0.5)
    assert canvas.audio.render_sound().peak > 0.0

Referenced by:

Source code in xnano/music.py

def note(
    pitch: Pitch | Sequence[Pitch],
    *,
    beats: float = 1.0,
    instrument: InstrumentName = 'piano',
    velocity: float = 0.8,
    effects: Sequence[PlayableEffectSpecification] = (),
    symbol: str | None = None,
) -> Note:
    """
    Make a [`Note`][xnano.Note]: a pitch, or several for a chord, with its length and sound.

    Nothing is played and no sound device is needed. Play it with [`play`][xnano.play] or
    [`Canvas.play`][xnano.canvas.Canvas.play]. ``symbol='kick'`` registers the note, and then
    ``play('kick')`` plays it.

    Args:
        pitch: A note name such as ``'C#4'``, a MIDI number from 0 to 127, or a sequence of
            them for a chord.
        beats: How long the note is held, in beats.
        instrument: A built-in instrument, from
            [`instrument_names`][xnano_audio.instrument_names].
        velocity: How hard the note is played, from 0.0 to 1.0.
        effects: Sound effects as dictionaries with a ``kind`` key, such as
            ``{'kind': 'audio.reverb'}``.
        symbol: A name to register the note under in [`symbols`][xnano.symbols]. A ``str``
            given to [`play`][xnano.play] is looked up as a symbol name before it is read as a
            note name, so the name must not look like a note.

    Raises:
        TypeError: The pitch is not a note name or a number.
        ValueError: A value is out of range or the instrument is unknown.

    Examples:
        ```python
        import xnano

        kick = xnano.note('C2', instrument='kick', symbol='kick_drum')
        with xnano.new(width=8, height=1) as canvas:
            canvas.play('kick_drum')
            canvas.step(delta_seconds=0.5)
            assert canvas.audio.render_sound().peak > 0.0
        ```
    """
    chord = (
        tuple(pitch)
        if isinstance(pitch, Sequence) and not isinstance(pitch, str)
        else pitch
    )
    return Note(
        chord,  # type: ignore[arg-type]
        beats=beats,
        instrument=instrument,
        velocity=velocity,
        effects=effect_sequence(effects, 'playable'),  # type: ignore[arg-type]
        symbol=symbol,
    )

play ¶

play(playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle

Play a note, a sound, a symbol name, a melody or a sequence of those.

The sound goes to the running canvas (see active); with no canvas running it goes to this computer's sound output. On a canvas from new, which has a clock you move, the sound is recorded and makes no noise: read it with canvas.audio.render_sound().

A str is a symbol name first, so play('kick') plays the note or sound registered with symbol='kick'. Any other str is a note name such as 'C#4', a frequency such as '440hz' or melody text: notes separated by spaces, :2 holds a note for two beats, rest is a silence, + joins a chord and | marks a bar, as in 'C4 E4 G4:2 rest C5+E5+G5'. A sequence plays one after another. An option replaces the same value on a Note, so play(note('C4'), instrument='violin') plays the violin.

Parameters:

playable (PlaySource) –

What to play.
**options (Unpack[PlayOptions], default: {} ) –

See PlayOptions: instrument, velocity, effects, volume, pan, at_beat and beats, the length in beats of a note name, a number or a Note.

Returns:

PlayHandle –

A PlayHandle.

Raises:

ImportError –

xnano-audio is not installed. Install it with pip install "xnano[audio]".
TerminalAudioUnavailableError –

No canvas is running and this computer has no sound output device.
ValueError –

An option is out of range, or a str is neither a symbol, a note name nor melody text. The message lists the known sound symbols.

Examples:

import xnano

with xnano.new(width=8, height=1) as canvas:
    xnano.play([xnano.note('C4'), xnano.note('E4'), xnano.note('G4')])
    canvas.step(delta_seconds=1.5)
    assert canvas.audio.render_sound().peak > 0.0

Referenced by:

API Reference xnano
- xnano
  - Note
  - note
- xnano.audio audio PlaySource
- xnano.music music
  - Note
  - PlayHandle
  - note
- xnano.types types

Source code in xnano/music.py

def play(playable: PlaySource, /, **options: Unpack[PlayOptions]) -> PlayHandle:
    """
    Play a note, a sound, a symbol name, a melody or a sequence of those.

    The sound goes to the running canvas (see [`active`][xnano.active]); with no canvas
    running it goes to this computer's sound output. On a canvas from [`new`][xnano.new],
    which has a clock you move, the sound is recorded and makes no noise: read it with
    ``canvas.audio.render_sound()``.

    A ``str`` is a symbol name first, so ``play('kick')`` plays the note or sound registered
    with ``symbol='kick'``. Any other ``str`` is a note name such as ``'C#4'``, a frequency such
    as ``'440hz'`` or melody text: notes separated by spaces, ``:2`` holds a note for two
    beats, ``rest`` is a silence, ``+`` joins a chord and ``|`` marks a bar, as in
    ``'C4 E4 G4:2 rest C5+E5+G5'``. A sequence plays one after another. An option replaces
    the same value on a [`Note`][xnano.Note], so ``play(note('C4'), instrument='violin')``
    plays the violin.

    Args:
        playable: What to play.
        **options: See [`PlayOptions`][xnano.types.PlayOptions]: ``instrument``, ``velocity``,
            ``effects``, ``volume``, ``pan``, ``at_beat`` and ``beats``, the length in beats
            of a note name, a number or a ``Note``.

    Returns:
        A [`PlayHandle`][xnano.music.PlayHandle].

    Raises:
        ImportError: ``xnano-audio`` is not installed. Install it with
            ``pip install "xnano[audio]"``.
        TerminalAudioUnavailableError: No canvas is running and this computer has no sound
            output device.
        ValueError: An option is out of range, or a ``str`` is neither a symbol, a note name
            nor melody text. The message lists the known sound symbols.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1) as canvas:
            xnano.play([xnano.note('C4'), xnano.note('E4'), xnano.note('G4')])
            canvas.step(delta_seconds=1.5)
            assert canvas.audio.render_sound().peak > 0.0
        ```
    """
    from xnano.canvas import active

    canvas = active(is_required=False)
    if canvas is not None:
        return canvas.play(playable, **options)
    return _default_player().play(playable, **options)

hook ¶

hook(function: Hook[DepsT, StateT]) -> ContextualOperation[DepsT, StateT]

hook(*, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> Callable[[Hook[DepsT, StateT]], ContextualOperation[DepsT, StateT]]

hook(function: Hook[DepsT, StateT] | None = None, /, *, on: HookKind | None = None, when: When[DepsT, StateT] | None = None, every: float | None = None, after: float | None = None, keys: KeyName | Sequence[KeyName] | None = None, requires_deps: bool = False) -> ContextualOperation[DepsT, StateT] | Callable[[Hook[DepsT, StateT]], ContextualOperation[DepsT, StateT]]

Describe a hook once, to attach to any canvas or placement later.

It takes the same arguments as target.hook(...) and returns an operation: pipe it onto a target with target | operation, or pass it to update. Each target gets its own hook. The function may return an operation, a style or an effect, which is applied to the target it runs on.

Parameters:

function (Hook[DepsT, StateT] | None, default: None ) –

The function to wrap when @xnano.hook is used without parentheses: a function of the Context, or one with no parameters.
on (HookKind | None, default: None ) –

What the hook listens to; see HookKind.
when (When[DepsT, StateT] | None, default: None ) –

A condition that must hold; see When.
every (float | None, default: None ) –

Repeat every this many seconds ('tick') or beats ('beat').
after (float | None, default: None ) –

Run once after this many seconds ('tick') or beats ('beat').
keys (KeyName | Sequence[KeyName] | None, default: None ) –

The key or keys an on='key' hook reacts to.
requires_deps (bool, default: False ) –

Whether the hook needs the dependencies given to new(deps=...).

Raises:

TypeError –

function cannot be called with a context, keys is not a key name or a list of them, or when is not a condition.
ValueError –

on, every, after, keys or when is not valid, or they do not fit together.

Examples:

import xnano

readings = []

@xnano.hook(on='frame')
def clock_readout(context: xnano.Context) -> None:
    readings.append(round(context.time.elapsed, 1))

with xnano.new(width=12, height=1) as canvas:
    canvas | clock_readout
    canvas.step(delta_seconds=0.5)
assert readings == [0.5]

Referenced by:

API Reference xnano xnano.operations operations

Source code in xnano/operations.py

def hook(
    function: Hook[DepsT, StateT] | None = None,
    /,
    *,
    on: HookKind | None = None,
    when: When[DepsT, StateT] | None = None,
    every: float | None = None,
    after: float | None = None,
    keys: KeyName | Sequence[KeyName] | None = None,
    requires_deps: bool = False,
) -> (
    ContextualOperation[DepsT, StateT]
    | Callable[
        [Hook[DepsT, StateT]],
        ContextualOperation[DepsT, StateT],
    ]
):
    """
    Describe a hook once, to attach to any canvas or placement later.

    It takes the same arguments as ``target.hook(...)`` and returns an operation: pipe it onto
    a target with ``target | operation``, or pass it to ``update``. Each target gets its own
    hook. The function may return an operation, a style or an effect, which is applied to the
    target it runs on.

    Args:
        function: The function to wrap when ``@xnano.hook`` is used without parentheses: a
            function of the [`Context`][xnano.context.Context], or one with no parameters.
        on: What the hook listens to; see [`HookKind`][xnano.types.HookKind].
        when: A condition that must hold; see [`When`][xnano.types.When].
        every: Repeat every this many seconds (``'tick'``) or beats (``'beat'``).
        after: Run once after this many seconds (``'tick'``) or beats (``'beat'``).
        keys: The key or keys an ``on='key'`` hook reacts to.
        requires_deps: Whether the hook needs the dependencies given to ``new(deps=...)``.

    Raises:
        TypeError: ``function`` cannot be called with a context, ``keys`` is not a key name
            or a list of them, or ``when`` is not a condition.
        ValueError: ``on``, ``every``, ``after``, ``keys`` or ``when`` is not valid, or they
            do not fit together.

    Examples:
        ```python
        import xnano

        readings = []

        @xnano.hook(on='frame')
        def clock_readout(context: xnano.Context) -> None:
            readings.append(round(context.time.elapsed, 1))

        with xnano.new(width=12, height=1) as canvas:
            canvas | clock_readout
            canvas.step(delta_seconds=0.5)
        assert readings == [0.5]
        ```
    """
    from xnano._when import compile_when

    _check_hook_arguments(
        cast('_Hooked[object, object]', object()), on, every, after, keys
    )
    compile_when(when)
    normalized_keys: tuple[str, ...] = (
        () if keys is None else (keys,) if isinstance(keys, str) else tuple(keys)
    )

    def wrap(
        callback: Hook[DepsT, StateT],
    ) -> ContextualOperation[DepsT, StateT]:
        return ContextualOperation(
            cast(
                'Callable[[Context[DepsT, StateT]], object]',
                _check_hook_function(callback),
            ),
            on=on,
            every=every,
            after=after,
            keys=normalized_keys,
            when=when,
            requires_deps=requires_deps,
        )

    if function is not None:
        return wrap(function)
    return wrap

box ¶

box(width: int, height: int, /, **appearance: Unpack[AppearanceArguments]) -> Region

Build an empty standalone rectangle of cells with a border (does not draw).

The region is a value that you write into a canvas.

Parameters:

width (int) –

The width in cells, border included.
height (int) –

The height in cells, border included.
appearance (Unpack[AppearanceArguments], default: {} ) –

The look of the box. border is 'plain' unless you pass another kind or False.

Raises:

ValueError –

A size is below 1 or above 65535.

Examples:

import xnano

frame = xnano.box(5, 3)
assert frame.render().splitlines() == ['┌───┐', '│   │', '└───┘']

Referenced by:

Source code in xnano/region.py

def box(width: int, height: int, /, **appearance: Unpack[AppearanceArguments]) -> Region:
    """
    Build an empty standalone rectangle of cells with a border (does not draw).

    The region is a value that you write into a canvas.

    Args:
        width: The width in cells, border included.
        height: The height in cells, border included.
        appearance: The look of the box. ``border`` is ``'plain'`` unless you pass another
            kind or ``False``.

    Raises:
        ValueError: A size is below 1 or above 65535.

    Examples:
        ```python
        import xnano

        frame = xnano.box(5, 3)
        assert frame.render().splitlines() == ['┌───┐', '│   │', '└───┘']
        ```
    """
    _check_cell_counts('xnano.box', width, height)
    if width < 1 or height < 1:
        raise ValueError(
            f'A box is at least 1 by 1 cells, but got {width} by {height}. Pass whole '
            f'numbers of cells, 1 or more.'
        )
    look = _standalone_look('box', '', cast('dict[str, object]', appearance), True)
    region = Region(
        _core.Buffer(width=width, height=height),
        is_standalone=True,
        look=look,
        is_text=False,
    )
    region._redraw_look()
    return region

write ¶

write(text: str, /, **appearance: Unpack[AppearanceArguments]) -> Region

Build a standalone region from text (does not draw).

The region is sized to the text and is a value that you write into a canvas. It owns its cells. Write it into a canvas with canvas.write(region), print it with render, or change its look afterwards with region.border and its siblings.

Parameters:

text (str) –

The text, line by line.
appearance (Unpack[AppearanceArguments], default: {} ) –

The look of the text: colors, text modifiers, border, title, padding and margin; see AppearanceArguments.

Raises:

TypeError –

text is not a string.

Examples:

import xnano

card = xnano.write('hello', border='rounded', padding={'horizontal': 1})
assert card.render().splitlines()[1] == '│ hello │'
card.border = False
assert card.render().strip() == 'hello'

Referenced by:

Source code in xnano/region.py

def write(text: str, /, **appearance: Unpack[AppearanceArguments]) -> Region:
    """
    Build a standalone region from text (does not draw).

    The region is sized to the text and is a value that you write into a canvas. It owns its
    cells. Write it into a canvas with ``canvas.write(region)``, print it
    with [`render`][xnano.region.Region.render], or change its look afterwards with
    ``region.border`` and its siblings.

    Args:
        text: The text, line by line.
        appearance: The look of the text: colors, text modifiers, ``border``, ``title``,
            ``padding`` and ``margin``; see [`AppearanceArguments`][xnano.types.AppearanceArguments].

    Raises:
        TypeError: ``text`` is not a string.

    Examples:
        ```python
        import xnano

        card = xnano.write('hello', border='rounded', padding={'horizontal': 1})
        assert card.render().splitlines()[1] == '│ hello │'
        card.border = False
        assert card.render().strip() == 'hello'
        ```
    """
    if not isinstance(text, str):
        raise TypeError(
            f'xnano.write() takes text, but got {text!r}. To show other content, create a '
            f'canvas with xnano.new() and call canvas.write(content).'
        )
    look = _standalone_look('write', text, cast('dict[str, object]', appearance), False)
    region = Region(
        _core.Buffer(width=1, height=1), is_standalone=True, look=look, is_text=True
    )
    region._redraw_look()
    return region

open ¶

open(canvas: Canvas[DepsT, StateT], /, *, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, **settings: Unpack[OpenSettings]) -> Terminal[DepsT, StateT]

open(content: Content | None = None, /, *, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float = 60.0, bpm: float = 120.0, effects: Sequence[RenderableEffectSpecification] = (), **settings: Unpack[CanvasSettings]) -> Terminal[None, None]

open(content: Content | None = None, /, *, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float = 60.0, bpm: float = 120.0, effects: Sequence[RenderableEffectSpecification] = (), state: StateT, **settings: Unpack[CanvasSettings]) -> Terminal[None, StateT]

open(content: Content | None = None, /, *, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float = 60.0, bpm: float = 120.0, effects: Sequence[RenderableEffectSpecification] = (), deps: DepsT, **settings: Unpack[CanvasSettings]) -> Terminal[DepsT, None]

open(content: Content | None = None, /, *, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, fps: float = 60.0, bpm: float = 120.0, effects: Sequence[RenderableEffectSpecification] = (), deps: DepsT, state: StateT, **settings: Unpack[CanvasSettings]) -> Terminal[DepsT, StateT]

open(canvas_or_content: Canvas[object, object] | Content | None = None, /, *, title: str | None = None, width: int | Percentage | str | None = None, height: int | Percentage | str | None = None, **settings: object) -> Terminal[DepsT, StateT]

Put a canvas on your screen and return it as a Terminal.

Given a canvas from new, this is Canvas.open: the same object is attached to the screen and its time continues. Given content or nothing, it creates the canvas with new() (the same keywords, except realtime) and attaches that. From here on, anything you write, remove or draw appears at once, on a loop of the canvas's own that your code never waits for. A with block closes it and gives the screen back.

By default the canvas takes over the whole window, on the alternate screen so that your shell's history comes back untouched; width='100%', height='100%' asks for the same. Give height (and optionally width) to draw in a region of that size below the cursor instead, in cells or as a percentage of the window such as '50%'; that region is erased when the canvas closes, unless you pass clear=False. title is the window title.

The input gates say what the screen reports: mouse for buttons and drags, scroll for the wheel, keyboard, paste, focus and interrupt (Ctrl-C), and capture holds back what the program prints while the canvas is on the screen. See GateSettings. mouse, scroll and paste are turned on by themselves when a hook registered before opening needs them.

Parameters:

canvas_or_content (Canvas[object, object] | Content | None, default: None ) –

A canvas from new(), or content to write into a new canvas.
title (str | None, default: None ) –

The window title; None keeps the canvas's title.
width (int | Percentage | str | None, default: None ) –

The width of the region to draw in, in cells or as a percentage of the window; the whole window when neither width nor height is given.
height (int | Percentage | str | None, default: None ) –

The height of the region to draw in, in cells or as a percentage of the window.
settings (object, default: {} ) –

The other keywords of new() except realtime: the gates, the canvas's look, fps, bpm, effects, deps and state.

Returns:

Terminal[DepsT, StateT] –

The open Terminal, which is also the one module-level functions
Terminal[DepsT, StateT] –

such as active find.

Raises:

TerminalAlreadyOpenError –

Another canvas is already on the screen.
TerminalError –

There is no terminal to draw on.
TypeError –

realtime was given, an appearance keyword was given with content, or a keyword is unknown.
ValueError –

A width was given without a height, or a value is out of range.

Examples:

with xnano.open(height=3, mouse=True) as terminal:
    terminal.write('hello')
    terminal.run(quit_on='q')

Referenced by:

Source code in xnano/terminal.py

def open(
    canvas_or_content: Canvas[object, object] | Content | None = None,
    /,
    *,
    title: str | None = None,
    width: int | Percentage | str | None = None,
    height: int | Percentage | str | None = None,
    **settings: object,
) -> Terminal[DepsT, StateT]:
    """
    Put a canvas on your screen and return it as a [`Terminal`][xnano.Terminal].

    Given a canvas from [`new`][xnano.new], this is [`Canvas.open`][xnano.canvas.Canvas.open]:
    the same object is attached to the screen and its time continues. Given content or
    nothing, it creates the canvas with ``new()`` (the same keywords, except ``realtime``)
    and attaches that. From here on, anything you write, remove or draw appears at once, on a
    loop of the canvas's own that your code never waits for. A ``with`` block closes it and
    gives the screen back.

    By default the canvas takes over the whole window, on the alternate screen so that your
    shell's history comes back untouched; ``width='100%', height='100%'`` asks for the same.
    Give ``height`` (and optionally ``width``) to draw in a region of that size below the cursor
    instead, in cells or as a percentage of the window such as ``'50%'``; that region is erased
    when the canvas closes, unless you pass ``clear=False``. ``title`` is the window title.

    The input gates say what the screen reports: ``mouse`` for buttons and drags, ``scroll``
    for the wheel, ``keyboard``, ``paste``, ``focus`` and ``interrupt`` (``Ctrl-C``), and
    ``capture`` holds back what the program prints while the canvas is on the screen. See
    [`GateSettings`][xnano.types.GateSettings]. ``mouse``, ``scroll`` and ``paste`` are turned
    on by themselves when a hook registered before opening needs them.

    Args:
        canvas_or_content: A canvas from ``new()``, or content to write into a new canvas.
        title: The window title; ``None`` keeps the canvas's title.
        width: The width of the region to draw in, in cells or as a percentage of the
            window; the whole window when neither ``width`` nor ``height`` is given.
        height: The height of the region to draw in, in cells or as a percentage of the
            window.
        settings: The other keywords of ``new()`` except ``realtime``: the gates, the
            canvas's look, ``fps``, ``bpm``, ``effects``, ``deps`` and ``state``.

    Returns:
        The open [`Terminal`][xnano.Terminal], which is also the one module-level functions
        such as [`active`][xnano.active] find.

    Raises:
        TerminalAlreadyOpenError: Another canvas is already on the screen.
        TerminalError: There is no terminal to draw on.
        TypeError: ``realtime`` was given, an appearance keyword was given with content, or a
            keyword is unknown.
        ValueError: A ``width`` was given without a ``height``, or a value is out of range.

    Examples:
        ```text
        with xnano.open(height=3, mouse=True) as terminal:
            terminal.write('hello')
            terminal.run(quit_on='q')
        ```
    """
    if isinstance(canvas_or_content, Canvas):
        return cast('Canvas[DepsT, StateT]', canvas_or_content).open(
            title=title,
            width=width,
            height=height,
            **settings,  # type: ignore[arg-type]
        )
    if 'realtime' in settings:
        raise TypeError(
            'open() takes no realtime: a canvas on the screen always runs on the wall clock. '
            'Remove realtime=..., or keep the canvas off the screen with '
            'xnano.new(realtime=True).'
        )
    if height is None and not _is_whole_window(_check_size('width', width)):
        raise ValueError(
            'A canvas on the screen with a width needs a height too, because it draws in a '
            "region of that size. Add height=... (cells, or a percentage such as '50%'), or "
            'remove width.'
        )
    # Checked here as well as in new(), so that an error names open().
    own = {'fps', 'bpm', 'effects', 'deps', 'state', 'layout', 'edges'}
    _, appearance = _split_settings(
        'open', {name: value for name, value in settings.items() if name not in own}
    )
    if canvas_or_content is not None and appearance:
        raise _appearance_with_content_error('open', appearance)
    canvas: Canvas[DepsT, StateT] = _create(
        canvas_or_content,  # type: ignore[arg-type]
        title=title,
        width=width,
        height=height,
        **settings,  # type: ignore[arg-type]
    )
    try:
        return canvas.open()
    except BaseException:
        canvas.close(raise_failure=False)
        raise

xnano

xnano ¶

Audio dataclass ¶

Image dataclass ¶

Canvas ¶

color property ¶

border property writable ¶

padding property writable ¶

margin property writable ¶

is_bold property writable ¶

is_dim property writable ¶

is_italic property writable ¶

is_underlined property writable ¶

is_blinking property writable ¶

is_reversed property writable ¶

is_hidden property writable ¶

is_crossed_out property writable ¶

output instance-attribute ¶

is_closed property ¶

is_running property ¶

core_buffer property ¶

parent property ¶

root property ¶

size property ¶

width property ¶

height property ¶

x property ¶

y property ¶

fps property ¶

bpm property writable ¶

deps property ¶

title property writable ¶

time property ¶

cursor property ¶

region property ¶

layout property ¶

edges property writable ¶

audio property ¶

fx property ¶

input property ¶

state class-attribute instance-attribute ¶

__setattr__ ¶

bold ¶

dim ¶

italic ¶

underline ¶

blink ¶

reverse ¶

hidden ¶

crossed_out ¶

hook ¶

__new__ ¶

open ¶

close ¶

local ¶

move ¶

up ¶

down ¶

left ¶

right ¶

new ¶

write ¶

clear ¶

update ¶

__or__ ¶

__ior__ ¶

inspect ¶

iter ¶

step ¶

deliver_events ¶

stop ¶

resume ¶

quit ¶

run ¶

wait_for_key ¶

prompt ¶

render ¶

push ¶

play ¶

state_reference ¶

Audio `dataclass` ¶

Image `dataclass` ¶

color `property` ¶

border `property` `writable` ¶

padding `property` `writable` ¶

margin `property` `writable` ¶

is_bold `property` `writable` ¶

is_dim `property` `writable` ¶

is_italic `property` `writable` ¶

is_underlined `property` `writable` ¶

is_blinking `property` `writable` ¶

is_reversed `property` `writable` ¶

is_hidden `property` `writable` ¶

is_crossed_out `property` `writable` ¶

output `instance-attribute` ¶

is_closed `property` ¶

is_running `property` ¶

core_buffer `property` ¶

parent `property` ¶

root `property` ¶

size `property` ¶

width `property` ¶

height `property` ¶

x `property` ¶

y `property` ¶

fps `property` ¶

bpm `property` `writable` ¶

deps `property` ¶

title `property` `writable` ¶

time `property` ¶

cursor `property` ¶

region `property` ¶

layout `property` ¶

edges `property` `writable` ¶

audio `property` ¶

fx `property` ¶

input `property` ¶

state `class-attribute` `instance-attribute` ¶

setattr ¶

new ¶

or ¶

ior ¶

canvas `instance-attribute` ¶

hook `instance-attribute` ¶

event `property` ¶

keyboard `property` ¶

mouse `property` ¶

scroll `property` ¶

clipboard `property` ¶

buffer `property` ¶

parent `property` ¶

root `property` ¶

plugin `property` ¶

deps `property` ¶

fx `property` ¶

time `property` ¶

audio `property` ¶

cursor `property` ¶

size `property` ¶

input `property` ¶

Note `dataclass` ¶

pitch `instance-attribute` ¶

beats `class-attribute` `instance-attribute` ¶

instrument `class-attribute` `instance-attribute` ¶

velocity `class-attribute` `instance-attribute` ¶

effects `class-attribute` `instance-attribute` ¶

symbol `class-attribute` `instance-attribute` ¶

Pixel `dataclass` ¶

character `instance-attribute` ¶

foreground `instance-attribute` ¶

background `instance-attribute` ¶

symbol `instance-attribute` ¶

str ¶

region `property` ¶

color `property` ¶

border `property` `writable` ¶

padding `property` `writable` ¶

margin `property` `writable` ¶

is_bold `property` `writable` ¶

is_dim `property` `writable` ¶