rich-struct 0.1.0__tar.gz

rich_struct-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.pytest_cache/
+dist/
+*.egg-info/
+.ipynb_checkpoints/

rich_struct-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mirek Wiertel
+
+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.

rich_struct-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: rich-struct
+Version: 0.1.0
+Summary: rich.print with 21 popular editor themes (Tokyo Night, Dracula, Nord, ...) and print_md/json/yaml/xml/object/table helpers
+Project-URL: Homepage, https://github.com/wiertmir/rich-struct
+Project-URL: Issues, https://github.com/wiertmir/rich-struct/issues
+Author: Mirek Wiertel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: markdown,print,rich,syntax highlighting,terminal,theme
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Requires-Python: >=3.9
+Requires-Dist: rich>=13
+Provides-Extra: yaml
+Requires-Dist: pyyaml; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# rich-struct
+
+[`rich`](https://github.com/Textualize/rich)'s `print`, with 21 popular editor themes and helpers for Markdown, JSON, YAML, XML, Python objects and tables (lists, numpy arrays, pandas DataFrames and Series).
+
+```sh
+pip install rich-struct          # add [yaml] to dump objects with print_yaml
+```
+
+```python
+from rich.markdown import Markdown
+from rich.theme import Theme
+from rich_struct import ThemeName, print, print_md, print_json, print_yaml, print_xml, print_object, print_syntax, print_table
+
+print("[bold]hello[/bold]", {"a": 1})                 # drop-in rich.print, Tokyo Night by default
+print(Markdown("## Printing structs"), theme=ThemeName.DRACULA)
+
+print_md("# Title\n\n```python\nprint('hi')\n```")
+print_json({"a": [1, 2, None]}, theme="Nord")         # enum value as a string works too
+print_yaml("a: 1\nb: [x, y]")
+print_xml("<a><b c='d'/></a>")
+print_object(my_dataclass, theme=ThemeName.GITHUB_LIGHT)
+print_syntax("SELECT 1", "sql")                       # any pygments lexer
+print_table(df, title="Sales")                        # DataFrame, Series, numpy array, list...
+print(df)                                             # arrays and frames become tables in print too
+
+print_md("# Mine", theme=Theme({"markdown.h1": "bold magenta", "syntax.keyword": "red"}))
+```
+
+Every function takes `theme=`: a `ThemeName`, its string value, or a rich `Theme`.
+`ThemeName.X.theme` gives you the underlying rich `Theme` to use with your own `Console`.
+
+## Tables
+
+`print_table(data, title=None, max_rows=20, max_cols=10)` accepts:
+
+- pandas `DataFrame` and `Series`, numpy arrays of any dimension (more than 2: one table per slice)
+- lists of dicts (records), lists of lists (a grid), and any other sequence such as `array.array` or `range` (one column)
+
+Numbers are right-aligned, floats in a column share their decimals, and missing values are dimmed.
+Long data shows its head and tail around a `…` gap, and columns that don't fit the terminal width go into the gap as well.
+`to_table(data)` returns the renderable instead of printing it. numpy and pandas are not dependencies.
+
+## Themes
+
+| Dark | Light |
+|---|---|
+| Tokyo Night (default) | GitHub Light |
+| Dracula | Solarized Light |
+| One Dark Pro | One Light |
+| Monokai | Catppuccin Latte |
+| Nord | Gruvbox Light |
+| Gruvbox Dark | Tokyo Night Light |
+| Catppuccin Mocha | Ayu Light |
+| Solarized Dark | Night Owl Light |
+| GitHub Dark | Light+ |
+| Night Owl | Everforest Light |
+| Winter is Coming | |
+
+Themes are built from each theme's colour palette, not ported token-by-token from the editor.
+
+Output is painted on the theme's background across the full terminal width. Pass `background=False` to keep the terminal's own background; nothing is painted or padded when the output has no colour (e.g. piped to a file). A custom `Theme` gets a background by defining a `background` style, e.g. `"background": "#c0caf5 on #1a1b26"`.
+
+Code colours come from `syntax.*` styles (`text`, `comment`, `keyword`, `string`, `number`, `function`, `type`, `tag`, `attribute`, `operator`); a custom `Theme` may override any of them.

rich_struct-0.1.0/README.md

@@ -0,0 +1,63 @@
+# rich-struct
+
+[`rich`](https://github.com/Textualize/rich)'s `print`, with 21 popular editor themes and helpers for Markdown, JSON, YAML, XML, Python objects and tables (lists, numpy arrays, pandas DataFrames and Series).
+
+```sh
+pip install rich-struct          # add [yaml] to dump objects with print_yaml
+```
+
+```python
+from rich.markdown import Markdown
+from rich.theme import Theme
+from rich_struct import ThemeName, print, print_md, print_json, print_yaml, print_xml, print_object, print_syntax, print_table
+
+print("[bold]hello[/bold]", {"a": 1})                 # drop-in rich.print, Tokyo Night by default
+print(Markdown("## Printing structs"), theme=ThemeName.DRACULA)
+
+print_md("# Title\n\n```python\nprint('hi')\n```")
+print_json({"a": [1, 2, None]}, theme="Nord")         # enum value as a string works too
+print_yaml("a: 1\nb: [x, y]")
+print_xml("<a><b c='d'/></a>")
+print_object(my_dataclass, theme=ThemeName.GITHUB_LIGHT)
+print_syntax("SELECT 1", "sql")                       # any pygments lexer
+print_table(df, title="Sales")                        # DataFrame, Series, numpy array, list...
+print(df)                                             # arrays and frames become tables in print too
+
+print_md("# Mine", theme=Theme({"markdown.h1": "bold magenta", "syntax.keyword": "red"}))
+```
+
+Every function takes `theme=`: a `ThemeName`, its string value, or a rich `Theme`.
+`ThemeName.X.theme` gives you the underlying rich `Theme` to use with your own `Console`.
+
+## Tables
+
+`print_table(data, title=None, max_rows=20, max_cols=10)` accepts:
+
+- pandas `DataFrame` and `Series`, numpy arrays of any dimension (more than 2: one table per slice)
+- lists of dicts (records), lists of lists (a grid), and any other sequence such as `array.array` or `range` (one column)
+
+Numbers are right-aligned, floats in a column share their decimals, and missing values are dimmed.
+Long data shows its head and tail around a `…` gap, and columns that don't fit the terminal width go into the gap as well.
+`to_table(data)` returns the renderable instead of printing it. numpy and pandas are not dependencies.
+
+## Themes
+
+| Dark | Light |
+|---|---|
+| Tokyo Night (default) | GitHub Light |
+| Dracula | Solarized Light |
+| One Dark Pro | One Light |
+| Monokai | Catppuccin Latte |
+| Nord | Gruvbox Light |
+| Gruvbox Dark | Tokyo Night Light |
+| Catppuccin Mocha | Ayu Light |
+| Solarized Dark | Night Owl Light |
+| GitHub Dark | Light+ |
+| Night Owl | Everforest Light |
+| Winter is Coming | |
+
+Themes are built from each theme's colour palette, not ported token-by-token from the editor.
+
+Output is painted on the theme's background across the full terminal width. Pass `background=False` to keep the terminal's own background; nothing is painted or padded when the output has no colour (e.g. piped to a file). A custom `Theme` gets a background by defining a `background` style, e.g. `"background": "#c0caf5 on #1a1b26"`.
+
+Code colours come from `syntax.*` styles (`text`, `comment`, `keyword`, `string`, `number`, `function`, `type`, `tag`, `attribute`, `operator`); a custom `Theme` may override any of them.

rich_struct-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rich-struct"
+version = "0.1.0"
+description = "rich.print with 21 popular editor themes (Tokyo Night, Dracula, Nord, ...) and print_md/json/yaml/xml/object/table helpers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mirek Wiertel" }]
+dependencies = ["rich>=13"]
+keywords = ["rich", "print", "theme", "terminal", "markdown", "syntax highlighting"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Topic :: Terminals",
+]
+
+[project.optional-dependencies]
+yaml = ["pyyaml"]
+
+[project.urls]
+Homepage = "https://github.com/wiertmir/rich-struct"
+Issues = "https://github.com/wiertmir/rich-struct/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rich_struct"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["demos.ipynb"]

rich_struct-0.1.0/rich_struct/__init__.py

@@ -0,0 +1,137 @@
+"""Themed drop-in extension of ``rich.print``."""
+
+import xml.etree.ElementTree as ET
+from typing import IO, Any, Optional, Union
+
+from rich.console import Console
+from rich.json import JSON
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.pretty import Pretty
+from rich.protocol import is_renderable
+from rich.syntax import Syntax
+from rich.theme import Theme
+
+from .tables import is_array, to_table
+from .themes import DEFAULT_THEME, ThemeLiteral, ThemeName, syntax_theme
+
+__all__ = [
+    "DEFAULT_THEME",
+    "ThemeLiteral",
+    "ThemeName",
+    "ThemeType",
+    "print",
+    "print_json",
+    "print_md",
+    "print_object",
+    "print_syntax",
+    "print_table",
+    "print_xml",
+    "print_yaml",
+    "to_table",
+]
+
+ThemeType = Union[ThemeName, Theme, ThemeLiteral]
+
+
+def print(
+    *objects: Any,
+    sep: str = " ",
+    end: str = "\n",
+    file: Optional[IO[str]] = None,
+    theme: ThemeType = DEFAULT_THEME,
+    background: bool = True,
+    **kwargs: Any,
+) -> None:
+    """``rich.print`` with a theme.
+
+    ``theme`` is a :class:`ThemeName` (or its string value) or a rich ``Theme``.
+    ``Markdown`` and ``Syntax`` objects get their code colours from the theme too,
+    and numpy arrays, pandas DataFrames and Series are shown as tables.
+    The theme's background is painted across the full terminal width unless
+    ``background=False`` (or the output has no colour, e.g. when piped to a file).
+    Extra keyword arguments go to ``Console.print`` (``style``, ``justify``, ...).
+    """
+    rich_theme = theme if isinstance(theme, Theme) else ThemeName(theme).theme
+    code_theme = syntax_theme(rich_theme)
+    objects = tuple(to_table(obj) if is_array(obj) else obj for obj in objects)
+    for obj in objects:
+        if isinstance(obj, Markdown):
+            obj.code_theme = code_theme
+        elif isinstance(obj, Syntax):
+            # ponytail: Syntax has no public theme setter; rebuild the object if rich renames this
+            obj._theme = code_theme
+    console = Console(theme=rich_theme, file=file)
+    base = rich_theme.styles.get("background")
+    if background and base and console.color_system:
+        # fill whole lines: Padding expands renderables, justify pads plain text
+        objects = tuple(
+            Padding(obj, 0) if is_renderable(obj) and not isinstance(obj, str) else obj
+            for obj in objects
+        )
+        kwargs.setdefault("justify", "left")
+        kwargs["style"] = base + console.get_style(kwargs.get("style") or "none")
+    console.print(*objects, sep=sep, end=end, **kwargs)
+
+
+def print_md(markdown: str, *, theme: ThemeType = DEFAULT_THEME, **kwargs: Any) -> None:
+    print(Markdown(markdown), theme=theme, **kwargs)
+
+
+def print_syntax(
+    code: str, lexer: str, *, theme: ThemeType = DEFAULT_THEME, **kwargs: Any
+) -> None:
+    """Print ``code`` highlighted with any pygments ``lexer`` ("python", "toml", ...)."""
+    print(Syntax(code, lexer, word_wrap=True), theme=theme, **kwargs)
+
+
+def print_json(data: Any, *, theme: ThemeType = DEFAULT_THEME, **kwargs: Any) -> None:
+    """Print a JSON string, or any JSON-serialisable object."""
+    json = JSON(data) if isinstance(data, str) else JSON.from_data(data, default=str)
+    print(json, theme=theme, **kwargs)
+
+
+def print_yaml(data: Any, *, theme: ThemeType = DEFAULT_THEME, **kwargs: Any) -> None:
+    """Print a YAML string, or dump an object as YAML (needs ``rich-struct[yaml]``)."""
+    if not isinstance(data, str):
+        import yaml
+
+        data = yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
+    print_syntax(data.rstrip("\n"), "yaml", theme=theme, **kwargs)
+
+
+def print_xml(
+    data: Union[str, ET.Element, ET.ElementTree],
+    *,
+    theme: ThemeType = DEFAULT_THEME,
+    **kwargs: Any,
+) -> None:
+    """Print an XML string as-is, or an ElementTree element indented."""
+    if not isinstance(data, str):
+        root = data.getroot() if isinstance(data, ET.ElementTree) else data
+        ET.indent(root)
+        data = ET.tostring(root, encoding="unicode")
+    print_syntax(data.rstrip("\n"), "xml", theme=theme, **kwargs)
+
+
+def print_object(obj: Any, *, theme: ThemeType = DEFAULT_THEME, **kwargs: Any) -> None:
+    """Pretty-print any Python object (dataclasses, dicts, nested structures...)."""
+    print(Pretty(obj, expand_all=True), theme=theme, **kwargs)
+
+
+def print_table(
+    data: Any,
+    *,
+    title: Optional[str] = None,
+    max_rows: int = 20,
+    max_cols: int = 10,
+    theme: ThemeType = DEFAULT_THEME,
+    **kwargs: Any,
+) -> None:
+    """Print a list, array, numpy array, pandas DataFrame or Series as a table.
+
+    Lists of dicts become records, lists of lists a grid. Data longer than
+    ``max_rows``/``max_cols`` shows its head and tail around a "…" gap.
+    """
+    table = to_table(data, title=title, max_rows=max_rows, max_cols=max_cols)
+    print(table, theme=theme, **kwargs)

rich_struct-0.1.0/rich_struct/tables.py

@@ -0,0 +1,174 @@
+"""Lists, arrays, numpy arrays and pandas objects as rich tables.
+
+Everything is duck-typed, so neither numpy nor pandas is imported (or required).
+"""
+
+from collections.abc import Mapping
+from numbers import Integral, Real
+from typing import Any, List, Optional, Tuple
+
+from rich import box
+from rich.console import Console, ConsoleOptions, Group, RenderableType, RenderResult
+from rich.table import Table
+from rich.text import Text
+
+_MISSING = {"None", "nan", "NaN", "NaT", "<NA>"}
+_GAP = "…"
+
+
+def is_array(obj: Any) -> bool:
+    """numpy arrays, pandas DataFrames/Series and anything else array-like with a shape."""
+    return hasattr(obj, "__array__") and getattr(obj, "ndim", 0) > 0
+
+
+def _clip(n: int, limit: int) -> List[Optional[int]]:
+    """Positions to show out of ``n``: head and tail, with None marking the gap."""
+    if n <= limit:
+        return list(range(n))
+    head = (limit + 1) // 2
+    return [*range(head), None, *range(n - (limit - head), n)]
+
+
+def _is_float(value: Any) -> bool:
+    return isinstance(value, Real) and not isinstance(value, Integral) and not _is_bool(value)
+
+
+def _is_bool(value: Any) -> bool:
+    return type(value).__name__ in ("bool", "bool_")
+
+
+def _cell(value: Any) -> Text:
+    text = format(value, ".6g") if _is_float(value) else str(value)
+    if isinstance(value, str):
+        style = "repr.ellipsis" if value == _GAP else "repr.str"
+    elif text in _MISSING:
+        style = "repr.none"
+    elif _is_bool(value):
+        style = "repr.bool_true" if value else "repr.bool_false"
+    else:
+        style = "repr.number" if isinstance(value, Real) else "none"
+    return Text(text, style=style)
+
+
+def _column(values: List[Any]) -> List[Text]:
+    """Cells of one column; its floats get the same number of decimals."""
+    cells = [_cell(value) for value in values]
+    floats = [i for i, value in enumerate(values) if _is_float(value) and value == value]
+    if floats and not any("e" in cells[i].plain for i in floats):
+        decimals = min(6, max(1, *(len(cells[i].plain.partition(".")[2]) for i in floats)))
+        for i in floats:
+            cells[i].plain = f"{values[i]:.{decimals}f}"
+    return cells
+
+
+class _Fitted:
+    """Renders ``data`` with as many columns (up to ``max_cols``) as fit the console."""
+
+    def __init__(
+        self, data: Any, title: Optional[str], max_rows: int, max_cols: int, caption: bool = True
+    ) -> None:
+        self.data, self.title, self.max_rows, self.max_cols = data, title, max_rows, max_cols
+        self.caption = caption
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        max_cols = self.max_cols
+        unlimited = options.update_width(10_000)  # measure the table before rich squeezes it
+        while True:
+            table, caption = _build(self.data, self.max_rows, max_cols)
+            if max_cols <= 2 or console.measure(table, options=unlimited).maximum <= options.max_width:
+                break
+            max_cols -= 1
+        if self.title:
+            yield Text(self.title, style="table.title")
+        yield table
+        if self.caption:
+            yield Text(caption, style="table.caption")
+
+
+def to_table(
+    data: Any, *, title: Optional[str] = None, max_rows: int = 20, max_cols: int = 10
+) -> RenderableType:
+    """A renderable table for a list, array, numpy array, DataFrame or Series.
+
+    Lists of dicts become records, lists of lists a grid, anything else one column.
+    Long data shows its first and last rows/columns around a "…" gap, and columns
+    that don't fit the console width are dropped into that gap too.
+    """
+    if is_array(data) and data.ndim > 2 and not hasattr(data, "iloc"):
+        shown = min(len(data), 3)
+        slices = [
+            _Fitted(data[i], f"[{i}]", max_rows, max_cols, caption=False)
+            if data.ndim == 3
+            else to_table(data[i], title=f"[{i}]", max_rows=max_rows, max_cols=max_cols)
+            for i in range(shown)
+        ]
+        if len(data) > shown:
+            slices.append(Text(f"… {len(data) - shown} more", style="repr.ellipsis"))
+        whole = f"{type(data).__name__} · shape {tuple(data.shape)} · dtype {data.dtype}"
+        heading = [Text(title, style="table.title")] if title else []
+        return Group(*heading, *slices, Text(whole, style="table.caption"))
+    return _Fitted(data, title, max_rows, max_cols)
+
+
+def _build(data: Any, max_rows: int, max_cols: int) -> Tuple[Table, str]:
+    corner = ""
+    if hasattr(data, "iloc"):  # pandas
+        if data.ndim == 1:
+            caption = f"Series · dtype {data.dtype} · {len(data)} items"
+            data = data.to_frame(name="value" if data.name is None else data.name)
+        else:
+            caption = f"DataFrame · {data.shape[0]} rows × {data.shape[1]} columns"
+        shown_rows, shown_cols = _clip(data.shape[0], max_rows), _clip(data.shape[1], max_cols)
+        part = data.iloc[
+            [i for i in shown_rows if i is not None], [j for j in shown_cols if j is not None]
+        ]
+        corner = "" if data.index.name is None else str(data.index.name)
+        columns, index = list(part.columns), list(part.index)
+        rows = [list(row) for row in part.itertuples(index=False, name=None)]
+    elif is_array(data):  # numpy and friends
+        caption = f"{type(data).__name__} · shape {tuple(data.shape)} · dtype {data.dtype}"
+        grid = data.reshape(-1, 1) if data.ndim == 1 else data
+        shown_rows, shown_cols = _clip(grid.shape[0], max_rows), _clip(grid.shape[1], max_cols)
+        index = [i for i in shown_rows if i is not None]
+        columns = [j for j in shown_cols if j is not None]
+        rows = grid[index][:, columns].tolist()
+        if data.ndim == 1:
+            columns = ["value"]
+    else:  # any other sequence: list, tuple, array.array, range, generator...
+        kind = type(data).__name__
+        data = list(data)
+        caption = f"{kind} · {len(data)} items"
+        shown_rows = _clip(len(data), max_rows)
+        index = [i for i in shown_rows if i is not None]
+        items = [data[i] for i in index]
+        if items and all(isinstance(item, Mapping) for item in items):
+            keys = list(dict.fromkeys(key for item in items for key in item))
+            grid = [[item.get(key) for key in keys] for item in items]
+        elif items and all(isinstance(item, (list, tuple)) for item in items):
+            keys = list(range(max(map(len, items))))
+            grid = [[*item, *[None] * (len(keys) - len(item))] for item in items]
+        else:
+            keys, grid = ["value"], [[item] for item in items]
+        shown_cols = _clip(len(keys), max_cols)
+        columns = [keys[j] for j in shown_cols if j is not None]
+        rows = [[row[j] for j in shown_cols if j is not None] for row in grid]
+
+    if None in shown_cols:
+        gap = shown_cols.index(None)
+        columns.insert(gap, _GAP)
+        for row in rows:
+            row.insert(gap, _GAP)
+    if None in shown_rows:
+        gap = shown_rows.index(None)
+        index.insert(gap, _GAP)
+        rows.insert(gap, [_GAP] * len(columns))
+
+    cells = [_column([row[j] for row in rows]) for j in range(len(columns))]
+    table = Table(box=box.ROUNDED, border_style="rule.line", header_style="table.header")
+    table.add_column(corner, style="table.header", justify="right", no_wrap=True)
+    for name, column in zip(columns, cells):
+        numeric = all(cell.style in ("repr.number", "repr.none", "repr.ellipsis") for cell in column)
+        table.add_column(str(name), justify="right" if numeric else "left")
+    for label, *row in zip(index, *cells):
+        table.add_row(str(label), *row)
+    return table, caption

rich_struct-0.1.0/rich_struct/themes.py

@@ -0,0 +1,240 @@
+"""Theme palettes and their translation into rich ``Theme`` objects."""
+
+from enum import Enum
+from functools import lru_cache
+from typing import Literal
+
+from pygments.token import (
+    Comment,
+    Error,
+    Generic,
+    Keyword,
+    Name,
+    Number,
+    Operator,
+    String,
+    Token,
+)
+from rich.style import Style
+from rich.syntax import ANSISyntaxTheme, SyntaxTheme
+from rich.theme import Theme
+
+
+class ThemeName(str, Enum):
+    # dark
+    TOKYO_NIGHT = "Tokyo Night"
+    DRACULA = "Dracula"
+    ONE_DARK_PRO = "One Dark Pro"
+    MONOKAI = "Monokai"
+    NORD = "Nord"
+    GRUVBOX_DARK = "Gruvbox Dark"
+    CATPPUCCIN_MOCHA = "Catppuccin Mocha"
+    SOLARIZED_DARK = "Solarized Dark"
+    GITHUB_DARK = "GitHub Dark"
+    NIGHT_OWL = "Night Owl"
+    WINTER_IS_COMING = "Winter is Coming"
+    # light
+    GITHUB_LIGHT = "GitHub Light"
+    SOLARIZED_LIGHT = "Solarized Light"
+    ONE_LIGHT = "One Light"
+    CATPPUCCIN_LATTE = "Catppuccin Latte"
+    GRUVBOX_LIGHT = "Gruvbox Light"
+    TOKYO_NIGHT_LIGHT = "Tokyo Night Light"
+    AYU_LIGHT = "Ayu Light"
+    NIGHT_OWL_LIGHT = "Night Owl Light"
+    LIGHT_PLUS = "Light+"
+    EVERFOREST_LIGHT = "Everforest Light"
+
+    @property
+    def is_dark(self) -> bool:
+        return self in _DARK
+
+    @property
+    def theme(self) -> Theme:
+        return _build(self)
+
+
+# The ThemeName values again, spelled out so editors can autocomplete theme="...".
+# Static type checkers can't derive this from the enum; a test keeps the two in sync.
+ThemeLiteral = Literal[
+    "Tokyo Night",
+    "Dracula",
+    "One Dark Pro",
+    "Monokai",
+    "Nord",
+    "Gruvbox Dark",
+    "Catppuccin Mocha",
+    "Solarized Dark",
+    "GitHub Dark",
+    "Night Owl",
+    "Winter is Coming",
+    "GitHub Light",
+    "Solarized Light",
+    "One Light",
+    "Catppuccin Latte",
+    "Gruvbox Light",
+    "Tokyo Night Light",
+    "Ayu Light",
+    "Night Owl Light",
+    "Light+",
+    "Everforest Light",
+]
+
+DEFAULT_THEME = ThemeName.TOKYO_NIGHT
+
+T = ThemeName
+#                       bg     fg     comment   red       orange    yellow    green     cyan      blue      purple
+_PALETTES = {
+    T.TOKYO_NIGHT:       "1a1b26 c0caf5 565f89 f7768e ff9e64 e0af68 9ece6a 7dcfff 7aa2f7 bb9af7",
+    T.DRACULA:           "282a36 f8f8f2 6272a4 ff5555 ffb86c f1fa8c 50fa7b 8be9fd bd93f9 ff79c6",
+    T.ONE_DARK_PRO:      "282c34 abb2bf 5c6370 e06c75 d19a66 e5c07b 98c379 56b6c2 61afef c678dd",
+    T.MONOKAI:           "272822 f8f8f2 75715e f92672 fd971f e6db74 a6e22e a1efe4 66d9ef ae81ff",
+    T.NORD:              "2e3440 d8dee9 616e88 bf616a d08770 ebcb8b a3be8c 88c0d0 81a1c1 b48ead",
+    T.GRUVBOX_DARK:      "282828 ebdbb2 928374 fb4934 fe8019 fabd2f b8bb26 8ec07c 83a598 d3869b",
+    T.CATPPUCCIN_MOCHA:  "1e1e2e cdd6f4 6c7086 f38ba8 fab387 f9e2af a6e3a1 89dceb 89b4fa cba6f7",
+    T.SOLARIZED_DARK:    "002b36 839496 586e75 dc322f cb4b16 b58900 859900 2aa198 268bd2 6c71c4",
+    T.GITHUB_DARK:       "0d1117 c9d1d9 8b949e ff7b72 ffa657 e3b341 7ee787 a5d6ff 79c0ff d2a8ff",
+    T.NIGHT_OWL:         "011627 d6deeb 637777 ef5350 f78c6c ecc48d addb67 7fdbca 82aaff c792ea",
+    T.WINTER_IS_COMING:  "011627 a7dbf7 999999 ef5350 8dec95 f7ecb5 bcf0c0 7fdbca 87aff4 00bff9",
+    T.GITHUB_LIGHT:      "ffffff 24292f 6e7781 cf222e 953800 9a6700 116329 1b7c83 0550ae 8250df",
+    T.SOLARIZED_LIGHT:   "fdf6e3 657b83 93a1a1 dc322f cb4b16 b58900 859900 2aa198 268bd2 6c71c4",
+    T.ONE_LIGHT:         "fafafa 383a42 a0a1a7 e45649 986801 c18401 50a14f 0184bc 4078f2 a626a4",
+    T.CATPPUCCIN_LATTE:  "eff1f5 4c4f69 9ca0b0 d20f39 fe640b df8e1d 40a02b 04a5e5 1e66f5 8839ef",
+    T.GRUVBOX_LIGHT:     "fbf1c7 3c3836 928374 9d0006 af3a03 b57614 79740e 427b58 076678 8f3f71",
+    T.TOKYO_NIGHT_LIGHT: "d5d6db 343b58 9699a3 8c4351 965027 8f5e15 485e30 0f4b6e 34548a 5a4a78",
+    T.AYU_LIGHT:         "fafafa 5c6166 abb0b6 f07171 fa8d3e f2ae49 86b300 4cbf99 399ee6 a37acc",
+    T.NIGHT_OWL_LIGHT:   "fbfbfb 403f53 989fb1 de3d3b c96765 daaa01 08916a 0c969b 4876d6 994cc3",
+    T.LIGHT_PLUS:        "ffffff 000000 008000 a31515 811f3f 795e26 098658 267f99 0000ff af00db",
+    T.EVERFOREST_LIGHT:  "fdf6e3 5c6a72 939f91 f85552 f57d26 dfa000 8da101 35a77c 3a94c5 df69ba",
+}
+_DARK = frozenset(list(T)[:11])
+del T
+
+# pygments token -> name of the "syntax.*" style that colours it
+_TOKENS = {
+    Token: "text",
+    Comment: "comment",
+    Keyword: "keyword",
+    Keyword.Constant: "number",
+    Keyword.Type: "type",
+    Name.Function: "function",
+    Name.Class: "type",
+    Name.Builtin: "type",
+    Name.Tag: "tag",
+    Name.Attribute: "attribute",
+    Name.Decorator: "attribute",
+    Name.Constant: "number",
+    String: "string",
+    String.Escape: "operator",
+    Number: "number",
+    Operator: "operator",
+    Generic.Deleted: "tag",
+    Generic.Inserted: "string",
+    Generic.Heading: "function",
+    Error: "tag",
+}
+
+
+@lru_cache(maxsize=None)
+def _build(name: ThemeName) -> Theme:
+    bg, fg, comment, red, orange, yellow, green, cyan, blue, purple = (
+        "#" + c for c in _PALETTES[name].split()
+    )
+    return Theme(
+        {
+            "background": f"{fg} on {bg}",
+            # code (see _TOKENS)
+            "syntax.text": fg,
+            "syntax.comment": f"italic {comment}",
+            "syntax.keyword": purple,
+            "syntax.string": green,
+            "syntax.number": orange,
+            "syntax.function": blue,
+            "syntax.type": cyan,
+            "syntax.tag": red,
+            "syntax.attribute": yellow,
+            "syntax.operator": cyan,
+            # markdown
+            "markdown.paragraph": fg,
+            "markdown.text": fg,
+            "markdown.h1": f"bold {purple}",
+            "markdown.h1.border": comment,
+            "markdown.h2": f"bold {blue}",
+            "markdown.h3": f"bold {cyan}",
+            "markdown.h4": f"bold {green}",
+            "markdown.h5": f"bold {yellow}",
+            "markdown.h6": f"italic {comment}",
+            "markdown.h7": f"italic {comment}",
+            "markdown.strong": f"bold {orange}",
+            "markdown.em": f"italic {yellow}",
+            "markdown.emph": f"italic {yellow}",
+            "markdown.s": f"strike {comment}",
+            "markdown.code": green,
+            "markdown.code_block": fg,
+            "markdown.block_quote": f"italic {comment}",
+            "markdown.item": fg,
+            "markdown.item.bullet": f"bold {yellow}",
+            "markdown.item.number": f"bold {yellow}",
+            "markdown.hr": comment,
+            "markdown.link": blue,
+            "markdown.link_url": f"underline {cyan}",
+            "markdown.table.border": comment,
+            "markdown.table.header": f"bold {blue}",
+            # json
+            "json.key": f"bold {blue}",
+            "json.str": green,
+            "json.number": orange,
+            "json.bool_true": f"italic {orange}",
+            "json.bool_false": f"italic {orange}",
+            "json.null": f"italic {purple}",
+            "json.brace": f"bold {fg}",
+            # repr / pretty-printed objects
+            "repr.str": green,
+            "repr.number": orange,
+            "repr.number_complex": orange,
+            "repr.bool_true": f"italic {orange}",
+            "repr.bool_false": f"italic {orange}",
+            "repr.none": f"italic {purple}",
+            "repr.brace": f"bold {fg}",
+            "repr.comma": fg,
+            "repr.ellipsis": comment,
+            "repr.indent": f"dim {comment}",
+            "repr.tag_start": fg,
+            "repr.tag_name": f"bold {red}",
+            "repr.tag_contents": fg,
+            "repr.tag_end": fg,
+            "repr.attrib_name": yellow,
+            "repr.attrib_equal": cyan,
+            "repr.attrib_value": purple,
+            "repr.call": f"bold {blue}",
+            "repr.url": f"underline {cyan}",
+            "repr.path": cyan,
+            "repr.filename": f"bold {cyan}",
+            "repr.uuid": yellow,
+            "repr.ipv4": green,
+            "repr.ipv6": green,
+            "repr.eui48": green,
+            "repr.eui64": green,
+            "repr.error": f"bold {red}",
+            # misc rich output
+            "table.header": f"bold {blue}",
+            "table.title": f"bold {purple}",
+            "table.caption": f"italic {comment}",
+            "rule.line": comment,
+            "rule.text": blue,
+            "pretty": fg,
+        }
+    )
+
+
+def syntax_theme(theme: Theme) -> SyntaxTheme:
+    """Code-highlighting theme from a rich Theme's ``syntax.*`` styles.
+
+    Styles the theme doesn't define fall back to the default theme's.
+    """
+    fallback = _build(DEFAULT_THEME).styles
+    styles = {
+        name: theme.styles.get(f"syntax.{name}", fallback[f"syntax.{name}"])
+        for name in set(_TOKENS.values())
+    }
+    return ANSISyntaxTheme({token: styles[name] for token, name in _TOKENS.items()})

rich_struct-0.1.0/tests/test_print.py

@@ -0,0 +1,127 @@
+import io
+from array import array
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from typing import get_args
+
+import pytest
+from rich.markdown import Markdown
+from rich.table import Table
+from rich.text import Text
+from rich.theme import Theme
+
+import rich_struct as rt
+from rich_struct import ThemeName
+
+
+def render(fn, *args, **kwargs) -> str:
+    out = io.StringIO()
+    fn(*args, file=out, **kwargs)
+    return out.getvalue()
+
+
+def test_theme_colours_reach_the_output(monkeypatch):
+    monkeypatch.setenv("FORCE_COLOR", "1")
+    monkeypatch.setenv("COLORTERM", "truecolor")
+    keyword = "38;2;187;154;247"  # Tokyo Night purple, #bb9af7
+    assert keyword in render(rt.print_syntax, "def f(): pass", "python")
+    assert keyword in render(rt.print_md, "```python\ndef f(): pass\n```")
+    assert keyword not in render(rt.print_syntax, "def f(): pass", "python", theme="Nord")
+    assert "38;2;122;162;247" in render(rt.print_json, {"a": 1})  # key, blue #7aa2f7
+
+
+@dataclass
+class Point:
+    x: int
+    y: str
+
+
+MD = "## Printing structs\n\nSome `code` and:\n\n```python\nprint('hi')\n```\n"
+
+
+def test_enum_has_11_dark_10_light_and_all_build():
+    assert sum(t.is_dark for t in ThemeName) == 11
+    assert ThemeName.WINTER_IS_COMING.is_dark and not ThemeName.GITHUB_LIGHT.is_dark
+    assert sum(not t.is_dark for t in ThemeName) == 10
+    assert rt.DEFAULT_THEME is ThemeName.TOKYO_NIGHT
+    for t in ThemeName:
+        assert isinstance(t.theme, Theme)
+    assert get_args(rt.ThemeLiteral) == tuple(t.value for t in ThemeName)  # autocomplete list
+
+
+@pytest.mark.parametrize("theme", [*ThemeName, "Dracula", Theme({"syntax.keyword": "red"})])
+def test_every_printer_with_every_theme_kind(theme):
+    assert "Printing structs" in render(rt.print, Markdown(MD), theme=theme)
+    assert "Printing structs" in render(rt.print_md, MD, theme=theme)
+    assert '"a": 1' in render(rt.print_json, {"a": 1}, theme=theme)
+    assert '"a": 1' in render(rt.print_json, '{"a": 1}', theme=theme)
+    assert "a: 1" in render(rt.print_yaml, "a: 1\n", theme=theme)
+    assert "<a>" in render(rt.print_xml, "<a><b/></a>", theme=theme)
+    assert "<b />" in render(rt.print_xml, ET.fromstring("<a><b/></a>"), theme=theme)
+    assert "Point(" in render(rt.print_object, Point(1, "y"), theme=theme)
+    assert "def" in render(rt.print_syntax, "def f(): pass", "python", theme=theme)
+
+
+def test_plain_print_matches_builtin_semantics():
+    assert render(rt.print, "a", "b", sep="-", end="!") == "a-b!"
+
+
+def test_unknown_theme_name_raises():
+    with pytest.raises(ValueError):
+        rt.print("x", theme="Nope")
+
+
+def test_background_fills_full_width(monkeypatch):
+    monkeypatch.setenv("FORCE_COLOR", "1")
+    monkeypatch.setenv("COLORTERM", "truecolor")
+    monkeypatch.setenv("COLUMNS", "40")
+    bg = "48;2;26;27;38"  # Tokyo Night #1a1b26
+    table = Table("col")
+    table.add_row("x")
+    for args in [("hi",), ({"a": 1},), (Markdown(MD),), (table,), ("a", Markdown("b"), 3)]:
+        out = render(rt.print, *args)
+        assert out.strip(), args
+        for line in Text.from_ansi(out).split():
+            assert line.cell_len == 40, (args, line.plain)
+            painted = sum(s.end - s.start for s in line.spans if s.style.bgcolor)
+            assert painted == len(line), (args, line.plain)
+        assert bg in out
+    assert bg not in render(rt.print, "hi", background=False)
+    assert bg not in render(rt.print, "hi", theme=Theme({"syntax.keyword": "red"}))
+
+
+def test_tables_from_lists():
+    out = render(rt.print_table, [{"a": 1, "b": "x"}, {"a": 2.5, "c": None}])
+    assert all(word in out for word in ("a", "b", "c", "2.5", "None", "list · 2 items"))
+    assert "array · 3 items" in render(rt.print_table, array("d", [1.0, 2.0, 0.1 + 0.2]))
+    assert "0.30 " in render(rt.print_table, [0.1 + 0.2, 1.25])  # rounded, decimals aligned
+    grid = render(rt.print_table, [[1, 2], [3]])
+    assert "None" in grid  # ragged rows are padded
+    assert "0 items" in render(rt.print_table, [])
+
+
+def test_long_data_is_clipped_to_head_and_tail():
+    out = render(rt.print_table, list(range(1000)), max_rows=4)
+    labels = [line.split()[1] for line in out.splitlines() if line.startswith("│")]
+    assert labels[1:] == ["0", "1", "…", "998", "999"]
+    wide = render(rt.print_table, [list(range(50))], max_cols=4)
+    assert "…" in wide and " 49 " in wide and " 25 " not in wide
+
+
+def test_numpy_and_pandas_tables():
+    np = pytest.importorskip("numpy")
+    pd = pytest.importorskip("pandas")
+    assert "shape (2, 3) · dtype int64" in render(rt.print_table, np.arange(6).reshape(2, 3))
+    assert "shape (5,)" in render(rt.print_table, np.linspace(0, 1, 5))
+    assert "[1]" in render(rt.print_table, np.zeros((2, 2, 2)))
+    df = pd.DataFrame({"name": ["a", "b"], "x": [1.5, float("nan")], "ok": [True, False]})
+    out = render(rt.print_table, df.set_index("name"))
+    assert all(word in out for word in ("name", "x", "ok", "1.5", "nan", "True", "DataFrame · 2 rows × 2 columns"))
+    assert "Series · dtype float64 · 2 items" in render(rt.print_table, df["x"])
+    big = render(rt.print_table, pd.DataFrame(np.zeros((1000, 100))))
+    assert "1000 rows × 100 columns" in big and len(big.splitlines()) < 30
+    assert max(map(len, big.splitlines())) <= 80 and "0.0…" not in big  # columns dropped to fit
+    # plain print() turns arrays and frames into tables too, but leaves lists alone
+    assert "2 rows × 3 columns" in render(rt.print, df)
+    assert "shape (2,)" in render(rt.print, np.array([1, 2]))
+    assert render(rt.print, [1, 2]) == "[1, 2]\n"