xnano.appearance

One color of an owner: the text color, the background or the border color.

A slot is live: changing it changes the owner. slot.value is the plain Color, a copy that changes nothing.

Attributes:

• value (Color | None) –

  The plain color of the slot, or None when it has none.

Examples:

import xnano

with xnano.new(width=8, height=1) as canvas:
    label = canvas.write('hi', background='#336699')
    label.color.bg.darken(0.2)
    darker = label.color.bg.value
    assert darker != xnano.Color('#336699')
    assert darker.darken(0.5) != label.color.bg.value

Make the slot of an owner. Get one from owner.color instead of calling this.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

• name (str) –

  'foreground', 'background' or 'border'.

Methods:

• darken –

  Make the color darker, in place.

• lighten –

  Make the color lighter, in place.

• random –

  Set the slot to a random color, or to a random shade of base, in place.

• shade –

  Color every cell of the owner from a function of its position, in one write.

524
525
526
527
528
529
530
531
532
533

def __init__(self, owner: _Looked, name: str) -> None:
    """
    Make the slot of an owner. Get one from ``owner.color`` instead of calling this.

    Args:
        owner: The canvas, placement or region.
        name: ``'foreground'``, ``'background'`` or ``'border'``.
    """
    self._owner = owner
    self._name = name

value: Color | None

darken(amount: float) -> None

581
582
583
584
585
586
587
588
589
590
591
592
593
594
595

def darken(self, amount: float) -> None:
    """
    Make the color darker, in place.

    This changes the owner and returns nothing. To get a darker copy, use
    ``slot.value.darken(amount)``. Assigning the result of this call to another slot
    raises a ``TypeError``, but this call has already darkened the owner by then.

    Args:
        amount: How much darker, from ``0.0`` (unchanged) to ``1.0`` (black).

    Raises:
        TerminalError: The slot has no color.
    """
    self._write(self._require_value('darken').darken(amount))

lighten(amount: float) -> None

597
598
599
600
601
602
603
604
605
606
607

def lighten(self, amount: float) -> None:
    """
    Make the color lighter, in place.

    Args:
        amount: How much lighter, from ``0.0`` (unchanged) to ``1.0`` (white).

    Raises:
        TerminalError: The slot has no color.
    """
    self._write(self._require_value('lighten').lighten(amount))

random(base: ColorName | ColorValue | None = None) -> Color

import xnano

with xnano.new(width=8, height=1) as canvas:
    label = canvas.write('hi')
    chosen = label.color.fg.random('green')
    assert label.color.fg.value == chosen
    label.color.bg.random()
    assert label.color.bg.value is not None

609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639

def random(self, base: ColorName | ColorValue | None = None) -> _core.Color:
    """
    Set the slot to a random color, or to a random shade of ``base``, in place.

    This is ``slot = Color.random(base)``; see
    [`Color.random`][xnano_core.Color.random]. ``random.seed(...)`` repeats the colors.

    Args:
        base: The color to pick shades of, or ``None`` for any color.

    Returns:
        The [`Color`][xnano_core.Color] the slot was set to.

    Raises:
        ValueError: ``base`` is ``Color.reset``, or not a color.

    Examples:
        ```python
        import xnano

        with xnano.new(width=8, height=1) as canvas:
            label = canvas.write('hi')
            chosen = label.color.fg.random('green')
            assert label.color.fg.value == chosen
            label.color.bg.random()
            assert label.color.bg.value is not None
        ```
    """
    color = _core.Color.random(base)
    self._write(color)
    return color

shade(function: Callable[[int, int], ColorValue | None]) -> None

import xnano

with xnano.new(width=4, height=2) as canvas:
    canvas.color.bg.shade(lambda x, y: (x * 40, y * 40, 0))
    assert canvas.region[3, 1].background.to_rgb() == (120, 40, 0)

641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676

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

    Args:
        function: Called with ``(x, y)`` in cells; return the color, or ``None`` to leave
            the cell alone. For half-block or braille resolution use
            ``owner.region.half_blocks.shade`` or ``owner.region.braille.shade``.

    Raises:
        TerminalError: The slot is ``border.color``, which is one color for the whole
            border and cannot be shaded.

    Examples:
        ```python
        import xnano

        with xnano.new(width=4, height=2) as canvas:
            canvas.color.bg.shade(lambda x, y: (x * 40, y * 40, 0))
            assert canvas.region[3, 1].background.to_rgb() == (120, 40, 0)
        ```
    """
    if self._name == 'border':
        raise TerminalError(
            'The border has one color, so border.color cannot be shaded cell by cell. '
            'Assign a color to border.color, or shade the content with color.fg.shade '
            'or color.bg.shade.'
        )
    from xnano.region import Region

    owner = self._owner
    region = owner if isinstance(owner, Region) else owner.region
    if self._name == 'foreground':
        region._shade_foreground(function)
    else:
        region.shade(function)

The two colors of an owner: fg is the text, bg is what is behind it.

Assigning accepts a color name, a (red, green, blue) tuple, a Color or another ColorSlot; 'reset' clears the color. A value that is not a color raises at the assignment and leaves the colors unchanged.

Attributes:

• fg (ColorSlot) –

  The color of the text.

• bg (ColorSlot) –

  The color behind the text.

Make the colors of an owner. Get them from owner.color instead of calling this.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

Methods:

• shade –

  Color the background of every cell from a function of its position, in one write.

707
708
709
710
711
712
713
714

def __init__(self, owner: _Looked) -> None:
    """
    Make the colors of an owner. Get them from ``owner.color`` instead of calling this.

    Args:
        owner: The canvas, placement or region.
    """
    self._owner = owner

fg: ColorSlot

bg: ColorSlot

shade(function: Callable[[int, int], ColorValue | None]) -> None

742
743
744
745
746
747
748
749
750
751

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

    Args:
        function: Called with ``(x, y)`` in cells; return the color, or ``None`` to leave
            the cell alone. For half-block or braille resolution use
            ``owner.region.half_blocks.shade`` or ``owner.region.braille.shade``.
    """
    self.bg.shade(function)

One side of a border: top, right, bottom or left.

Attributes:

• kind (BorderKind | None) –

  The kind of line on this side, or None when the side is not drawn.

• color (Color | None) –

  The color of this side, or None when it uses the border's own color.

Make a side. Get one from owner.border.top and its siblings instead.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

• name (str) –

  'top', 'right', 'bottom' or 'left'.

768
769
770
771
772
773
774
775
776
777

def __init__(self, owner: _Looked, name: str) -> None:
    """
    Make a side. Get one from ``owner.border.top`` and its siblings instead.

    Args:
        owner: The canvas, placement or region.
        name: ``'top'``, ``'right'``, ``'bottom'`` or ``'left'``.
    """
    self._owner = owner
    self._name = name

kind: BorderKind | None

color: Color | None

The border of an owner.

Attributes:

• kind (BorderKind | None) –

  'plain', 'rounded', 'double' or 'thick'; None for no border.

• top (BorderSide) –

  The top side, a BorderSide.

• right (BorderSide) –

  The right side.

• bottom (BorderSide) –

  The bottom side.

• left (BorderSide) –

  The left side.

• color (ColorSlot) –

  The border color, a ColorSlot. A side may have its own.

• title (str | None) –

  The text written on the top edge, or None.

Make the border of an owner. Get it from owner.border instead of calling this.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

867
868
869
870
871
872
873
874

def __init__(self, owner: _Looked) -> None:
    """
    Make the border of an owner. Get it from ``owner.border`` instead of calling this.

    Args:
        owner: The canvas, placement or region.
    """
    self._owner = owner

kind: BorderKind | None

top: BorderSide

right: BorderSide

bottom: BorderSide

left: BorderSide

color: ColorSlot

title: str | None

The four edges of a padding or a margin, in cells.

Reading an edge gives the number of cells it is now. Assigning accepts a number of cells, a float or a percentage such as '10%', which is a share of the content's size when the look is drawn.

Attributes:

• top (int) –

  The space above.

• right (int) –

  The space to the right.

• bottom (int) –

  The space below.

• left (int) –

  The space to the left.

Make the edges of an owner. Get them from owner.padding or owner.margin.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

1000
1001
1002
1003
1004
1005
1006
1007

def __init__(self, owner: _Looked) -> None:
    """
    Make the edges of an owner. Get them from ``owner.padding`` or ``owner.margin``.

    Args:
        owner: The canvas, placement or region.
    """
    self._owner = owner

top: int

right: int

bottom: int

left: int

Bases: Edges

The space between the border and the content; see Edges.

Attributes:

• top (int) –

  The space above.

• right (int) –

  The space to the right.

• bottom (int) –

  The space below.

• left (int) –

  The space to the left.

Make the edges of an owner. Get them from owner.padding or owner.margin.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

1000
1001
1002
1003
1004
1005
1006
1007

def __init__(self, owner: _Looked) -> None:
    """
    Make the edges of an owner. Get them from ``owner.padding`` or ``owner.margin``.

    Args:
        owner: The canvas, placement or region.
    """
    self._owner = owner

top: int

right: int

bottom: int

left: int

Bases: Edges

The transparent space outside the border; see Edges.

Attributes:

• top (int) –

  The space above.

• right (int) –

  The space to the right.

• bottom (int) –

  The space below.

• left (int) –

  The space to the left.

Make the edges of an owner. Get them from owner.padding or owner.margin.

Parameters:

• owner (_Looked) –

  The canvas, placement or region.

1000
1001
1002
1003
1004
1005
1006
1007

def __init__(self, owner: _Looked) -> None:
    """
    Make the edges of an owner. Get them from ``owner.padding`` or ``owner.margin``.

    Args:
        owner: The canvas, placement or region.
    """
    self._owner = owner

top: int

right: int

bottom: int

left: int