Skip to content

Latest commit

 

History

History
317 lines (215 loc) · 9.92 KB

README.rst

File metadata and controls

317 lines (215 loc) · 9.92 KB

autopalette

Terminal palettes and themes, without tears.

pip install autopalette

Status: Alpha; being developed.

Do you write python scripts that print() text on the command-line terminal? Do you feel the interface could convey a bit more meaning, but the effort needed to get it right has kept you away from using ANSI colors? These things should be easy, right?

Here’s a regular Python program that prints a word:

print("Tring!")
01-regular-print

01-regular-print

Here is what it looks like with autopalette, using a shortcut called AutoFormat or in short: af.

from autopalette import af

print(af("Tring!"))
02-autoformat-wrapped-print

02-autoformat-wrapped-print

We added one line to import, and four characters around the string.

And it does nothing - autopalette is non-intrusive that way. You can leave your af-wrapped strings around and they will not run unnecessary code until you ask for more.

What’s more?

from autopalette import af

print(af("Hello, world!").id)
print(af("Hello, world!").id256)
03-id-deterministic-color

03-id-deterministic-color

If your terminal / emulator reports that it supports color, you should see the second line formatted in fuschia/ magenta. Try changing the text and observe that the color changes when the text changes, but it stays fixed for the same text. Across function calls, across program runs, across machines, across time itself! Okay maybe that was too dramatic, but it is kind of true because, mathematics.

Autopalette’s id feature hashes the supplied text and generates a color unique to the text within the range of colors reported by the terminal. id256 generates a color within the ANSI 256 palette. id256 is not portable, but feel free to use it for your personal scripts where color limits are known.

Why is this useful?

It helps to identify unique names that your program may output, such as:

  • hostnames, when working with remote machines.
  • usernames, for logs of multi-user environments.
  • you know better what matters to your program’s output :)

Sometimes you want a little more…

from autopalette import af

print(af("Hello again!").h1)
04-header-one

04-header-one

And we have a nicely decorated header, just like that. You can use one of the several pre-defined styles, or read further below how you can design your own.

Here are the various styles built into autopalette.

  • p: plain-text, or paragraph - as you like to read it.
  • light: where color range allows it, lighter text.
  • dark: darker text if terminal supports enough colors within palette.
  • h1: highlighted text style 1, or header-1.
  • h2:
  • h3
  • h4
  • li: list element.
  • err: an error
  • warn: a warning
  • info: a warning
  • ok: a warning
  • b: bold.
  • i: italic.
  • u: underline.
  • r: reversed colors.
  • raw: useful to debug, displays the ANSI code instead of applying it.

Let us try superimposing two styles.

from autopalette import af

print(af("Hey! We've met before!?").info.b)
05-superimpose-styles

05-superimpose-styles

You get the idea, tack the names of styles you want at the end-bracket of the call to af.

If you are wondering, “Wait, what’s with that weird syntax?”, in Python’s spirit of quick protoyping, autopalette encourages experimenting with minimal mental and physical effort to tweak knobs. Your program’s actual task matters more, but you care enough about your future self and users using the app to style it well and be a delight to use. Autopalette’s syntax is an expriment to help manage this dilemma.

While you compose and read your code, this syntax separates the styling from rest of the function calls. You don’t have to think about styling unless you want to, and when you do, which is often as you look at the string you just put together to print - assuming you started with af(", close the quote and bracket, type out a style shortcut and you are done.

Although, few times you want a bit more than that…

from autopalette import af, GameBoyGreenPalette

af.init(palette=GameBoyGreenPalette)

print(af("There you are!").h1)
06-select-palette

06-select-palette

Look at that! Yummy.

Autopalette goes the length to support a handful of palettes.

  • GameBoyChocolate
  • GameBoyOriginal
  • Grayscale
  • Oil
  • Arcade
  • CLRS

If this is exciting to you too, read further below how to create your own!

How does this look on a terminal with only 16 colors?

06-select-palette-16-color

06-select-palette-16-color

Not too shabby, eh?

How do you test how your app will look on terminals with limited colors? Try these as prefix to your script invocation for a temporary change:

  • env TERM=vt100
  • env TERM=rxvt
  • env TERM=xterm
  • env TERM=xterm-256color
  • env COLORTERM=truecolor
  • env NO_COLOR

like so:

$ env TERM=xterm-256color python app.py

To save a setting permanently, put export TERM=... in your ~/.bash_profile or your default shell’s configuration.

If the environment variable NO_COLOR is set, autopalette honors the configuration and disables all color. Same with redirected output and pipes - autopalette will handle it fully automatically, if it fails to do so, please open an issue in the tracker and I’ll do my best to fix it. In case you can fix the issue yourself, a pull request will be awesome!

And we would be essentially done, except, there’s this little voice in the head that’s saying something mojibªke something, but it’s all garbled up.

from autopalette import af

af.init(fix_text=True)

print(af("¯\\_(ã\x83\x84)_/¯").info)
07-fix-text

07-fix-text

Neat, with the fix_text option set, autopalette transparently passes your text through ftfy’s fix_text() function call, ensuring your application does not output garbage when badly encoded strings find their way to your app’s print statement.

There’s more, not all terminal and emulators support unicode, and will still produce garbage if we feed them strings that they do not know how to display. Use the fix_all option to let autopalette and the terminal it is running on figure out the rest.

from autopalette import af

af.init(fix_all=True)

print(af("I 💛 Unicode!"))

Try this example with env TERM=vt100 for the full cleanup!

08-fix-all

08-fix-all

Note that fixing text and emoji requires additional libraries to be loaded and can slow down startup time. If your program does not output strings generated by other programs, (which includes strings received from http APIs!) and the program is invoked repeatedly instead of running for a while, you may want to skip fix_... options.

And that’s about it for three-line examples!

You can start your scripts with af.init(fix_all=True) and use af() to wrap your strings, even if you ignore colors and styles, your program will display text correctly on most popular (and many obscure) terminals.

Here’s the basic theme:

09-basic-palette

09-basic-palette

But there’s more!

Your users have the ability to define their own themes, and autopalette will automatically* recolor your application to their preferences or needs. (*mostly automatically, or with a little help.)

# ~/.autopalette

palette = Dutron
render = Truecolor
10-restricted-color-palette

10-restricted-color-palette

Your terminal applications look beautiful as you intend, to everyone, as they expect.

It is almost two decades since Y2K! And with over 50 years of the terminal technology behind us, this should be a thing we expect as a norm.

Autopalette is another attempt at fixing some of these gaps by making it near trivial to style terminal apps and do the right thing for the various terminals it runs on… without the complexity often involved as a result of the rich legacy of the technology.

Autopalette would not dare exist without the libraries published by these generous individuals who made it possible to think and write code in simple mental models that are just right for the task: