xnano.types

xnano.types

The types that describe what xnano accepts: positions and sizes as an axis, anything that can be added to a canvas, space around text, pixel encodings, the settings of a canvas and of the screen it is opened on, and the functions that hook into events.

Classes:

• SpacingDictionary –

  Space around text, edge by edge.

• EffectController –

  The effects of the hook that is running, one method for each effect.

• PlayableEffects –

  The sound effects of a canvas's audio, one method for each effect.

• RenderableEffects –

  The visual effects of a placement or a canvas, one method for each effect.

• HookHandle –

  One hook attached to a canvas or a placement.

• SupportsPlay –

  Anything that can be played: an object with a __xnano_play__ method.

• SupportsRender –

  Anything that draws itself: an object with a __xnano_render__ method.

• GateSettings –

  What a screen reports to a canvas: the input gates of new() and open().

• CanvasAppearanceArguments –

  How a canvas itself looks: its colors, text modifiers, border, padding and margin.

• AppearanceArguments –

  How written content looks: the appearance keywords of write.

• CanvasSettings –

  The keyword settings of new: the input gates and the canvas's own look.

• OpenSettings –

  The keyword settings of Canvas.open and of

• PlayOptions –

  The keyword options of play. An option replaces the same value on a

Attributes:

• Spacing (TypeAlias) –

  Space around text: one value for every edge or a SpacingDictionary.

• EffectCustomization –

  Any visual or sound effect, as the customization that fx(...) returns.

• PlayableEffect –

  A sound effect as fx(...) and the methods of canvas.audio.fx and context.fx return it.

• PlayableEffectKind –

  The kinds of effect that change how a sound plays: fx kinds that start with 'audio.'.

• PlayableEffectSpecification –

  One sound effect as a dictionary for effects=[...]: its kind and its keywords.

• RenderableEffect –

  A visual effect as fx(...) and the methods of placement.fx and context.fx return it.

• RenderableEffectKind –

  The kinds of effect that change how a buffer looks: fx kinds that start with 'effect.'.

• RenderableEffectSpecification –

  One visual effect as a dictionary for effects=[...]: its kind and its keywords.

• Hook (TypeAlias) –

  What a canvas or placement calls when an event counts: a function of the

• HookGenerator (TypeAlias) –

  A hook that spans several events: it receives the next context at each bare yield.

• HookKind (TypeAlias) –

  When a hook runs.

• When (TypeAlias) –

  The condition of a hook: an expression, a function of the context, or a string.

• Anchor (TypeAlias) –

  The (x, y) pixel inside an Art that sits at the art's (x, y).

• Axis (TypeAlias) –

  One number of a position or size: x, y, width or height.

• CanvasLayout (TypeAlias) –

  How a canvas places what is written on it.

• ColorValue (TypeAlias) –

  A color, an ANSI color name, a '#rrggbb' string, or a (red, green, blue) tuple.

• Content (TypeAlias) –

  Anything a canvas can show or play: a Renderable or a Playable.

• EdgeBehavior (TypeAlias) –

  What content does at the edges of its area.

• HeldMouseButtonName (TypeAlias) –

  The name of a mouse button in the held-input vocabulary of Input.

• HorizontalPosition (TypeAlias) –

  A word that places something inside its parent along x.

• Interpolation (TypeAlias) –

  How an effect eases between its start and end: 'linear', or a curve such as

• KeyName (TypeAlias) –

  The name of a key such as 'q', 'enter' or 'page_up'.

• MotionDirection (TypeAlias) –

  The direction a sweep, slide or stretch effect moves in.

• Percentage (TypeAlias) –

  A share of the space a size or position is measured against, such as '50%'.

• PixelEncoding (TypeAlias) –

  'half_blocks': one column and two rows of pixels per cell. 'braille': two by four.

• Playable (TypeAlias) –

  Anything play and Canvas.play accept: a

• PlaySource (TypeAlias) –

  Anything play and Canvas.play accept: a

• RangeBound (TypeAlias) –

  One end of a range as written: cells, a percentage string, an expression, or None.

• Renderable (TypeAlias) –

  Anything Canvas.write accepts: text, a

• VerticalPosition (TypeAlias) –

  A word that places something inside its parent along y.

• PixelPreset (TypeAlias) –

  The names of the characters Pixel knows: Pixel('diamond') draws ◆.

• BorderKind (TypeAlias) –

  The line style of a border.

Spacing: TypeAlias = int | float | Percentage | str | SpacingDictionary

EffectCustomization = RenderableEffect | PlayableEffect

PlayableEffect = BitCrushAudioCustomization | DistortionAudioCustomization | LowPassAudioCustomization | HighPassAudioCustomization | DelayAudioCustomization | ReverbAudioCustomization | TremoloAudioCustomization

PlayableEffectKind = Literal['audio.bit_crush', 'audio.distortion', 'audio.low_pass', 'audio.high_pass', 'audio.delay', 'audio.reverb', 'audio.tremolo']

PlayableEffectSpecification = BitCrushAudioSpecification | DistortionAudioSpecification | LowPassAudioSpecification | HighPassAudioSpecification | DelayAudioSpecification | ReverbAudioSpecification | TremoloAudioSpecification

RenderableEffect = FadeToEffectCustomization | FadeFromEffectCustomization | PaintEffectCustomization | SaturateEffectCustomization | LightenEffectCustomization | DarkenEffectCustomization | SweepInEffectCustomization | SweepOutEffectCustomization | SlideInEffectCustomization | SlideOutEffectCustomization | HslShiftEffectCustomization | DissolveEffectCustomization | CoalesceEffectCustomization | GlitchEffectCustomization | SleepEffectCustomization | EvolveEffectCustomization | EvolveIntoEffectCustomization | EvolveFromEffectCustomization | ExpandEffectCustomization | StretchEffectCustomization | ExplodeEffectCustomization

RenderableEffectKind = Literal['effect.fade_to', 'effect.fade_from', 'effect.paint', 'effect.saturate', 'effect.lighten', 'effect.darken', 'effect.sweep_in', 'effect.sweep_out', 'effect.slide_in', 'effect.slide_out', 'effect.hsl_shift', 'effect.dissolve', 'effect.coalesce', 'effect.glitch', 'effect.sleep', 'effect.evolve', 'effect.evolve_into', 'effect.evolve_from', 'effect.expand', 'effect.stretch', 'effect.explode']

RenderableEffectSpecification = FadeToEffectSpecification | FadeFromEffectSpecification | PaintEffectSpecification | SaturateEffectSpecification | LightenEffectSpecification | DarkenEffectSpecification | SweepInEffectSpecification | SweepOutEffectSpecification | SlideInEffectSpecification | SlideOutEffectSpecification | HslShiftEffectSpecification | DissolveEffectSpecification | CoalesceEffectSpecification | GlitchEffectSpecification | SleepEffectSpecification | EvolveEffectSpecification | EvolveIntoEffectSpecification | EvolveFromEffectSpecification | ExpandEffectSpecification | StretchEffectSpecification | ExplodeEffectSpecification

Hook: TypeAlias = Callable[[Context[DepsT, StateT]], 'object | HookGenerator[DepsT, StateT]'] | Callable[[], 'object | HookGenerator[DepsT, StateT]']

HookGenerator: TypeAlias = Generator[None, Context[DepsT, StateT], None]

HookKind: TypeAlias = Literal['frame', 'tick', 'beat', 'key', 'mouse', 'scroll', 'drag', 'paste', 'focus', 'resize', 'state', 'custom']

When: TypeAlias = 'str | Callable[[Context[DepsT, StateT]], bool] | _core.Expression[bool]'

Anchor: TypeAlias = tuple[int, int]

Axis: TypeAlias = int | float | Percentage | HorizontalPosition | VerticalPosition | str | tuple[RangeBound, RangeBound] | NumericExpression

CanvasLayout: TypeAlias = Literal['overlay', 'column', 'row']

ColorValue: TypeAlias = 'Color | ColorName | str | tuple[int, int, int]'

Content: TypeAlias = 'Renderable | Playable'

EdgeBehavior: TypeAlias = Literal['clip', 'stop', 'wrap']

HeldMouseButtonName: TypeAlias = Literal['mouse_left', 'mouse_right', 'mouse_middle']

HorizontalPosition: TypeAlias = Literal['left', 'center', 'right']

Interpolation: TypeAlias = Literal['linear', 'back_in', 'back_out', 'back_in_out', 'bounce_in', 'bounce_out', 'bounce_in_out', 'circ_in', 'circ_out', 'circ_in_out', 'cubic_in', 'cubic_out', 'cubic_in_out', 'elastic_in', 'elastic_out', 'elastic_in_out', 'expo_in', 'expo_out', 'expo_in_out', 'quad_in', 'quad_out', 'quad_in_out', 'quart_in', 'quart_out', 'quart_in_out', 'quint_in', 'quint_out', 'quint_in_out', 'sine_in', 'sine_out', 'sine_in_out', 'smooth_step', 'spring', 'reverse', 'ease_in']

KeyName: TypeAlias = Literal['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'space', 'enter', 'escape', 'tab', 'backspace', 'delete', 'insert', 'home', 'end', 'page_up', 'page_down', 'up', 'down', 'left', 'right', 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'f11', 'f12'] | str

MotionDirection: TypeAlias = Literal['left_to_right', 'right_to_left', 'up_to_down', 'down_to_up']

Percentage: TypeAlias = Literal['5%', '10%', '15%', '20%', '25%', '30%', '35%', '40%', '45%', '50%', '55%', '60%', '65%', '70%', '75%', '80%', '85%', '90%', '95%', '100%']

PixelEncoding: TypeAlias = Literal['half_blocks', 'braille']

Playable: TypeAlias = 'str | Note | Audio | SupportsPlay | Sequence[Playable]'

PlaySource: TypeAlias = 'Playable | int | float | TerminalSound | TerminalNote | TerminalMelody'

RangeBound: TypeAlias = Number | Percentage | str | NumericExpression | None

Renderable: TypeAlias = 'str | Region | Art | Pixel | Image | Buffer | SupportsRender | Sequence[Renderable]'

VerticalPosition: TypeAlias = Literal['top', 'center', 'bottom']

PixelPreset: TypeAlias = Literal['block', 'half_top', 'half_bottom', 'shade_light', 'shade_medium', 'shade_dark', 'braille', 'circle', 'circle_outline', 'dot', 'diamond', 'star', 'line_horizontal', 'line_vertical', 'corner_top_left_rounded', 'corner_top_right_rounded', 'corner_bottom_left_rounded', 'corner_bottom_right_rounded', 'corner_top_left_square', 'corner_top_right_square', 'corner_bottom_left_square', 'corner_bottom_right_square', 'arrow_up', 'arrow_down', 'arrow_left', 'arrow_right', 'check', 'cross']

BorderKind: TypeAlias = Literal['plain', 'rounded', 'double', 'thick']

EffectController(context: Context[object, object])

import xnano

with xnano.new(width=8, height=1) as canvas:
    label = canvas.write('hi')
    counts = []

    @label.hook(on='frame')
    def tint(context: xnano.Context) -> None:
        if not context.fx.active:
            context.fx.fade_to(foreground='red', duration_milliseconds=100)
        counts.append(len(context.fx.active))

    canvas.step(delta_seconds=0.05)
    assert counts and set(counts) == {1}

891
892
893
894
895
896
897
898

def __init__(self, context: Context[object, object]) -> None:
    """
    Create the controller of a context. Use ``context.fx`` instead of calling this.

    Args:
        context: The context of the hook that applies the effects.
    """
    self._context = context

context: Context[object, object]

active: tuple[EffectCustomization, ...]

bit_crush(**parameters: Unpack[BitCrushAudioArguments]) -> BitCrushAudioCustomization

607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622

def bit_crush(
    self, **parameters: Unpack[BitCrushAudioArguments]
) -> BitCrushAudioCustomization:
    """
    Lower the resolution of the sound, for a gritty, retro tone.

    Keyword Args:
        bits (int): Quantization resolution in bits (``1`` to ``16``).
        downsample (int): Sample-hold factor (``1`` to ``256``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast(
        'BitCrushAudioCustomization', self._start('audio.bit_crush', parameters)
    )

distortion(**parameters: Unpack[DistortionAudioArguments]) -> DistortionAudioCustomization

624
625
626
627
628
629
630
631
632
633
634
635
636
637
638

def distortion(
    self, **parameters: Unpack[DistortionAudioArguments]
) -> DistortionAudioCustomization:
    """
    Distort the sound by driving it into soft clipping.

    Keyword Args:
        drive (float): Input gain before soft-clipping (``0.1`` to ``100.0``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast(
        'DistortionAudioCustomization', self._start('audio.distortion', parameters)
    )

low_pass(**parameters: Unpack[LowPassAudioArguments]) -> LowPassAudioCustomization

640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655

def low_pass(
    self, **parameters: Unpack[LowPassAudioArguments]
) -> LowPassAudioCustomization:
    """
    Keep the frequencies below ``cutoff`` and soften those above it.

    Keyword Args:
        cutoff (float): Corner frequency in hertz (``20.0`` to ``20000.0``).
        resonance (float): Filter resonance Q (``0.1`` to ``20.0``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast(
        'LowPassAudioCustomization', self._start('audio.low_pass', parameters)
    )

high_pass(**parameters: Unpack[HighPassAudioArguments]) -> HighPassAudioCustomization

657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672

def high_pass(
    self, **parameters: Unpack[HighPassAudioArguments]
) -> HighPassAudioCustomization:
    """
    Keep the frequencies above ``cutoff`` and soften those below it.

    Keyword Args:
        cutoff (float): Corner frequency in hertz (``20.0`` to ``20000.0``).
        resonance (float): Filter resonance Q (``0.1`` to ``20.0``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast(
        'HighPassAudioCustomization', self._start('audio.high_pass', parameters)
    )

delay(**parameters: Unpack[DelayAudioArguments]) -> DelayAudioCustomization

674
675
676
677
678
679
680
681
682
683
684
685
686

def delay(self, **parameters: Unpack[DelayAudioArguments]) -> DelayAudioCustomization:
    """
    Repeat the sound as fading echoes.

    Keyword Args:
        time_milliseconds (float): Delay time between echoes in milliseconds (``1.0`` to ``2000.0``).
        feedback (float): Echo feedback ratio (``0.0`` to ``0.95``).
        mix (float): Wet/dry mix ratio (``0.0`` to ``1.0``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast('DelayAudioCustomization', self._start('audio.delay', parameters))

reverb(**parameters: Unpack[ReverbAudioArguments]) -> ReverbAudioCustomization

688
689
690
691
692
693
694
695
696
697
698
699
700
701
702

def reverb(
    self, **parameters: Unpack[ReverbAudioArguments]
) -> ReverbAudioCustomization:
    """
    Add the reverberation of a room.

    Keyword Args:
        room (float): Room size (``0.0`` to ``1.0``).
        damping (float): High-frequency damping (``0.0`` to ``1.0``).
        mix (float): Wet/dry mix ratio (``0.0`` to ``1.0``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast('ReverbAudioCustomization', self._start('audio.reverb', parameters))

tremolo(**parameters: Unpack[TremoloAudioArguments]) -> TremoloAudioCustomization

704
705
706
707
708
709
710
711
712
713
714
715
716
717

def tremolo(
    self, **parameters: Unpack[TremoloAudioArguments]
) -> TremoloAudioCustomization:
    """
    Pulse the volume up and down.

    Keyword Args:
        rate_hertz (float): Modulation rate in hertz (``0.1`` to ``40.0``).
        depth (float): Modulation depth (``0.0`` to ``1.0``).

    Returns:
        The effect. Assigning one of its fields changes the sounds played after that.
    """
    return cast('TremoloAudioCustomization', self._start('audio.tremolo', parameters))

fade_to(**parameters: Unpack[FadeToEffectArguments]) -> FadeToEffectCustomization

165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184