plotille 6.0.0__py3-none-any.whl

plotille/_colors.py

@@ -0,0 +1,379 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+import colorsys
+import os
+import sys
+from collections.abc import Sequence
+from typing import Final, Literal, Union
+
+MAX_RGB: Final = 255
+MAX_HUE: Final = 360
+RGB_VALUES: Final = 3
+
+RGB_t = tuple[int, int, int] | Sequence[int]
+ColorDefinition = Union[str, int, "ColorNames", RGB_t, None]
+ColorMode = Literal["names", "byte", "rgb"]
+
+
+ColorNames = Literal[
+    "black",
+    "red",
+    "green",
+    "yellow",
+    "blue",
+    "magenta",
+    "cyan",
+    "white",
+    "bright_black",
+    "bright_red",
+    "bright_green",
+    "bright_yellow",
+    "bright_blue",
+    "bright_magenta",
+    "bright_cyan",
+    "bright_white",
+    "bright_black_old",
+    "bright_red_old",
+    "bright_green_old",
+    "bright_yellow_old",
+    "bright_blue_old",
+    "bright_magenta_old",
+    "bright_cyan_old",
+    "bright_white_old",
+]
+
+
+def color(
+    text: str,
+    fg: ColorDefinition = None,
+    bg: ColorDefinition = None,
+    mode: ColorMode = "names",
+    no_color: bool = False,
+    full_reset: bool = True,
+) -> str:
+    """Surround `text` with control characters for coloring
+
+    c.f. http://en.wikipedia.org/wiki/ANSI_escape_code
+
+    There are 3 color modes possible:
+        - `names`:  corresponds to 3/4 bit encoding; provide colors as lower case
+                    with underscore names, e.g. 'red', 'bright_green'
+        - `byte`: corresponds to 8-bit encoding; provide colors as int ∈ [0, 255];
+                  compare 256-color lookup table
+        - `rgb`: corresponds to 24-bit encoding; provide colors either in 3- or
+                 6-character hex encoding or provide as a list / tuple with three ints
+                 (∈ [0, 255] each)
+
+    With `fg` you can specify the foreground, i.e. text color, and with `bg` you
+    specify the background color. The resulting `text` also gets the `RESET` signal
+    at the end, s.t. no coloring swaps over to following text!
+
+    Make sure to set the colors corresponding to the `mode`, otherwise you get
+    `ValueErrors`.
+
+    If you do not want a foreground or background color, leave the corresponding
+    parameter `None`. If both are `None`, you get `text` directly.
+
+    When you stick to mode `names` and only use the none `bright_` versions,
+    the color control characters conform to ISO 6429 and the ANSI Escape sequences
+    as defined in http://ascii-table.com/ansi-escape-sequences.php.
+
+    Color names for mode `names` are:
+        black red green yellow blue magenta cyan white     <- ISO 6429
+        bright_black bright_red bright_green bright_yellow
+        bright_blue bright_magenta bright_cyan bright_white
+    (trying other names will raise ValueError)
+
+    If you want to use colorama (https://pypi.python.org/pypi/colorama), you should
+    also stick to the ISO 6429 colors.
+
+    The environment variables `NO_COLOR` (https://no-color.org/) and `FORCE_COLOR`
+    (only toggle; see https://nodejs.org/api/tty.html#tty_writestream_getcolordepth_env)
+    have some influence on color output.
+
+    If you do not run in a TTY, e.g. pipe to some other program or redirect output
+    into a file, color codes are stripped as well.
+
+    Parameters:
+        text: str        Some text to surround.
+        fg: multiple     Specify the foreground / text color.
+        bg: multiple     Specify the background color.
+        color_mode: str  Specify color input mode; 'names' (default), 'byte' or 'rgb'
+        no_color: bool   Remove color optionally. default=False
+        full_reset: bool Reset all codes or only color codes. default=True
+
+    Returns:
+        str: `text` enclosed with corresponding coloring controls
+    """
+    if fg is None and bg is None:
+        return text
+
+    if no_color or os.environ.get("NO_COLOR"):
+        #  https://no-color.org/
+        return text
+
+    # similar to https://nodejs.org/api/tty.html#tty_writestream_getcolordepth_env
+    # except for only on or of
+    force_color = os.environ.get("FORCE_COLOR")
+    if force_color:
+        force_color = force_color.strip().lower()
+        if force_color in ("0", "false", "none"):
+            return text
+
+    if not force_color and not _isatty():
+        # only color if tty (not a redirect / pipe)
+        return text
+
+    start = ""
+    if mode == "names":
+        assert fg is None or isinstance(fg, str)
+        assert bg is None or isinstance(bg, str)
+        start = _names(fg, bg)
+    elif mode == "byte":
+        assert fg is None or isinstance(fg, int)
+        assert bg is None or isinstance(bg, int)
+        start = _byte(fg, bg)
+    elif mode == "rgb":
+        if isinstance(fg, str):
+            fg = _hex2rgb(fg)
+        if isinstance(bg, str):
+            bg = _hex2rgb(bg)
+
+        assert fg is None or isinstance(fg, (list, tuple))
+        assert bg is None or isinstance(bg, (list, tuple))
+        start = _rgb(fg, bg)
+    else:
+        raise ValueError(f'Invalid mode "{mode}". Use one of "names", "byte" or "rgb".')
+
+    assert start
+    res = start + text
+    if full_reset:
+        return res + "\x1b[0m"
+    else:
+        return res + "\x1b[39;49m"
+
+
+def hsl(hue: float, saturation: float, lightness: float) -> tuple[int, int, int]:
+    """Convert HSL color space into RGB color space.
+
+    In contrast to colorsys.hls_to_rgb, this works directly in
+    360 deg Hue and give RGB values in the range of 0 to 255.
+
+    Parameters:
+        hue: float         Position in the spectrum. 0 to 360.
+        saturation: float  Color saturation. 0 to 1.
+        lightness: float   Color lightness. 0 to 1.
+    """
+    assert 0 <= hue <= MAX_HUE
+    assert 0 <= saturation <= 1
+    assert 0 <= lightness <= 1
+
+    r, g, b = colorsys.hls_to_rgb(hue / 360.0, lightness, saturation)
+    return round(r * 255), round(g * 255), round(b * 255)
+
+
+def rgb2byte(r: int, g: int, b: int) -> int:
+    """Convert RGB values into an index for the byte color-mode.
+
+    Parameters:
+        r: int    Red value. Between 0 and 255.
+        g: int    Green value. Between 0 and 255.
+        b: int    Blue value. Between 0 and 255.
+
+    Returns
+        idx: int  Index of approximate color in the byte color-mode.
+    """
+    assert 0 <= r <= MAX_RGB
+    assert 0 <= g <= MAX_RGB
+    assert 0 <= b <= MAX_RGB
+
+    if r == g == b < 244:
+        # gray:
+        gray_idx = _value_to_index(min(238, r), off=8, steps=10)
+        return gray_idx + 232
+
+    # here we also have some gray values ...
+    r_idx = _value_to_index(r)
+    g_idx = _value_to_index(g)
+    b_idx = _value_to_index(b)
+
+    return 16 + 36 * r_idx + 6 * g_idx + b_idx
+
+
+def _value_to_index(v: int, off: int = 55, steps: int = 40) -> int:
+    idx = (v - off) / steps
+    if idx < 0:
+        return 0
+    return round(idx)
+
+
+def _isatty() -> bool:
+    return sys.stdout.isatty()
+
+
+def _names(fg: str | None, bg: str | None) -> str:
+    """3/4 bit encoding part
+
+    c.f. https://en.wikipedia.org/wiki/ANSI_escape_code#3.2F4_bit
+
+    Parameters:
+
+    """
+    if not (fg is None or fg in _FOREGROUNDS):
+        raise ValueError(f'Invalid color name fg = "{fg}"')
+    if not (bg is None or bg in _BACKGROUNDS):
+        raise ValueError(f'Invalid color name bg = "{bg}"')
+
+    fg_ = _FOREGROUNDS.get(fg, "")
+    bg_ = _BACKGROUNDS.get(bg, "")
+
+    return _join_codes(fg_, bg_)
+
+
+def _byte(fg: int | None, bg: int | None) -> str:
+    """8-bite encoding part
+
+    c.f. https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
+    """
+    if not (fg is None or (isinstance(fg, int) and 0 <= fg <= MAX_RGB)):
+        raise ValueError(f"Invalid fg = {fg}. Allowed int in [0, 255].")
+    if not (bg is None or (isinstance(bg, int) and 0 <= bg <= MAX_RGB)):
+        raise ValueError(f"Invalid bg = {bg}. Allowed int in [0, 255].")
+
+    fg_ = ""
+    if fg is not None:
+        fg_ = "38;5;" + str(fg)
+    bg_ = ""
+    if bg is not None:
+        bg_ = "48;5;" + str(bg)
+
+    return _join_codes(fg_, bg_)
+
+
+def _hex2rgb(h: str) -> tuple[int, int, int]:
+    """Transform rgb hex representation into rgb tuple of ints representation"""
+    assert isinstance(h, str)
+    if h.lower().startswith("0x"):
+        h = h[2:]
+    if len(h) == 3:
+        return (int(h[0] * 2, base=16), int(h[1] * 2, base=16), int(h[2] * 2, base=16))
+    if len(h) == 6:
+        return (int(h[0:2], base=16), int(h[2:4], base=16), int(h[4:6], base=16))
+
+    raise ValueError("Invalid hex RGB value.")
+
+
+def _rgb(fg: Sequence[int] | None, bg: Sequence[int] | None) -> str:
+    """24-bit encoding part
+
+    c.f. https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit
+    """
+    if not (
+        fg is None
+        or (
+            (isinstance(fg, (list, tuple)) and len(fg) == RGB_VALUES)
+            and all(0 <= f <= MAX_RGB for f in fg)
+        )
+    ):
+        raise ValueError(f"Foreground fg either None or 3-tuple: {fg}")
+    if not (
+        bg is None
+        or (
+            (isinstance(bg, (list, tuple)) and len(bg) == RGB_VALUES)
+            and all(0 <= b <= MAX_RGB for b in bg)
+        )
+    ):
+        raise ValueError(f"Foreground fg either None or 3-tuple: {bg}")
+
+    fg_ = ""
+    if fg is not None:
+        fg_ = "38;2;" + ";".join(map(str, fg))
+    bg_ = ""
+    if bg is not None:
+        bg_ = "48;2;" + ";".join(map(str, bg))
+
+    return _join_codes(fg_, bg_)
+
+
+def _join_codes(fg: str, bg: str) -> str:
+    """Join `fg` and `bg` with ; and surround with correct esc sequence."""
+    colors = ";".join(filter(lambda c: len(c) > 0, (fg, bg)))
+    if colors:
+        return "\x1b[" + colors + "m"
+
+    return ""
+
+
+_BACKGROUNDS: dict[str | None, str] = {
+    "black": "40",
+    "red": "41",
+    "green": "42",
+    "yellow": "43",
+    "blue": "44",
+    "magenta": "45",
+    "cyan": "46",
+    "white": "47",
+    "bright_black": "100",
+    "bright_red": "101",
+    "bright_green": "102",
+    "bright_yellow": "103",
+    "bright_blue": "104",
+    "bright_magenta": "105",
+    "bright_cyan": "106",
+    "bright_white": "107",
+    "bright_black_old": "1;40",
+    "bright_red_old": "1;41",
+    "bright_green_old": "1;42",
+    "bright_yellow_old": "1;43",
+    "bright_blue_old": "1;44",
+    "bright_magenta_old": "1;45",
+    "bright_cyan_old": "1;46",
+    "bright_white_old": "1;47",
+}
+
+_FOREGROUNDS: dict[str | None, str] = {
+    "black": "30",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "blue": "34",
+    "magenta": "35",
+    "cyan": "36",
+    "white": "37",
+    "bright_black": "90",
+    "bright_red": "91",
+    "bright_green": "92",
+    "bright_yellow": "93",
+    "bright_blue": "94",
+    "bright_magenta": "95",
+    "bright_cyan": "96",
+    "bright_white": "97",
+    "bright_black_old": "1;30",
+    "bright_red_old": "1;31",
+    "bright_green_old": "1;32",
+    "bright_yellow_old": "1;33",
+    "bright_blue_old": "1;34",
+    "bright_magenta_old": "1;35",
+    "bright_cyan_old": "1;36",
+    "bright_white_old": "1;37",
+}

plotille/_data_metadata.py

@@ -0,0 +1,103 @@
+"""Metadata tracking for data type conversions.
+
+When we normalize datetime values to float (timestamps), we need to remember
+that they were originally datetimes so we can format them correctly later.
+"""
+
+from collections.abc import Sequence
+from datetime import datetime, tzinfo
+from typing import Any, final
+
+from ._util import DataValue
+
+
+@final
+class DataMetadata:
+    """Tracks whether data was originally datetime and timezone info.
+
+    Attributes:
+        is_datetime: True if the original data was datetime-like
+        timezone: The timezone if datetime was timezone-aware, else None
+    """
+
+    def __init__(self, is_datetime: bool, timezone: tzinfo | None = None) -> None:
+        self.is_datetime = is_datetime
+        self.timezone = timezone
+
+    @classmethod
+    def from_value(cls, value: Any) -> "DataMetadata":
+        """Create metadata from a single value.
+
+        Args:
+            value: Any value (datetime, numeric, etc.)
+
+        Returns:
+            DataMetadata instance
+        """
+        if isinstance(value, datetime):
+            return cls(is_datetime=True, timezone=value.tzinfo)
+        # For numeric types, numpy datetime64, etc.
+        # Check if it has a dtype attribute (numpy)
+        if hasattr(value, "dtype") and "datetime" in str(value.dtype):
+            # numpy datetime64 - these don't have timezone in the same way
+            return cls(is_datetime=True, timezone=None)
+        return cls(is_datetime=False, timezone=None)
+
+    @classmethod
+    def from_sequence(cls, sequence: Sequence[Any]) -> "DataMetadata":
+        """Create metadata from a sequence of values.
+
+        All values in the sequence should have the same type.
+
+        Args:
+            sequence: Sequence of values
+
+        Returns:
+            DataMetadata instance
+
+        Raises:
+            ValueError: If sequence contains mixed timezones
+        """
+        if len(sequence) == 0:
+            return cls(is_datetime=False, timezone=None)
+
+        metadatas = [cls.from_value(v) for v in sequence]
+        datetime_flags = {m.is_datetime for m in metadatas}
+
+        if len(datetime_flags) > 1:
+            raise ValueError("Cannot mix numeric and datetime values.")
+
+        if not metadatas[0].is_datetime:
+            return DataMetadata(is_datetime=False, timezone=None)
+
+        timezones = {m.timezone for m in metadatas}
+        has_naive = None in timezones
+        has_aware = len(timezones - {None}) > 0
+
+        if has_naive and has_aware:
+            raise ValueError("Cannot mix timezone-naive and timezone-aware datetime.")
+
+        # Pick first encountered timezone as default
+        display_timezone = metadatas[0].timezone
+
+        return DataMetadata(is_datetime=True, timezone=display_timezone)
+
+    def convert_for_display(
+        self, value: float, tz_override: tzinfo | None = None
+    ) -> DataValue:
+        """Convert normalized float back to original type for display.
+
+        Args:
+            value: Normalized float value (timestamp if datetime)
+            tz_override: Optional timezone override for datetime display
+
+        Returns:
+            float for numeric data, datetime for datetime data
+        """
+        if not self.is_datetime:
+            # if not datetime, we assume we have some numeric value ... no conversion there
+            return value
+
+        display_tz = tz_override or self.timezone
+
+        return datetime.fromtimestamp(value, tz=display_tz)

plotille/_dots.py

@@ -0,0 +1,202 @@
+# The MIT License
+
+# Copyright (c) 2017 - 2025 Tammo Ippen, tammo.ippen@posteo.de
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+from typing import Any
+
+from ._colors import ColorDefinition, color
+
+# I plot upside down, hence the different order
+# fmt: off
+_xy2dot = [
+    [1 << 6, 1 << 7],
+    [1 << 2, 1 << 5],
+    [1 << 1, 1 << 4],
+    [1 << 0, 1 << 3],
+]
+# fmt: on
+
+
+class Dots:
+    """A Dots object is responsible for printing requested braille dots and colors
+
+    Dot ordering: \u2800 '⠀' - \u28ff '⣿'' Coding according to ISO/TR 11548-1
+
+        Hence, each dot on or off is 8bit, i.e. 256 possibilities. With dot number
+        one being the lsb and 8 is msb:
+
+        idx:  8 7 6 5 4 3 2 1
+        bits: 0 0 0 0 0 0 0 0
+
+        Ordering of dots:
+
+        1  4
+        2  5
+        3  6
+        7  8
+    """
+
+    def __init__(
+        self,
+        marker: str | None = None,
+        fg: ColorDefinition = None,
+        bg: ColorDefinition = None,
+        **color_kwargs: Any,
+    ) -> None:
+        """Create a Dots object
+
+        Parameters:
+            dots: List[int]  With set dots to on; ∈ 1 - 8
+            marker: str      Set a marker instead of braille dots.
+            fg: str          Color of dots
+            bg: str          Color of background
+            **color_kwargs:  More arguments to the color-function.
+                             See `plotille.color()`.
+
+        Returns:
+            Dots
+        """
+        assert marker is None or len(marker) == 1
+        self._dots = 0
+        self._marker = marker
+        self.fg = fg
+        self.bg = bg
+        self._color_kwargs = color_kwargs
+        if "mode" not in self._color_kwargs:
+            self._color_kwargs["mode"] = "names"
+
+    @property
+    def color_kwargs(self) -> dict[str, Any]:
+        return self._color_kwargs
+
+    @property
+    def dots(self) -> list[int]:
+        assert self._dots.bit_length() <= 8
+        dots = []
+        x = self._dots
+        bit = 1
+        while x != 0:
+            if x & 1 == 1:
+                dots.append(bit)
+            bit += 1
+            x >>= 1
+        return sorted(dots)
+
+    @property
+    def marker(self) -> str | None:
+        return self._marker
+
+    @marker.setter
+    def marker(self, value: str | None) -> None:
+        assert value is None or isinstance(value, str)
+        assert value is None or len(value) == 1
+        self._marker = value
+
+    def __repr__(self) -> str:
+        return "Dots(dots={}, marker={}, fg={}, bg={}, color_kwargs={})".format(
+            self.dots,
+            self.marker,
+            self.fg,
+            self.bg,
+            " ".join(f"{k}: {v}" for k, v in self.color_kwargs.items()),
+        )
+
+    def __str__(self) -> str:
+        if self.marker:
+            res = self.marker
+        else:
+            res = chr(0x2800 + self._dots)
+
+        return color(res, fg=self.fg, bg=self.bg, **self.color_kwargs)
+
+    def fill(self) -> None:
+        self._dots = 0xFF
+
+    def clear(self) -> None:
+        self._dots = 0
+        self.marker = None
+
+    def update(
+        self, x: int, y: int, set_: bool = True, marker: str | None = None
+    ) -> None:
+        """(Un)Set dot at position x, y, with (0, 0) is top left corner.
+
+        Parameters:
+            x: int      x-coordinate ∈ [0, 1]
+            y: int      y-coordinate ∈ [0, 1, 2, 3]
+            set_: bool  True, sets dot, False, removes dot
+            marker: str Instead of braille dots set a marker char.
+        """
+        assert x in (0, 1)
+        assert y in (0, 1, 2, 3)
+
+        if set_:
+            self._dots |= _xy2dot[y][x]
+            if marker:
+                self.marker = marker
+        else:
+            self._dots = self._dots & (_xy2dot[y][x] ^ 0xFF)
+            self.marker = None
+
+
+def braille_from(dots: list[int]) -> str:
+    """Unicode character for braille with given dots set
+
+    See https://en.wikipedia.org/wiki/Braille_Patterns#Identifying.2C_naming_and_ordering
+    for dot to braille encoding.
+
+    Parameters:
+        dots: List[int]  All dots that should be set. Allowed dots are 1,2,3,4,5,6,7,8
+
+    Returns:
+        unicode: braille sign with given dots set. \u2800 - \u28ff
+    """
+    bin_code = ["0"] * 8
+    for i in dots:
+        bin_code[8 - i] = "1"
+
+    code = 0x2800 + int("".join(bin_code), 2)
+
+    return chr(code)
+
+
+def dots_from(braille: str) -> list[int]:
+    """Get set dots from given
+
+    See https://en.wikipedia.org/wiki/Braille_Patterns#Identifying.2C_naming_and_ordering
+    for braille to dot decoding.
+
+    Parameters:
+        braille: unicode  Braille character in \u2800 - \u28ff
+
+    Returns:
+        List[int]: dots that are set in braille sign
+    """
+    assert 0x2800 <= ord(braille) <= 0x28FF
+
+    code = str(bin(ord(braille) - 0x2800))[2:].rjust(8, "0")
+
+    dots = []
+    for i, c in enumerate(code):
+        if c == "1":
+            dots += [8 - i]
+
+    return sorted(dots)