{"id":15489404,"url":"https://github.com/apparebit/prettypretty","last_synced_at":"2025-03-22T15:27:38.075Z","repository":{"id":238387122,"uuid":"796446264","full_name":"apparebit/prettypretty","owner":"apparebit","description":"Hello pretty-pretty, awesome terminal colors you have there!","archived":false,"fork":false,"pushed_at":"2024-05-22T17:49:33.000Z","size":2532,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-22T23:08:44.766Z","etag":null,"topics":["ansi-colors","ansi-escape-codes","apca-w3","color-contrast","color-distance","terminal","tty"],"latest_commit_sha":null,"homepage":"https://apparebit.github.io/prettypretty/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apparebit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-06T00:13:19.000Z","updated_at":"2024-05-28T03:11:04.078Z","dependencies_parsed_at":"2024-05-10T09:35:57.641Z","dependency_job_id":"a46c721b-940d-4b7b-8bd6-ca8356ecdb14","html_url":"https://github.com/apparebit/prettypretty","commit_stats":null,"previous_names":["apparebit/pitty","apparebit/prettypretty"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apparebit%2Fprettypretty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apparebit%2Fprettypretty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apparebit%2Fprettypretty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apparebit%2Fprettypretty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apparebit","download_url":"https://codeload.github.com/apparebit/prettypretty/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244976863,"owners_count":20541556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi-colors","ansi-escape-codes","apca-w3","color-contrast","color-distance","terminal","tty"],"created_at":"2024-10-02T07:05:31.504Z","updated_at":"2025-03-22T15:27:38.069Z","avatar_url":"https://github.com/apparebit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pretty 🌸 Terminals\n\n[![Run Tests, Build Wheels, \u0026 Publish to PyPI](https://github.com/apparebit/prettypretty/actions/workflows/ci.yml/badge.svg)](https://github.com/apparebit/prettypretty/actions/workflows/ci.yml)\n[![Publish to GitHub Pages](https://github.com/apparebit/prettypretty/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/apparebit/prettypretty/actions/workflows/gh-pages.yml)\n\n## Pretty 🌸 Tty\n\n\\[  [**Docs.rs**](https://docs.rs/prettytty/latest/prettytty/)\n| [**GitHub Pages**](https://apparebit.github.io/prettypretty/prettytty/)\n| [**Rust Crate**](https://crates.io/crates/prettytty)\n| [**Repository**](https://github.com/apparebit/prettypretty)\n\\]\n\nPrettytty is a **lightweight and flexible terminal library** for Rust that has\nonly one low-level dependency, i.e., [`libc`](https://crates.io/crates/libc) on\nUnix and [`windows-sys`](https://crates.io/crates/windows-sys) on Windows. Its\nAPI is clean and simple: Open a [`Connection`] to the terminal and share it\nacross threads as needed. Write [`Command`]s to [`Output`]. Read [`Query`]\nresponses from [`Input`]. [`Scan::read_token`] takes care of low-level UTF-8 and\nANSI escape sequence decoding and [`Query::parse`] turns token payloads into\nobjects. A [`cmd`] library with 70+ built-in commands covers basic needs and\nthen some.\n\n\n[`cmd`]: https://apparebit.github.io/prettypretty/prettytty/cmd/index.html\n[`Command`]: https://apparebit.github.io/prettypretty/prettytty/trait.Command.html\n[`Connection`]: https://apparebit.github.io/prettypretty/prettytty/struct.Connection.html\n[`Input`]: https://apparebit.github.io/prettypretty/prettytty/struct.Input.html\n[`Output`]: https://apparebit.github.io/prettypretty/prettytty/struct.Output.html\n[`Query`]: https://apparebit.github.io/prettypretty/prettytty/trait.Query.html\n[`Query::parse`]: https://apparebit.github.io/prettypretty/prettytty/trait.Query.html#method.parse\n[`Scan`]: https://apparebit.github.io/prettypretty/prettytty/trait.Scan.html\n[`Scan::read_token`]: https://apparebit.github.io/prettypretty/prettytty/trait.Scan.html#method.read_token\n\n----\n\n\n## Pretty 🌸 Pretty:\n\n\\[  [**Docs.rs**](https://docs.rs/prettypretty/latest/prettypretty/)\n| [**GitHub Pages**](https://apparebit.github.io/prettypretty/prettypretty/)\n| [**Rust Crate**](https://crates.io/crates/prettypretty)\n| [**Python Package**](https://pypi.org/project/prettypretty/)\n| [**Repository**](https://github.com/apparebit/prettypretty)\n\\]\n\n🎖️ As featured on [Real Python #211](https://realpython.com/podcasts/rpp/211/)\n\n🎖️ Inspired [iTerm2's color preferences](https://raw.githubusercontent.com/apparebit/prettypretty/main/docs/figures/iterm2-color-preferences.jpg)\n\nPrettypretty is a Rust library with optional Python bindings that applies\n**2020s color science to 1970s terminals** to facilitate scalable user\ninterfaces. However, instead of progressive enhancement, it primarily relies on\ngraceful degradation from high-resolution colors down to more limited terminal\ncolors.\n\nThe **three steps for better terminal styles** are:\n\n 1. Fluently declare high-resolution styles.\n 2. Let prettypretty adjust styles to terminal capabilities and user preferences at\n    program startup.\n 3. Use adjusted styles at will.\n\nPrettypretty seamlessly integrates with\n[prettytty](https://crates.io/crates/prettytty) for **querying the terminal for\nits current color theme**. It then uses said color theme to produce more\naccurate results when converting high resultion colors down to 256 or 16\nterminal colors. The integration also is entirely optional, controlled by the\n`tty` feature, and fairly small, requiring about 80 lines of code for\n[`Theme::query`](https://apparebit.github.io/prettypretty/prettypretty/theme/struct.Theme.html#method.query).\nHence integration with another terminal library should be easy enough.\n\nAs far as colors are concerned, prettypretty comes with all the expressivity and\nconvenience of **high-resolution, floating point colors and [color\nspaces](https://lab.ardov.me/spaces-3d)**, including the perceptually uniform\n[Oklab](https://bottosson.github.io/posts/oklab/), whether in Cartesian or polar\nform, with original or [revised\nlightness](https://bottosson.github.io/posts/colorpicker/#intermission---a-new-lightness-estimate-for-oklab).\nIt further implements state-of-the-art algorithms for\n[gamut-mapping](https://www.w3.org/TR/css-color-4/#gamut-mapping), [color\ninterpolation](https://www.w3.org/TR/css-color-4/#interpolation), [perceptual\ncontrast](https://github.com/Myndex/apca-w3), as well as its own hue- and\nlightness-based downsampling for optimal selection of ANSI colors.\n\n\n## Python Integration\n\nThe optional Python integration is enabled with the `pyffi` feature flag and\nrelies on [PyO3](https://pyo3.rs/v0.22.0/) and [Maturin](https://www.maturin.rs)\nfor building an extension module with the same functionality. Only where the\nRust library uses trait implementations, the Python module [uses dedicated\nmethods](https://github.com/apparebit/prettypretty/blob/main/prettypretty/color/__init__.pyi).\nWhile prettytty takes care of terminal access for Rust, the Python version of\nprettypretty has its own terminal abstraction, with its own Pythonic interface.\n\n\n## Scripts Using Prettypretty\n\nBesides the [documentation](https://apparebit.github.io/prettypretty/), a good\nstarting point for familiarizing yourself with prettypretty are the scripts:\n\n  * [prettypretty.progress](https://github.com/apparebit/prettypretty/blob/main/prettypretty/progress.py)\n    illustrates the library's use on the example of a progress bar in less than\n    100 lines of Python. The finished progress bar is shown below for both light\n    and dark themes.\n\n    \u003cimg src=\"https://raw.githubusercontent.com/apparebit/prettypretty/main/docs/figures/progress-bar-light.png\"\n         alt=\"a complete, green progress bar under light mode\" width=293\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/apparebit/prettypretty/main/docs/figures/progress-bar-dark.png\"\n         alt=\"a complete, green progress bar under dark mode\" width=298\u003e\n\n  * [prettypretty.plot](https://github.com/apparebit/prettypretty/blob/main/prettypretty/plot.py)\n    charts colors on the chroma/hue plane of Oklab, if you don't feed it colors\n    defaulting to your terminal's current color scheme. Here's the one for the\n    basic theme in Apple's Terminal.app:\n\n    \u003cimg src=\"https://raw.githubusercontent.com/apparebit/prettypretty/main/docs/src/deepdive/colortheme/terminal.app-colors.svg\"\n         alt=\"colors from the basic theme for Apple's Terminal.app in Oklch\" width=300px\u003e\n\n  * [prettypretty.grid](https://github.com/apparebit/prettypretty/blob/main/prettypretty/grid.py)\n    visualizes perceptual contrast and color downsampling strategies,\n    exhaustively for the 6x6x6 RGB cube embedded in 8-bit color and selectively\n    for 32x32 slices through the much bigger 24-bit RGB cube.\n\n    \u003cimg src=\"https://raw.githubusercontent.com/apparebit/prettypretty/main/docs/figures/rgb6-background.png\"\n         alt=\"a grid visualizing the 6x6x6 embedded RGB cube\" width=300px\u003e\n\n  * [prettypretty.viz3d](https://github.com/apparebit/prettypretty/blob/main/prettypretty/viz3d.py)\n    traces the boundaries of the *visual gamut* in 3D and saves the\n    corresponding point cloud or mesh in [PLY\n    format](https://en.wikipedia.org/wiki/PLY_(file_format)). The screenshot\n    below shows [Vedo](https://vedo.embl.es)'s rendering.\n\n    \u003cimg src=\"https://raw.githubusercontent.com/apparebit/prettypretty/main/docs/figures/visual-gamut.jpg\"\n         alt=\"a 3D visualization of the gamut for visible light,\n              somewhat shaped like a fat, squat hot pocket\" width=300px\u003e\n\n\n## Acknowledgements\n\nI wrote much of prettypretty over a two-month period in 2024. Twice. I first\nimplemented the core color routines in Python and then I did so again in Rust.\nAt this point, only the Rust version survives. But Python remains a tier-1\nruntime target for prettypretty. Two things really helped with getting this\nproject started. First, I had been toying with different approaches to terminal\nstyles for a while and knew what I was looking for. Second, I benefitted\ntremendously from [Lea Verou](http://lea.verou.me/)'s and [Chris\nLilley](https://svgees.us/)'s work on the [Color.js](https://colorjs.io) library\nand [CSS Color 4](https://www.w3.org/TR/css-color-4/) specification.\nPrettypretty directly reuses Color.js' formulae for conversion between color\nspaces and implements several CSS Color 4 algorithms.\n\n---\n\nCopyright 2024-2025 Robert Grimm. The code in this repository has been released\nas open source under the [Apache\n2.0](https://github.com/apparebit/prettypretty/blob/main/LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapparebit%2Fprettypretty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapparebit%2Fprettypretty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapparebit%2Fprettypretty/lists"}