xnano.styles

@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')
        ```
    """

@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)
        ```
    """

@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
        ```
    """

@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)
        ```
    """

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
        ```
    """

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'
        ```
    """

@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'
        ```
    """

@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'
        ```
    """

@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
        ```
    """

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
        ```
    """

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
        ```
    """

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
        ```
    """