Changelog¶

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

v0.4.3 - 2026-11-06 | Full-width panels¶

Fixed¶

• Panel(expand=True) now really fills the available width. The 0.4.2 fix measured the wrong object, so the enclosing gradient still shrank the panel. The inner Rich panel now reports the full width, so the border and its content share one gradient ramp.

v0.4.2 - 2026-11-06 | Panels and syntax¶

Fixed¶

• Panel(expand=True) now fills the available width. Rich measures a panel at its content width, so the enclosing gradient shrank it and spread the ramp over empty space, making the border look styled apart from its content.
• Syntax keeps the theme's colors for highlighted tokens (keywords, strings, comments, ...) instead of recoloring all code with the gradient; plain code, line numbers and the frame still take the gradient. Pass keep_token_colors=False for the previous all-gradient look.

Changed¶

• Gradient._merge_styles is now an instance method (was a static method) so subclasses can customize style merging.

v0.4.1 - 2026-11-01 | JSON and ProgressBar¶

Added¶

• JSON, a gradient wrapper for rich.json.JSON, including JSON.from_data (accepts Rich's indent, skip_keys, sort_keys, ... options).
• ProgressBar, a gradient-filled variant of Rich's ProgressBar. Only the filled portion takes the gradient; the track and the fill style's background and attributes are untouched. Pulse and indeterminate bars render as Rich does, and Rich's bar state (completed, total, width, styles) is exposed on the wrapper.
• Guide and reference pages for both, plus showcase SVGs.
• trailing_newline option on Gradient (default True); wrappers honor the attribute, including Rule and AnimatedRule.

Fixed¶

• Gradient (and every wrapper built on it) now ends its output with a newline like other Rich renderables, so consecutive console.print calls no longer run together. Pass trailing_newline=False to Gradient (or set the attribute on a wrapper) for the old behavior.
• Gradient expands any iterable of renderables (sets, generators, custom containers), while strings and self-rendering objects stay whole.
• Spectrum palette colors are parsed with the Rich-first parser and fall back to rich-color-ext, so Rich's own color names keep Rich's meaning.
• RICH_GRADIENT_HOME_DIR is honored when locating config.json, and an empty boolean environment value is no longer treated as false.
• An empty Gradient prints the same as an empty Rich Text for any end.

Changed¶

• CI and docs workflows use current GitHub Actions (actions/checkout v7, astral-sh/setup-uv v10.3.3, Pages actions v5/v6), clearing the Node.js 20 deprecation warnings.
• Refreshed locked development dependencies (black, filelock, virtualenv, and others).
• Updated the security contact email in SECURITY.md.
• Confirmed compatibility with Rich 15.0.0; no code changes were required.

v0.4.0 - 2026-10-08 | Gradients that reach the end¶

Breaking¶

• Importing rich_gradient no longer installs Rich's pretty traceback handler (it previously replaced sys.excepthook process-wide as an import side effect). Programs run identically; only uncaught-exception formatting reverts to Python's default unless you opt in.

Migration — either call the new helper once at startup:

import rich_gradient

rich_gradient.install_tracebacks()  # accepts rich.traceback.install kwargs

or set RICH_GRADIENT_TRACEBACKS=1 in the environment to restore the old automatic behavior with no code changes.

Added¶

• A Docs GitHub Actions workflow builds the site with Zensical and deploys it to GitHub Pages on every push to main (or on demand). zensical.toml now sets site_url so canonical links and instant navigation resolve correctly.
• CI now runs the test suite on Python 3.11, 3.12, 3.13, and 3.14 (using uv with the locked dependencies) and has a separate job that builds the docs.
• Docs are now built with Zensical (zensical.toml), using the classic theme variant with the Astral light/dark palettes, Inter and Roboto Mono fonts, and an animated rainbow accent (header title, links, active navigation, and heading underline). It respects prefers-reduced-motion.
• Guide pages for Table, Tree, Columns, Pretty, and Syntax (docs/table.md, tree.md, columns.md, pretty.md, syntax.md), each with runnable examples and a link to its reference page. They appear under the User Guide.
• examples/renderables_that_work.py renders every rich-gradient renderable, reports which ones work, and saves a compact summary table to docs/img/renderables-that-work.svg. It replaces gradient-table.svg in the Gradient docs.
• Test coverage for color parsing precedence (tests/test_color_parsing.py), the hues minimum across every renderable (tests/test_hues.py), the derived repeat_scale (tests/test_repeat_scale.py), configuration loading and validation (tests/test_config.py), empty Gradient output, and Gradient accepting tuples and generators of renderables.

Changed¶

• The documentation moved from MkDocs to Zensical. mkdocs.yml is gone; configuration lives in zensical.toml. Use uv run zensical serve to preview and uv run zensical build --clean to build (replacing uv run mkdocs serve and uv run mkdocs build). The mkdocs and mkdocs-material dev dependencies were removed; mkdocstrings is still used for the API reference. CLAUDE.md, the Copilot instructions, and .readthedocs.yaml were updated to match.

• Color strings are now parsed with Rich's own parser first, falling back to rich-color-ext (CSS names and 3-digit hex) only when Rich rejects them. Names Rich defines keep Rich's meaning, so "red" is ANSI red (#800000) rather than CSS red (#ff0000); use "#ff0000" for pure red. CSS-only names such as "tomato" are unaffected. Requires rich-color-ext>=3.0.0.

• hues now has a minimum of 2 everywhere. Gradient (and the renderables built on it) previously clamped smaller values up to 2 silently, and Text only rejected them when it had to auto-generate colors. All of them now raise ValueError for hues < 2, matching Spectrum.

• Configuration loading is stricter and quieter. Invalid animate values, uncolorable palette entries, and malformed config files are ignored with a logged warning instead of raising later (or, for RICH_GRADIENT_ANIMATE, silently disabling animation on a typo). Accepted RICH_GRADIENT_ANIMATE values now include 0, false, no, and off. ~ in RICH_GRADIENT_HOME_DIR is expanded.

• The default palette entry hotpink (#FF00AA) is now named pink, matching the fallback palette in spectrum.py. If your config file overrides hotpink, rename the key to pink; otherwise both entries are kept and the palette grows to 18 colors.

• rich-color-ext>=3.0.0 is now required, and zensical joins the dev dependencies.

• The docs stylesheets were cleaned up: a stray body { background: #000 }, unrelated button-animation rules, and dark-only table rules that applied in light mode were removed, and code blocks now use the theme's code colors.

• Corrected stale docstrings and documentation: vertical_justify accepts "middle" (not "center"), Text background colors use bg_colors (docs previously said bgcolors), and default values in Panel / AnimatedGradient docstrings now match their signatures.

Fixed¶

• Gradients now reach their first and last colors. repeat_scale defaults to None and is derived from the color stops (1.0 for two colors, 2.0 for three or more, with a background gradient mirrored to share the same period). Previously Gradient defaulted to 2.0, which stopped halfway through a two-color gradient, and Markdown defaulted to 4.0, which only reached the second color. This changes the look of existing Gradient, Panel, Rule, Markdown, Table, Tree, Columns, Pretty, and Syntax output; pass an explicit repeat_scale to keep the old spread. The animated renderables keep their explicit defaults.
• Gradient now accepts a tuple or generator of renderables, as documented, instead of raising NotRenderableError. Lists, tuples, and iterators are treated as several renderables; strings and single renderables (including rich.text.Text) stay whole. AnimatedGradient no longer replaces an empty renderable with an empty list via a truthiness check.
• Gradient("") (and any Gradient made only of empty text) now prints a blank line, exactly like console.print(""), instead of printing nothing. A Gradient with no renderables at all still prints nothing, like an empty Rich Group.

• Rule only converts genuine color errors (ColorParseError, TypeError) into ValueError, with the message Invalid color for Rule: .... Other errors, such as an invalid hues, now propagate with their own message instead of being reported as "Invalid color provided".

• Now requires rich-color-ext>=3.0.0. _color_ext.py imports get_css_map, install and is_installed directly and drops the compatibility fallbacks and the sys.excepthook snapshot/restore that only older releases needed.

• The duplicated "install if needed" checks in __init__, config and spectrum are replaced by a single ensure_installed() helper.
• Color parsing is now Rich-first, matching rich-color-ext 3.0: Rich's own parser runs first and CSS names / 3-digit hex are only tried when Rich rejects the input. Names that Rich also defines now resolve to Rich's ANSI palette instead of the CSS value, for gradient colors and Style strings alike (red is #800000, not #ff0000). Ten names are affected: red, blue, yellow, cyan, magenta, white, purple, violet, orchid and tan; use a hex code (e.g. #ff0000) for the exact CSS value. A bare abc (no #) is no longer accepted as hex.

Fixed¶

• Gradient color stops (Text, Gradient, Spectrum) are resolved through parse_color(), which tries Rich first and then falls back to CSS names and #abc hex itself. CSS names such as tomato therefore keep working if the patch was removed with rich_color_ext.uninstall(), instead of raising ColorParseError.

• get_logger(enabled=True) no longer calls loguru.logger.remove(), which destroyed every handler the host application had configured. It now tracks and removes only its own sinks, filters them to rich_gradient records so application logs cannot leak in, and defaults its log directory to ~/.rich-gradient/logs instead of creating ./logs in the current working directory.

• Panel no longer crashes when style is passed as a rich.style.Style instance instead of a string.
• Rule accepts being constructed with no title (Rule()), matching AnimatedRule and Rich's own Rule.
• AnimatedRule now uses its faster phase speed when animation is enabled via the global config, not only when animate=True is passed explicitly.
• Rule reports an accurate error message for out-of-range thickness values.
• Removed the unused requests runtime dependency.

v0.3.15 - 2026-08-21 | Documentation refresh¶

Changed¶

• Refreshed the README and the docs landing page, and updated the bundled images.

v0.3.14 - 2026-08-21 | Rich 15¶

Changed¶

• Raised the minimum Rich version to rich>=15.0.0.
• Added a type annotation to theme.__all__.

v0.3.13 - 2026-06-02 | Renderables, ramp caching, and animation fixes¶

Added¶

• Add an internal typed GradientRamp helper that precomputes foreground and background Style objects for each render span.
• Add benchmark coverage for static gradient rendering, animated frame rendering, long text rendering, and gradient panel rendering.
• Add convenience wrappers for Rich Table, Tree, Columns, Pretty, and Syntax, including package exports, reference docs, tests, and direct module demos.

Changed¶

• Route Gradient._get_style_at_position() through the cached ramp so repeated cell lookups reuse precomputed styles instead of rebuilding styles per character cluster.
• Alias direct Rich table imports as RichTable internally and in examples so rich_gradient.Table can be the package-level table wrapper.

Fixed¶

• Clean up AnimatedGradient running state when a duration-limited animation expires, allowing the same instance to restart.
• Allow AnimatedPanel regex highlights to use two-item tuples (pattern, style) with default flags, matching Gradient highlight parsing.

v0.3.12 - 2026-05-10 | Refactor rule gradient rendering and remove bundled CLI¶

• Share the cell-aware styled segment renderer across Gradient, Rule, and AnimatedRule
• Fix Rule and AnimatedRule empty-renderable fallbacks and thickness handling
• Accept RGB tuple color stops and validate tuple channel bounds
• Make AnimatedGradient refresh-rate validation explicit and allow restart after stop
• Move CLI docs toward rich-gradient-cli and remove the packaged console script
• Add/update tests and documentation for rendering, animation, colors, and rules

v0.3.11 - 2026-02-10 | Highlight configs, CLI refactor, Gradient/Rule fixes¶

Added / Changed¶

• Added explicit highlight configuration helpers (HighlightWords, HighlightRegex) and updated Gradient to accept the new highlight inputs.
• Refactored CLI command structure and removed deprecated CLI command modules/files.
• Improved documentation and examples to cover the new highlighting workflow.
• Added GradientTheme tests and tightened gradient test coverage (including single background color handling).
• See rich-gradient-cli for the new CLI implementation.

Fixed¶

• Improved Gradient color parsing and handling of highlight inputs.
• Corrected Rule thickness/character mapping behavior.
• Streamlined Text background color parsing and ensured theme initialization is consistent.

v0.3.10 - 2026-01-04 | AnimatedText, CLI defaults, Live persistence¶

Added / Changed¶

• Added AnimatedText for live gradient rich.text.Text, plus update_text helpers, package export, reference docs, and an example script.
• AnimatedGradient family (AnimatedGradient, AnimatedPanel, AnimatedMarkdown, AnimatedRule) no longer clears the console on stop; unless transient=True, the final gradient render persists.
• CLI defaults to the print command when no subcommand is provided and can read input from stdin.

• For example:

  echo "Hello, World!" | rich-gradient

• Docs refreshed to note the behavior.

• Animation/text guides and the mkdocs navigation now include AnimatedText coverage.
• Added tests for AnimatedText behavior and CLI default/stdin handling.

Fixed¶

• Silenced rich-color-ext get_css_map type checker mismatch for older releases.

v0.3.9 - 2025-12-15 | CLI doc refresh, import/test stability, CSS fix¶

Added / Changed¶

• CLI docs and README now describe the Click + rich-click subcommands (print, panel, rule, markdown) with current options and examples; removed stale Typer references.
• CLI option help text across commands uses the rich markup formatting introduced in text_command.py for consistent help output.
• Contributor note documents that pytest runs without an editable install because tests/conftest.py adds src/ to sys.path.
• Documentation CSS now anchors html, body to the theme background to avoid a black flash/transparent top before styles load.

Fixed¶

• Test collection no longer fails with ModuleNotFoundError: rich_gradient when the package isn't installed editable, thanks to the path shim in tests/conftest.py.

v0.3.7 - 2025-10-24 | Documentation refresh, reproducible assets & CLI polish¶

Added¶

• Docs
  • New user-guide pages for panels, the CLI, and animation (docs/panel.md, docs/cli.md, docs/animation.md) linked from the main navigation.
  • API reference stubs for AnimatedPanel and Panel via mkdocstrings.
  • Hero quick-start, palette, background, panel, rule, spectrum, and CLI images generated from checked-in example scripts.
• Examples
  • Added reproducible scripts under examples/ to render all user-guide screenshots, including quick-start Text, palette variations, background gradients, gradient/table showcases, panel gallery, rule gallery, spectrum table, CLI help, and updated hello_world.py.

Changed¶

• Docs
  • Rewrote the landing page plus Text, Gradient, Rule, and Spectrum guides for clearer positioning and accurate option coverage.
  • Updated index code snippets to import Text from the package root and refreshed installation guidance.
  • Refined docs/animated_gradient_ref.md to point at the public module path.
  • Regenerated SVG/GIF assets with consistent naming (e.g., hello_world.svg, text-quickstart.svg, gradient-panel.svg, cli-help.svg) and removed legacy images.
• Library
  • Exported Text from rich_gradient/__init__.py so examples, docs, and the CLI can rely on the top-level import.
• Tooling
  • Expanded mkdocs.yml navigation to surface the new pages and verified the build with uv run mkdocs build.

Removed¶

• Docs
  • Dropped the obsolete base_gradient_ref.md page and deprecated image assets that the refreshed guides no longer reference.

v0.3.6 - 2025-09-10 | Consolidated Gradient, RNG fix, gamma-correct Text, docs/tests¶

Added / Changed¶

• Gradient
  • Consolidated to a single public factory (rich_gradient.gradient.Gradient) that returns BaseGradient or AnimatedGradient internally.
  • Kept test helper methods by adding equivalents to BaseGradient (_color_at, _styled, _interpolated_color) and _active_stops initialization.
  • Added background= support to BaseGradient/AnimatedGradient for parity with previous API.
• Text
  • Interpolates colors with gamma-correct blending for visual consistency with Gradient.
• Spectrum
  • Uses a dedicated random.Random(seed) instance to avoid mutating global RNG state; behavior is deterministic per seed without side effects.
• Rule
  • Normalized invalid color errors to ValueError for consistency.
• Package Init
  • Centralized rich-color-ext install to package init; removed duplicate installs from other modules.
• Repo Hygiene
  • Removed committed build artifacts (dist/) and static site (site/) from source; they remain in .gitignore.
• Docs / Examples / Tests
  • README basic example fixed (missing parenthesis).
  • Benchmark test now measures actual console printing safely.
• CLI
  • Relaxed --justify and --overflow option annotations from Literal[...] to str with explicit validation for broader Typer/Click compatibility.
  • Pinned dependencies to stabilize CLI behavior: typer>=0.12.5,<0.13 and click>=8.1.7,<9.0.0.
• Tests
  • Made CLI tests portable across Click/Typer versions by removing mix_stderr usage and accepting warnings from stdout or stderr.
• Cleanup
  • Removed duplicate internal Gradient factory leftover in _animated_gradient.py; the public factory now lives in rich_gradient/gradient.py.
• Docs
  • Added _base_gradient_ref.md for referencing BaseGradient
  • Added _animated_gradient_ref.md for referencing AnimatedGradient

Fixed¶

• Eliminated duplicate Gradient implementations that could drift out of sync.
• Avoided global RNG seeding in Spectrum that could affect host applications.

v0.3.4 - 2025-09-03 | Text.as_rich(), background gradients, spectrum + docs¶

v0.3.4 Added¶

• Text
• .as_rich() method to return a plain rich.text.Text with all spans/styles preserved.
• .rich convenience property wrapping as_rich().
• Background gradients via bgcolors=; multiple bg stops interpolate alongside foreground.
• Robust color normalization supporting Color, ColorTriplet, (r,g,b) tuples, CSS names, 3/6‑digit hex, and rgb() strings.
• Spectrum
• Deterministic seed, color names, styles, hex accessors, and a rich preview table renderable.
• Docs/Examples
• New SVG/PNG assets for gradient text examples under docs/img/v0.3.4/ and updated spectrum preview.

v0.3.4 Updated¶

• Text
• Improved error types/messages and comprehensive module documentation.
• Single‑color fast‑path applies one composed Style across content for performance.
• Empty text rendering no longer emits a trailing newline/segment; nested renderables filtered accordingly.
• Gradient and BaseGradient
• Gamma‑corrected color interpolation, smoother stop wrapping, explicit alignment validation, and safer measurement when no renderables.
• Support for repeat_scale/phase used by animated variants.
• Rule
• Accepts colors as strings, Color, ColorTriplet, or RGB tuples with clearer validation and messages.
• Title style applied after gradient generation for accurate highlighting.
• Package Init / Theme
• Install rich-color-ext on import and monkey‑patch Console._collect_renderables to suppress empty Text trailing newline.
• Theme helpers for consistent docs SVG generation (GRADIENT_TERMINAL_THEME).
• README/Docs
• Expanded examples and color‑format visuals; refreshed links and images.

v0.3.4 Fixed¶

• Suppressed stray newline output when rendering empty gradient Text (affects console capture/recorded SVGs).

v0.3.3 - 2025-08-27 | Added tests and Fixed Bugs¶

v0.3.3 Updated¶

• Enhanced rendering and color handling in gradient components
• Refactored rich-gradient for improved structure and functionality
• Reorganized imports in __init__.py for clarity.
• Updated AnimatedGradient to ensure color extension is installed at package import time.
• Enhanced BaseGradient to improve gradient wrapping logic and error handling.
• Improved logger utility with better error handling and configuration options.
• Adjusted Gradient class to ensure quit panel behavior is consistent and intuitive.
• Added comprehensive tests for edge cases in Gradient and Text classes, including long text, unicode handling, and color validation.
• Enhanced Spectrum class to support color generation with optional seed for reproducibility.
• Improved Text class to ensure proper initialization and color parsing.
• Updated test suites for Gradient and Spectrum to cover additional scenarios and edge cases.

v0.3.2 Added tests and Fixed Bugs¶

v0.3.2 Removed¶

• Dev Dependencies
• snoop
• cheap-repr

v0.3.2 Updated¶

• Removed instances that were imported from:
• snoop
  • @snoop()
• cheap-repr
  • register_repr(f"{class})(normal_repr)
• Renamed GradientRule -> Rule
• to match the naming of the other modules in rich-gradient

v0.3.2 Added¶

• Tests
• tests/benchmark_perf.py: To benchmark the performance of generating gradients that span large amounts of characters.
• tests/test_edge_cases.py: To cover edge cases that may otherwise break rich-gradient.

v0.3.0 - 2025-06-20 | Working Rewrite¶

v0.3.0 Added¶

• Validated working and added tests for:
• rich_gradient.text.Text
• rich_gradient.gradient.Gradient
• rich_gradient.rule.GradientRule
• rich_gradient.spectrum.Spectrum
• rich-color-ext acting as adequate replacement for previous color logic
• Added examples directory containing:
• animated_gradient_example.py
• gradient_example.py
• hello_world.py
• rainbow_gradient.py
• specific_color_gradient.py
• text_markup.py
• two_color_gradients.py
• Generated updated exports for examples for documentation (still in the works)

v0.3.0 Updated¶

• docs/index.md

v0.3.0 TODO¶

• Update Documentation
• Expand Tests
• Work on Gradient Panel and Table Renderables

v0.3.0 Removed¶

Removed all of the the archived modules from rich_gradient/archive/*

v0.2.1 Rewrite¶

There was a lot of overhead in rich-gradient so I rewrote it from the ground up with an actual goal. I created rich-color-ext to wrap around rich's color parsing removing the need for the_rgb.py, color.py, color_data.py, _colors.py, and all of their tests.

v0.2.0 - 2025-3-13 | uv, pure python, and 3.13.2¶

There are a number of significant changes in v0.2.0:

rye → uv¶

Astral has done a hell of a job making python dev tools. ruff blew the existing python linters out of the water and uv pretty much did the same thing to package managers. Rich-gradient was started on rye but as Astral has since depreciated it, it's moved to their current rust powered python package manager, uv.

Pure Python¶

Rich-gradient is now a pure-python package. This allows it to be more easily used regardless of platform. As rich-gradient previously had pydantic as a dependency, it now just borrows the logic from pydantic-extra-types.color.

3.13.2¶

After switching to uv, the package has been updated to python 3.13.2.

v0.2.0 Updated¶

• Switched rich-gradient package manager from astral/rye to astral/uv
• Updated python to 3.13.2

v0.2.0 Changed¶

• Removed pydantic and pydantic-extra-types dependencies.
• Updated the names of some of the colors. For example greenyellow became lawngreen.
• Updated README.md, CHANGELOG, and documentation.

v0.2.0 Added¶

• src/rich_gradient/_base_color.py: stores the color logic from pydantic-extra-types.color modules stripped of the pydantic framework.

v0.1.7 - 2024-7-16 | Added support for Two-Color Gradients¶

v0.1.7 Updated¶

• Updated Gradient.generate_subgradients() to default to returning a list containing a single simple gradient to allow Gradients to work when only supplied with two colors.

v0.1.7 Added¶

• Added len, int, str, and repr dunder methods to rich-gradient.gradient.Gradient (will simply refer to as Gradient from here on out).
• Added a tests/test_gradient.py for Gradient to test two color gradiets

v0.1.6 - 2024-6-28 | Updated Rev¶

• Updated rev to 0.1.6.

v0.1.5 - 2024-6-28 | Added Tests¶

v0.1.5 Updated¶

• Updated requirements for minimum versions of python from 3.8 -> 3.10.
• Added pytest to dev-dependencies.

v0.1.5 Added¶

• Tests for:
• Color
• Spectrum
• SimpleGradient

v0.1.4 | 2024-6-28 | Resolved Dependencies¶

v0.1.4 Updated¶

• This release is primarily to prune unnecessary dependencies.
• Removed numpy to avoid issues of numpy version 2.0.0 conflicting with torch.

v0.1.3 - 2021-10-10¶

v0.1.3 Fixed¶

• Updated README to use GitHub pages for example gradient image.

v0.1.2 - 2021-10-10¶

v0.1.2 Updated¶

• Updated PyProject.toml description.
• Moved MKDocs and related dependencies to dev-dependencies.

v0.1.2 Fixed¶

• Updated README to use GitHub pages for banner image.
• Updated README to use GitHub pages for docs url.

v0.1.1 - 2021-10-10¶

v0.1.1 Fixed¶

• Updated README to use GitHub pages for images.

v0.1.0 - 2021-10-10¶

Initial release. Based off of MaxGradient with a simplified color model based on pydantic-extra-types.color.Color. Re-released as rich-gradient to avoid confusion with MaxGradient.