xnano.terminal

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

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

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)

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

359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384

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 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.

386
387
388
389
390
391
392
393
394
395
396
397
398
399
400

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

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.

402
403
404
405
406
407
408
409
410
411
412
413
414
415
416

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 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.

418
419
420
421
422
423
424
425
426
427
428
429
430
431
432

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

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.

434
435
436
437
438
439
440
441
442
443
444
445
446
447
448

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

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.

450
451
452
453
454
455
456
457
458
459
460
461
462
463
464

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

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.

466
467
468
469
470
471
472
473
474
475
476
477
478
479
480

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

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.

482
483
484
485
486
487
488
489
490
491
492
493
494
495
496

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

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']

 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005

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)

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

681
682
683
684
685
686
687
688

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)

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')

1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451