From b5909d6c39c5c4268ebc0d9bcce7e4b2de002b30 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Thu, 15 Oct 2026 16:25:30 +1000 Subject: [PATCH] docs(llms): add "when to use it" and recipes, link llms.txt from PyPI Agents choosing between packages need to know what this one is for and what it is not for, and users phrase problems as tasks, not API names. llms_intro.md gains a "When to use it" section (including what it is not for) and a "Recipes" section of task-phrased one-liners, each checked against the current code. pyproject.toml gains a project URL for llms.txt so it is discoverable from the PyPI page. Co-Authored-By: Claude Sonnet 5.5 --- docs/llms_intro.md | 15 +++++++++++++++ pyproject.toml | 1 + 2 files changed, 16 insertions(+) diff --git a/docs/llms_intro.md b/docs/llms_intro.md index 80da9b2..0097e5d 100644 --- a/docs/llms_intro.md +++ b/docs/llms_intro.md @@ -1,5 +1,11 @@ ansitable prints tabular data and NumPy matrices in a terminal with optional Unicode borders and ANSI color, and exports the same table to Markdown, HTML, LaTeX, reStructuredText, wikitable, CSV and Pandas. It is a small, pure-Python package (one module, `ansitable.table`) whose only dependency is the `colored` package, which provides the color names. It requires Python 3.9 or later. Install with `pip install ansitable`. +## When to use it + +Reach for ansitable when a program needs to show **rows of values or a NumPy matrix as a neat table in a terminal**, optionally with color and box-drawing borders, and especially when the *same* table must also go into a document (Markdown, LaTeX, HTML, reStructuredText, wikitable, CSV) or a Pandas DataFrame. It is small and has one dependency, `colored`, which is optional for output without color. + +It is not a general terminal UI toolkit (use `rich` or `textual` for live layouts, progress bars, panels), and it is not a data-wrangling library (use Pandas). It is a good fit when you want a plain, dependable table with a few lines of code. + ## Quick start ```python @@ -17,6 +23,15 @@ table.sort("Score", key=float, reverse=True) # in place; returns the tabl table.print() # to a terminal, or table.print(file=f) ``` +## Recipes + +- **Print a table of results**: `t = ANSITable("name", "value", border="thin")`, then `t.row("a", 1.5)` for each row, then `t.print()`. +- **Show a NumPy matrix neatly**: `ANSIMatrix().print(A)`, or `str_ = ANSIMatrix(fmt="{:8.3f}").str(A)` for a string. +- **Show a Pandas DataFrame as a table**: `ANSITable.Pandas(df).print()`. +- **Put the same table in a Markdown or LaTeX document**: `t.markdown()`, `t.latex()`, or `t.export(file="results.md")`, which picks the format from the file extension. +- **Turn color and Unicode off for log files**: `ansitable.options(use_unicode=False, color=False)`. +- **Color one row or cell**: `t.row(..., fgcolor="red")`, or wrap a value in `Cell("text", fgcolor="red")`. + ## Key points - **Creating a table.** `ANSITable("a", "b", "c")` makes columns from strings (right-aligned, formatted with `"{}"`). Pass `Column(name, fmt=..., width=..., colcolor=..., colalign=..., headstyle=...)` objects instead for formatting and styling, or call `table.addcolumn(name, **kwargs)`. An alignment marker at the start of a column name, such as `"{<}Name"`, `"{^}Name"`, sets alignment in the string form. diff --git a/pyproject.toml b/pyproject.toml index dd88851..a47c09d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,7 @@ dependencies = ["colored"] "Homepage" = "https://github.com/petercorke/ansitable" "Bug Tracker" = "https://github.com/petercorke/ansitable/issues" "Documentation" = "https://petercorke.github.io/ansitable" +"llms.txt" = "https://petercorke.github.io/ansitable/llms.txt" "Source" = "https://github.com/petercorke/ansitable" [project.optional-dependencies]