tytable 0.6.0__py3-none-any.whl

tytable/__init__.py

@@ -0,0 +1,24 @@
+"""Public exports for :mod:`tytable`.
+
+Besides the :func:`tt` factory and :class:`TinyTable`, the package exposes
+:data:`THEMES`, the registry of built-in theme callables.
+"""
+
+from ._themes import THEMES
+from ._tytable import TinyTable, tt
+
+#: Built-in theme registry mapping public names to ``theme(table)`` callables.
+#: Pass a key to ``tt(theme=...)`` / ``TinyTable.theme()``, or inspect and call
+#: a registry value when building a custom theme.
+
+try:
+    from ._version import __version__
+except ImportError:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("tytable")
+    except PackageNotFoundError:
+        __version__ = "0.0.0"
+
+__all__ = ["tt", "TinyTable", "THEMES"]

tytable/_colors.py

@@ -0,0 +1,212 @@
+"""Color parsing → Typst color expressions. See guide 05 §8."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+_HEX_RE = re.compile(r"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
+_COLOR_FUNCTION_RE = re.compile(
+    r"^(?:rgb|luma|oklab|oklch|hsl|hsv)\([A-Za-z0-9.%+/,\s-]*\)$",
+    re.IGNORECASE,
+)
+
+_NAMED_COLORS: dict[str, str] = {
+    "aliceblue": "#f0f8ff",
+    "antiquewhite": "#faebd7",
+    "aqua": "#00ffff",
+    "aquamarine": "#7fffd4",
+    "azure": "#f0ffff",
+    "beige": "#f5f5dc",
+    "bisque": "#ffe4c4",
+    "blanchedalmond": "#ffebcd",
+    "blue": "#0000ff",
+    "blueviolet": "#8a2be2",
+    "brown": "#a52a2a",
+    "burlywood": "#deb887",
+    "cadetblue": "#5f9ea0",
+    "chartreuse": "#7fff00",
+    "chocolate": "#d2691e",
+    "coral": "#ff7f50",
+    "cornflowerblue": "#6495ed",
+    "cornsilk": "#fff8dc",
+    "crimson": "#dc143c",
+    "cyan": "#00ffff",
+    "darkblue": "#00008b",
+    "darkcyan": "#008b8b",
+    "darkgoldenrod": "#b8860b",
+    "darkgray": "#a9a9a9",
+    "darkgrey": "#a9a9a9",
+    "darkgreen": "#006400",
+    "darkkhaki": "#bdb76b",
+    "darkmagenta": "#8b008b",
+    "darkolivegreen": "#556b2f",
+    "darkorange": "#ff8c00",
+    "darkorchid": "#9932cc",
+    "darkred": "#8b0000",
+    "darksalmon": "#e9967a",
+    "darkseagreen": "#8fbc8f",
+    "darkslateblue": "#483d8b",
+    "darkslategray": "#2f4f4f",
+    "darkslategrey": "#2f4f4f",
+    "darkturquoise": "#00ced1",
+    "darkviolet": "#9400d3",
+    "deeppink": "#ff1493",
+    "deepskyblue": "#00bfff",
+    "dimgray": "#696969",
+    "dimgrey": "#696969",
+    "dodgerblue": "#1e90ff",
+    "firebrick": "#b22222",
+    "floralwhite": "#fffaf0",
+    "forestgreen": "#228b22",
+    "fuchsia": "#ff00ff",
+    "gainsboro": "#dcdcdc",
+    "ghostwhite": "#f8f8ff",
+    "gold": "#ffd700",
+    "goldenrod": "#daa520",
+    "gray": "#808080",
+    "grey": "#808080",
+    "green": "#008000",
+    "greenyellow": "#adff2f",
+    "honeydew": "#f0fff0",
+    "hotpink": "#ff69b4",
+    "indianred": "#cd5c5c",
+    "indigo": "#4b0082",
+    "ivory": "#fffff0",
+    "khaki": "#f0e68c",
+    "lavender": "#e6e6fa",
+    "lavenderblush": "#fff0f5",
+    "lawngreen": "#7cfc00",
+    "lemonchiffon": "#fffacd",
+    "lightblue": "#add8e6",
+    "lightcoral": "#f08080",
+    "lightcyan": "#e0ffff",
+    "lightgoldenrodyellow": "#fafad2",
+    "lightgray": "#d3d3d3",
+    "lightgrey": "#d3d3d3",
+    "lightgreen": "#90ee90",
+    "lightpink": "#ffb6c1",
+    "lightsalmon": "#ffa07a",
+    "lightseagreen": "#20b2aa",
+    "lightskyblue": "#87cefa",
+    "lightslategray": "#778899",
+    "lightslategrey": "#778899",
+    "lightsteelblue": "#b0c4de",
+    "lightyellow": "#ffffe0",
+    "lime": "#00ff00",
+    "limegreen": "#32cd32",
+    "linen": "#faf0e6",
+    "magenta": "#ff00ff",
+    "maroon": "#800000",
+    "mediumaquamarine": "#66cdaa",
+    "mediumblue": "#0000cd",
+    "mediumorchid": "#ba55d3",
+    "mediumpurple": "#9370db",
+    "mediumseagreen": "#3cb371",
+    "mediumslateblue": "#7b68ee",
+    "mediumspringgreen": "#00fa9a",
+    "mediumturquoise": "#48d1cc",
+    "mediumvioletred": "#c71585",
+    "midnightblue": "#191970",
+    "mintcream": "#f5fffa",
+    "mistyrose": "#ffe4e1",
+    "moccasin": "#ffe4b5",
+    "navajowhite": "#ffdead",
+    "navy": "#000080",
+    "oldlace": "#fdf5e6",
+    "olive": "#808000",
+    "olivedrab": "#6b8e23",
+    "orange": "#ffa500",
+    "orangered": "#ff4500",
+    "orchid": "#da70d6",
+    "palegoldenrod": "#eee8aa",
+    "palegreen": "#98fb98",
+    "paleturquoise": "#afeeee",
+    "palevioletred": "#db7093",
+    "papayawhip": "#ffefd5",
+    "peachpuff": "#ffdab8",
+    "peru": "#cd853f",
+    "pink": "#ffc0cb",
+    "plum": "#dda0dd",
+    "powderblue": "#b0e0e6",
+    "purple": "#800080",
+    "rebeccapurple": "#663399",
+    "red": "#ff0000",
+    "rosybrown": "#bc8f8f",
+    "royalblue": "#4169e1",
+    "saddlebrown": "#8b4513",
+    "salmon": "#fa8072",
+    "sandybrown": "#f4a460",
+    "seagreen": "#2e8b57",
+    "seashell": "#fff5ee",
+    "sienna": "#a0522d",
+    "silver": "#c0c0c0",
+    "skyblue": "#87ceeb",
+    "slateblue": "#6a5acd",
+    "slategray": "#708090",
+    "slategrey": "#708090",
+    "snow": "#fffafa",
+    "springgreen": "#00ff7f",
+    "steelblue": "#4682b4",
+    "tan": "#d2b48c",
+    "teal": "#008080",
+    "thistle": "#d8bfd8",
+    "tomato": "#ff6347",
+    "turquoise": "#40e0d0",
+    "violet": "#ee82ee",
+    "wheat": "#f5deb3",
+    "whitesmoke": "#f5f5f5",
+    "yellow": "#ffff00",
+    "yellowgreen": "#9acd32",
+}
+
+
+@lru_cache(maxsize=256)
+def color_to_typst(color: str) -> str:
+    """
+    Map a user color spec to a Typst color expression (guide 05 §8).
+
+    - "#RGB"/"#RRGGBB" -> rgb("#rrggbb") (normalize #RGB → #RRGGBB, lowercase)
+    - "#RGBA"/"#RRGGBBAA" -> rgb("#rrggbbaa") (normalize #RGBA → #RRGGBBAA, lowercase)
+    - "black"/"white"  -> black / white (Typst built-ins)
+    - named             -> rgb("#...") via the bundled dict
+    - safe color expression -> pass through unchanged
+
+    Raw expressions are limited to a color name or one of Typst's color
+    constructors with scalar arguments. This keeps useful expressions such as
+    ``luma(50%)`` while preventing a value from breaking out of the generated
+    style signature.
+    """
+    if not isinstance(color, str):
+        return str(color)
+    c = color.strip()
+    low = c.lower()
+    if low == "black":
+        return "black"
+    if low == "white":
+        return "white"
+    if low in _NAMED_COLORS:
+        return f'rgb("{_NAMED_COLORS[low]}")'
+    m = _HEX_RE.match(c)
+    if m:
+        digits = m.group(1)
+        if len(digits) in (3, 4):
+            digits = "".join(ch * 2 for ch in digits)
+        return f'rgb("#{digits.lower()}")'
+    _validate_color_string(c)
+    return c
+
+
+def _validate_color_string(color: str) -> None:
+    """Accept only bundled color names, hex colors, and known color constructors."""
+    if (
+        color.lower() in _NAMED_COLORS
+        or color.lower() in ("black", "white")
+        or _HEX_RE.fullmatch(color)
+        or _COLOR_FUNCTION_RE.fullmatch(color)
+    ):
+        return
+    raise ValueError(
+        f"invalid color value {color!r}: expected a color name, hex color, "
+        "or supported color function"
+    )

tytable/_constants.py

@@ -0,0 +1,28 @@
+"""Static Typst snippets inlined into every styled table render."""
+
+STATIC_GET_STYLE_AND_SHOW_RULE: str = """\
+  #let get-style(x, y) = {
+    let key = str(y) + "_" + str(x)
+    if key in style-dict { style-array.at(style-dict.at(key)) } else { none }
+  }
+
+  #show table.cell: it => {
+    if style-array.len() == 0 { return it }
+    let style = get-style(it.x, it.y)
+    if style == none { return it }
+    let tmp = it
+    if ("fontsize" in style) { tmp = text(size: style.fontsize, tmp) }
+    if ("color" in style) { tmp = text(fill: style.color, tmp) }
+    if ("indent" in style) { tmp = pad(left: style.indent, tmp) }
+    if ("underline" in style) { tmp = underline(tmp) }
+    if ("italic" in style) { tmp = emph(tmp) }
+    if ("bold" in style) { tmp = strong(tmp) }
+    if ("mono" in style) { tmp = math.mono(tmp) }
+    if ("strikeout" in style) { tmp = strike(tmp) }
+    if ("smallcaps" in style) { tmp = smallcaps(tmp) }
+    if ("rotate" in style) {
+      let a = if "align" in style { style.align } else { left }
+      tmp = align(a, rotate(style.rotate, reflow: true, tmp))
+    }
+    tmp
+  }"""

tytable/_directives.py

@@ -0,0 +1,114 @@
+"""
+Frozen dataclasses recording user *intent* (styles, formats, plots, groups).
+
+These are produced by the chaining methods on :class:`~tytable._tytable.TinyTable`
+and replayed at render time by :func:`tytable._resolve.build`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import polars as pl
+
+
+@dataclass(frozen=True)
+class StyleDirective:
+    """A single ``.style()`` call: selectors plus the cell properties to apply."""
+
+    i: int | str | Sequence[int | str] | pl.Expr | pl.Series | Callable[[dict], bool] | None
+    j: int | str | Sequence[int | str] | None
+    regex: bool = False
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    strikeout: bool | None = None
+    monospace: bool | None = None
+    smallcaps: bool | None = None
+    color: str | None = None
+    background: str | None = None
+    fontsize: float | None = None
+    align: str | None = None
+    alignv: str | None = None
+    indent: float | None = None
+    colspan: int | None = None
+    rowspan: int | None = None
+    rotate: float | None = None
+    line: str | None = None
+    line_color: str | None = None
+    line_width: float | None = 0.1
+    line_trim: str | None = None
+    output: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True)
+class FormatDirective:
+    """A single ``.fmt()`` call: selectors plus numeric/format/replace/fn transforms."""
+
+    i: int | str | Sequence[int | str] | pl.Expr | pl.Series | Callable[[dict], bool] | None
+    j: int | str | Sequence[int | str] | None
+    regex: bool = False
+    digits: int | None = None
+    num_fmt: str | None = "decimal"
+    replace: dict | str | bool | None = None
+    escape: bool | str = False
+    fn: Callable | None = None
+    output: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True)
+class PlotDirective:
+    """A single ``.plot()`` call."""
+
+    i: int | str | Sequence[int | str] | pl.Expr | pl.Series | Callable[[dict], bool] | None
+    j: int | str | Sequence[int | str] | None
+    fun: Callable
+    regex: bool = False
+    data: list | None = None
+    color: str = "black"
+    xlim: list[float] | None = None
+    height: float = 1.0
+    height_px: int = 400
+    width_px: int = 1200
+    output: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True)
+class ImageDirective:
+    """A single ``.images()`` call."""
+
+    i: int | str | Sequence[int | str] | pl.Expr | pl.Series | Callable[[dict], bool] | None
+    j: int | str | Sequence[int | str] | None
+    images: list[str]
+    regex: bool = False
+    height: float = 1.0
+    output: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True)
+class RowGroup:
+    """A row-group separator: ``label`` displayed before data row ``position``."""
+
+    label: str
+    position: int
+
+
+@dataclass(frozen=True)
+class ColGroup:
+    """A column group: ``label`` spanning ``columns`` (0-based positions)."""
+
+    label: str
+    columns: list[int]
+
+
+@dataclass(frozen=True)
+class Note:
+    """A footnote; ``marker`` is auto-assigned when ``i``/``j`` target a cell."""
+
+    text: str
+    marker: str | None = None
+    i: list[int] | None = None
+    j: list[int] | None = None

tytable/_escape.py

@@ -0,0 +1,58 @@
+"""Escaping for Typst and HTML metacharacters in cell text and captions."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+TYPST_ESCAPE = {
+    "\\": "\\\\",
+    "<": "\\<",
+    ">": "\\>",
+    "*": "\\*",
+    "_": "\\_",
+    "@": "\\@",
+    "=": "\\=",
+    "-": "\\-",
+    "+": "\\+",
+    "/": "\\/",
+    "$": "\\$",
+    "#": "\\#",
+    "[": "\\[",
+    "]": "\\]",
+    "`": "\\`",
+    "~": "\\~",
+}
+TYPST_SPECIAL_RE = re.compile(r"[\\<>*_@=+/\$#\[\]`~\-]")
+
+HTML_ESCAPE = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+}
+HTML_SPECIAL_RE = re.compile(r"[&<>]")
+
+
+def escape_typst(text: object) -> str:
+    """Backslash-escape Typst metacharacters in ``text`` (no-op when none are present)."""
+    return _escape_typst_cached(str(text))
+
+
+@lru_cache(maxsize=4096)
+def _escape_typst_cached(text: str) -> str:
+    """Cache escaped strings used repeatedly across table cells."""
+    if not text:
+        return text
+    if not TYPST_SPECIAL_RE.search(text):
+        return text
+    return TYPST_SPECIAL_RE.sub(lambda m: TYPST_ESCAPE[m.group(0)], text)
+
+
+def escape_html(text: object) -> str:
+    """Escape ``&``, ``<``, ``>`` for safe inclusion in HTML text."""
+    text = str(text)
+    if not text:
+        return text
+    if not HTML_SPECIAL_RE.search(text):
+        return text
+    return HTML_SPECIAL_RE.sub(lambda m: HTML_ESCAPE[m.group(0)], text)