Package: colordemo
colordemocolordemois a Python package implementing RGB queries on xterm-like
terminals.  It includes a demo script for presenting terminal color
schemes, complete with RGB hex codes.Quick startThere are many ways to run the demo script, and we will briefly describe
them here. Note that with any of the methods below, thecolordemotool can accept command-line options. To see which options are available,
use--helpwith any of the methods, e.g.,pipx run colordemo --helpUsingpipxWith only an active internet connection and thepipxPython utility,
the script can be run directly without installation:pipx run colordemoAlternatively, it can also be installed explicitly and run that way:pipx install colordemo
colordemoUsingpipThe package can also be installed and run as a normal Python package
usingpip(preferably in avirtualenvenvironment):pip install colordemo
colordemo

# Equivalent
python -m colordemoFrom the source treeFinally, the script can be run easily from the source tree directly.
This package has no dependencies besides Python, so no actions are
needed besides cloning the repository.git clone 'git@github.com:dranjan/python-colordemo.git'
cd python-colordemo
python -m colordemoOverview of functionalitycolordemoallows you to programmatically determine the RGB values of
some terminals' ANSI colors (or more colors, if the terminal has them).
The functions must be run from the terminal whose colors you want to
determine, and with caveats if within a screen or tmux session (see
below for more on this).  Not all terminal types are supported (see the
next section).Terminal supportThe fundamental requirement for a terminal to be supported bycolordemois for it to support the xterm-like OSC ("Operating System Command") control
sequences, listed under "Operating System Commands" here:https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands(Sometimes this support can be ascertained from the documentation of
the terminal, but often you just need to try it.)We call these terminals "xterm-like". If a terminal emulator doesn't
support those sequences, then it won't be supported here.
There may be other ways to obtain RGB values for these terminals, such
as parsing configuration files or perhaps parsing the output ofxrdb --query, but we have no plans to implement any of these.
The only way to add support for a currently unsupported terminal is to
patch the terminal with support for the OSC sequences.There are too many terminals for us to test all of them, so the lists
below are not exhaustive. If a terminal isn't mentioned in one of the
following subsections, attempt at your own risk!Fully supported terminalsxtermurxvtVTE-based terminals, including:vteTerminal (XFCE)gnome-terminalterminatortilda(etc.)kittyalacrittyweztermttyd(etc.)Unsupported terminalsKonsole-based terminals, which are buggy:Konsoleyakuake(etc.)terminologyst (unpatched)Linux basic TTY (text mode without X)(etc.)Some terminals (like terminology) don't seem to allow their colors to be
queried dynamically, so all RGB queries will fail, but the failure can
be detected. The demo script will therefore be able to output a color
table, but without RGB values.Other terminals (like Konsole) seem to support the query codes but are
extremely buggy, returning incorrect values and even segfaulting
sometimes.In other cases (like the basic TTY),colordemowill garble
the TTY and make it unreadable. (Trytput reset<ENTER>to restore it
to something usable.)Note regarding screen and tmuxIt generally doesn't make sense to query a terminal from inside a screen
or tmux session, since a single screen or tmux session can be attached
to multiple terminals.  However, in the special case of being attached
to a single terminal, it is possible because tmux and screen provide
(different) methods to pass control sequences through to the attached
terminal.  Of course, it makes no sense to try this if there are
multiple terminals attached, and you should expect crazy results if you
do.  Thus, forwarding queries through screen or tmux is currently an
opt-in feature (see thescreen_forwardoptional argument inTerminalQueryContext.__init__or the--screen-forward/--tmux-forwardcommand-line options).
This will fail inside a nested screen or tmux session.(Not using the optional screen/tmux control-passthrough support, it's
interesting to observe that screen and tmux emulate a 256-color terminal
independently of the terminal(s) to which they are attached, which is
very apparent if you run the script with 256-color output on a screen
session attached to a terminal with 8- or 16-color terminfo (or with
TERM set to such).)Python APIFor greater flexbility, the functionality of this package can also be
accessed through its Python API. For example, this could be useful to
create new color scheme demo scripts.The primary interface is the context manager,colordemo.TerminalQueryContext. The color queries must be performed
inside the context manager's context.importcolordemowithcolordemo.TerminalQueryContext()astq:# Simplest method: get everything at once.# This provides a list of RGBAColor instances.colors=tq.get_all_indexed_colors()# Alternatively, you can query individual colors.n=tq.get_num_colors()colors=[tq.get_indexed_color(k)forkinrange(n)]# The foreground and background colors need to# be queried separately:fg=tq.get_fg()bg=tq.get_bg()# Color values are represented as instances of `RGBAColor`, which is# a specialization of `namedtuple`.(r,g,b,a)=fg# Equivalent:r,g,b,a=fg.r,fg.g,fg.b,fg.a# Color components are floating-point numbers in the range [0, 1].# To convert these to two-digit hex codes:r_hex='%02x'%(int(r*0xffff)//256)# etc.Creditsdranjan: main implementationoblique: improved tmux supportXyne: much useful discussion and review