{"id":22643228,"url":"https://github.com/dranjan/python-colordemo","last_synced_at":"2025-07-06T23:39:44.165Z","repository":{"id":5176082,"uuid":"6349869","full_name":"dranjan/python-colordemo","owner":"dranjan","description":"Python module implementing RGB queries on xterm-like terminals","archived":false,"fork":false,"pushed_at":"2023-08-30T09:52:47.000Z","size":170,"stargazers_count":17,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T15:12:26.217Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ckan/ckan","license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dranjan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-10-23T09:29:46.000Z","updated_at":"2025-01-12T15:11:29.000Z","dependencies_parsed_at":"2022-07-06T05:30:32.334Z","dependency_job_id":null,"html_url":"https://github.com/dranjan/python-colordemo","commit_stats":null,"previous_names":["dranjan/python-colordemo"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dranjan%2Fpython-colordemo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dranjan%2Fpython-colordemo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dranjan%2Fpython-colordemo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dranjan%2Fpython-colordemo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dranjan","download_url":"https://codeload.github.com/dranjan/python-colordemo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248493487,"owners_count":21113269,"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":[],"created_at":"2024-12-09T05:09:44.058Z","updated_at":"2025-04-11T23:23:17.271Z","avatar_url":"https://github.com/dranjan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `colordemo`\n\n`colordemo` is a Python package implementing RGB queries on xterm-like\nterminals.  It includes a demo script for presenting terminal color\nschemes, complete with RGB hex codes.\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/dranjan/python-colordemo/master/examples/colordemo-example.png\"\u003e\n\u003c/div\u003e\n\n## Quick start\n\nThere are many ways to run the demo script, and we will briefly describe\nthem here. Note that with any of the methods below, the `colordemo`\ntool can accept command-line options. To see which options are available,\nuse `--help` with any of the methods, e.g.,\n\n    pipx run colordemo --help\n\n### Using `pipx`\n\nWith only an active internet connection and the `pipx` Python utility,\nthe script can be run directly without installation:\n\n    pipx run colordemo\n\nAlternatively, it can also be installed explicitly and run that way:\n\n    pipx install colordemo\n    colordemo\n\n### Using `pip`\n\nThe package can also be installed and run as a normal Python package\nusing `pip` (preferably in a `virtualenv` environment):\n\n    pip install colordemo\n    colordemo\n\n    # Equivalent\n    python -m colordemo\n\n### From the source tree\n\nFinally, the script can be run easily from the source tree directly.\nThis package has no dependencies besides Python, so no actions are\nneeded besides cloning the repository.\n\n    git clone 'git@github.com:dranjan/python-colordemo.git'\n    cd python-colordemo\n    python -m colordemo\n\n## Overview of functionality\n\n`colordemo` allows you to programmatically determine the RGB values of\nsome terminals' ANSI colors (or more colors, if the terminal has them).\nThe functions must be run from the terminal whose colors you want to\ndetermine, and with caveats if within a screen or tmux session (see\nbelow for more on this).  Not all terminal types are supported (see the\nnext section).\n\n## Terminal support\n\nThe fundamental requirement for a terminal to be supported by `colordemo`\nis for it to support the xterm-like OSC (\"Operating System Command\") control\nsequences, listed under \"Operating System Commands\" here:\n\nhttps://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands\n\n(Sometimes this support can be ascertained from the documentation of\nthe terminal, but often you just need to try it.)\n\nWe call these terminals \"xterm-like\". If a terminal emulator doesn't\nsupport those sequences, then it won't be supported here.\nThere may be other ways to obtain RGB values for these terminals, such\nas parsing configuration files or perhaps parsing the output of\n`xrdb --query`, but we have no plans to implement any of these.\nThe only way to add support for a currently unsupported terminal is to\npatch the terminal with support for the OSC sequences.\n\nThere are too many terminals for us to test all of them, so the lists\nbelow are not exhaustive. If a terminal isn't mentioned in one of the\nfollowing subsections, attempt at your own risk!\n\n### Fully supported terminals\n\n**Note:** a terminal being \"supported\" doesn't mean `colordemo` will\nwork well on all versions of the terminal. For many terminals, proper\nsupport for the xterm-like OSC sequences was added and improved over\ntime.\n\n- xterm\n- urxvt\n- VTE-based terminals, including:\n  - vte\n  - Terminal (XFCE)\n  - gnome-terminal\n  - terminator\n  - tilda\n  - (etc.)\n- st\n- kitty\n- alacritty\n- wezterm\n- ttyd\n- (etc.)\n\n### Unsupported terminals\n\n- Konsole-based terminals, which are buggy:\n  - Konsole\n  - yakuake\n  - (etc.)\n- terminology\n- anything in Emacs (Eshell, vterm, ...)\n- Linux basic TTY (text mode without X)\n- (etc.)\n\nSome terminals (like terminology) don't seem to allow their colors to be\nqueried dynamically, so all RGB queries will fail, but the failure can\nbe detected. The demo script will therefore be able to output a color\ntable, but without RGB values.\n\nOther terminals (like Konsole) seem to support the query codes but are\nextremely buggy, returning incorrect values and even segfaulting\nsometimes.\n\nIn other cases (like older versions of the basic TTY), `colordemo` will garble\nthe TTY and make it unreadable. (Try `tput reset\u003cENTER\u003e` to restore it\nto something usable.)\n\n## Note regarding screen and tmux\n\nIt generally doesn't make sense to query a terminal from inside a screen\nor tmux session, since a single screen or tmux session can be attached\nto multiple terminals.  However, in the special case of being attached\nto a single terminal, it is possible because tmux and screen provide\n(different) methods to pass control sequences through to the attached\nterminal.  Of course, it makes no sense to try this if there are\nmultiple terminals attached, and you should expect crazy results if you\ndo.  Thus, forwarding queries through screen or tmux is currently an\nopt-in feature (see the `screen_forward` optional argument in\n`TerminalQueryContext.__init__` or the\n`--screen-forward`/`--tmux-forward` command-line options).\nThis will fail inside a nested screen or tmux session.\n\n(Not using the optional screen/tmux control-passthrough support, it's\ninteresting to observe that screen and tmux emulate a 256-color terminal\nindependently of the terminal(s) to which they are attached, which is\nvery apparent if you run the script with 256-color output on a screen\nsession attached to a terminal with 8- or 16-color terminfo (or with\nTERM set to such).)\n\n## Python API\n\nFor greater flexbility, the functionality of this package can also be\naccessed through its Python API. For example, this could be useful to\ncreate new color scheme demo scripts.\n\nThe primary interface is the context manager,\n`colordemo.TerminalQueryContext`. The color queries must be performed\ninside the context manager's context.\n\n```Python Console\nimport colordemo\n\nwith colordemo.TerminalQueryContext() as tq:\n    # Simplest method: get everything at once.\n    # This provides a list of RGBAColor instances.\n    colors = tq.get_all_indexed_colors()\n\n    # Alternatively, you can query individual colors.\n    n = tq.get_num_colors()\n    colors = [tq.get_indexed_color(k) for k in range(n)]\n\n    # The foreground and background colors need to\n    # be queried separately:\n    fg = tq.get_fg()\n    bg = tq.get_bg()\n\n# Color values are represented as instances of `RGBAColor`, which is\n# a specialization of `namedtuple`.\n(r, g, b, a) = fg\n\n# Equivalent:\nr, g, b, a = fg.r, fg.g, fg.b, fg.a\n\n# Color components are floating-point numbers in the range [0, 1].\n# To convert these to two-digit hex codes:\nr_hex = '%02x' % (int(r * 0xffff) // 256)  # etc.\n```\n\n## Credits\n\n- dranjan: main implementation\n- oblique: improved tmux support\n- Xyne: much useful discussion and review\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdranjan%2Fpython-colordemo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdranjan%2Fpython-colordemo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdranjan%2Fpython-colordemo/lists"}