constyle

A Python library to add style to your console.

The name of the library comes from merging the words CONSoLE and STYLE. Also "con" means "with" in Spanish.

Installation

You can install this package with pip or conda.

$ pip install constyle

$ conda install -c conda-forge constyle

$ conda install -c abrahammurciano constyle

Links

Usage

There are a couple of ways to use this library.

The style() function

The simplest way is with the style() function.

from constyle import style, Attributes

print(style('Hello World', Attributes.GREEN, Attributes.BOLD, Attributes.ON_BLUE))

Style objects

You can also use Style objects to create a reusable style with any number of attributes.

Calling a Style object

Style objects are callable and take a string as input (or any other object, which will be converted to a string) and return a styled string.

warning = Style(Attributes.YELLOW, Attributes.BOLD)
print(warning('You shall not pass!'))

Adding Style objects

Adding together Style objects will also create Style objects.

whisper = Attributes.GREY + Attributes.DIM + Attributes.SUPERSCRIPT
print(whisper('Fly you fools'))

Converting Style objects to strings

Style objects can be converted to strings to obtain the ANSI escape sequence for that style.

warning = Style(Attributes.YELLOW, Attributes.BOLD)
print(f"{warning}You shall not pass!{Attributes.RESET}")

Attributes

The Attributes enum contains all the available ANSI attributes. You can read more about them here.

Attributes are also Style objects, and as such, as demonstrated above, they too can be called to style a string, added together and to other Style objects, and converted to strings to obtain their ANSI sequence.

You'll find there is limited support for all the ANSI attributes among some consoles.

If you find more attributes that aren't provided in this enum, you can create your own by constructing a Style with an integer.

Nesting

In order to nest styles, you can use the end= keyword argument of the style() function or the Style class. Usually when applying a style, the RESET attribute is appended to the end. This can be undesirable when nesting (see the example below).

bold = Attributes.BOLD
yellow = Attributes.YELLOW
green = Attributes.GREEN

print(yellow(bold('This is bold and yellow')))
print(green(f"This is green. {yellow('This is yellow.')} This is no longer green"))

In order to achieve the desired result in the above example, you would have to use the end= keyword argument of the style() function. You can pass any Style to end.

print(green(f"This is green. {bold('This is green and bold.', end=Attributes.NO_BOLD)} This is still green but not bold anymore"))
print(green(f"This is green. {yellow('This is yellow.', end=green)} This is now green again"))

Custom colours

The constyle.custom_colours module contains a few classes that can be used to create custom colours.

RGB colours

You can create a Style for a custom RGB colour by using the RGB class. This is not well supported by all consoles.

from constyle.custom_colours import RGB

print(style('This is pink', RGB(255, 192, 203)))

8-bit colours

Some consoles support 8-bit colours. You can create a Style for an 8-bit colour by using the EightBit class, passing a single integer to it, or you can use the EightBitRGB class to create an 8-bit colour style as close to the RGB values as possible.

The command line interface

This package also provides a very basic command line interface to print styled strings.

You can pass it any number of strings and it will print them all together (like echo). You can pass --attribute (or -a) with the name of an attribute to apply to the other strings being printed. You can pass --attribute as many times as you like.

You can use constyle --help to see more specific details, as well as all available attributes.

For example you can use constyle from your shell to print some styled text.

$ constyle Hello World! -a green -a bold -a on_white

Or if you're writing a shell script you can make an alias or a function to reuse a certain style.

#!/bin/bash
alias error="constyle --attribute bold --attribute red" # With an alias
warn() { constyle $@ -a bold -a yellow } # With a function
error You shall not pass!
warn Fly you fools!

Sub-modules

constyle.custom_colours

This module contains classes to create foreground and background attributes which apply custom colours …

Functions

def style(string: object, *attrs: Style, end: Optional[Style] = None) ‑> str

Apply the given attributes to the given string.

If the given object isn't a string it will be converted into one.

Args

string

The string to style.

*attrs

The attributes/styles to apply.

end

The style to apply after the string. If None (the default) it will reset all attributes at the end.

Classes

class Attributes (*attrs: Union[Style, int], end: Optional[Style] = None)

This enum contains almost all ANSI sequences known to man.

Due to inconsistencies across implementations you may find that there are sometimes conflicting attributes with the same param.

There are also several common aliases for the same attribute (such as RESET and NORMAL).

Ancestors

• constyle._style.Style
• enum.Enum

Class variables

var ALT_FONT_1

Select alternate font 1. Rarely supported.

var ALT_FONT_2

Select alternate font 2. Rarely supported.

var ALT_FONT_3

Select alternate font 3. Rarely supported.

var ALT_FONT_4

Select alternate font 4. Rarely supported.

var ALT_FONT_5

Select alternate font 5. Rarely supported.

var ALT_FONT_6

Select alternate font 6. Rarely supported.

var ALT_FONT_7

Select alternate font 7. Rarely supported.

var ALT_FONT_8

Select alternate font 8. Rarely supported.

var ALT_FONT_9

Select alternate font 9. Rarely supported.

var BLACK

Black foreground text

var BLINK

Same as SLOW_BLINK

var BLUE

Blue foreground text

var BOLD

Bold text

var BRIGHT_BLACK

Grey foreground text

var BRIGHT_BLUE

Bright blue foreground text

var BRIGHT_CYAN

Bright cyan foreground text

var BRIGHT_GREEN

Bright green foreground text

var BRIGHT_MAGENTA

Bright magenta foreground text

var BRIGHT_RED

Bright red foreground text

var BRIGHT_WHITE

Bright white foreground text

var BRIGHT_YELLOW

Bright yellow foreground text

var CONCEAL

Invisible text (same as HIDE). Not widely supported.

var CROSSED

Crossed out text (same as STRIKE). Characters legible but marked as if for deletion.

var CYAN

Cyan foreground text

var DEFAULT_BACKGROUND

Default background text colour

var DEFAULT_FOREGROUND

Default foreground text colour

var DEFAULT_UNDERLINE_COLOUR

Set the underline colour to the default. Not in standard; implemented in Kitty, VTE, mintty, and iTerm2.

var DIM

Dim text (same as FAINT). May be implemented as a lighter colour or as a thinner font.

var DOUBE_UNDERLINE

Double underline. Rarely supported. Sometimes implemented as not bold.

var ENCIRCLED

Encircled text. Implemented as "emoji variation selector" in mintty.

var FAINT

Faint text (same as DIM). May be implemented as a lighter colour or as a thinner font.

var FRAKTUR

Fraktur font (same as GOTHIC). Rarely supported.

var FRAMED

Framed text. Implemented as "emoji variation selector" in mintty.

var GOTHIC

Gothic font (same as FRAKTUR). Rarely supported.

var GREEN

Green foreground text

var GREY

Grey foreground text (same as BRIGHT_BLACK)

var HIDE

Invisible text (same as CONCEAL). Not widely supported.

var IDEOGRAM_DOUBLE_OVERLINE

Ideogram double overline. Rarely supported.

var IDEOGRAM_DOUBLE_UNDERLINE

Ideogram double underline. Rarely supported.

var IDEOGRAM_OVERLINE

Ideogram overline. Rarely supported.

var IDEOGRAM_STRESS_MARK

Ideogram stress mark. Rarely supported.

var IDEOGRAM_UNDERLINE

Ideogram underline. Rarely supported.

var INVERT

Swap foreground and background colors; inconsistent emulation

var ITALIC

Italic text. Not widely supported. Sometimes implemented as inverse or blink.

var LEFT_DOUBLE_LINE

Double line on left of text. Rarely supported.

var LEFT_LINE

Line on left of text. Rarely supported.

var MAGENTA

Magenta foreground text

var NORMAL

Remove all formatting (same as RESET)

var NO_BACKGROUND

Default background text colour

var NO_BLINK

Sets blinking to off.

var NO_BOLD

Not bold text. Sometimes implemented as double underline.

var NO_BOLD_FEINT

Neither bold nor faint text

var NO_COLOUR

Default foreground text colour

var NO_CONCEAL

Unset conceal/hide (same as REVEAL and NO_HIDE)

var NO_CROSSED

Unset crossed out text (same as NO_STRIKE)

var NO_FOREGROUND

Default foreground text colour

var NO_FRAMED_ENCIRCLED

Unset framed/encircled text

var NO_HIDE

Unset conceal/hide (same as REVEAL and NO_CONCEAL)

var NO_IDEOGRAM

Unset ideogram underline/overline/stress mark.

var NO_INVERT

Unset invert

var NO_ITALIC_BLACKLETTER

Neither italic nor blackletter text

var NO_OVERLINE

Unset overline

var NO_PROPORTIONAL_SPACING

Unset proportional spacing

var NO_STRIKE

Unset crossed out text (same as NO_CROSSED)

var NO_SUPERSCRIPT_SUBSCRIPT

Unset superscript/subscript text

var NO_UNDERLINE

Unset underline

var ON_BLACK

Black background text

var ON_BLUE

Blue background text

var ON_BRIGHT_BLACK

Grey background text

var ON_BRIGHT_BLUE

Bright blue background text

var ON_BRIGHT_CYAN

Bright cyan background text

var ON_BRIGHT_GREEN

Bright green background text

var ON_BRIGHT_MAGENTA

Bright magenta background text

var ON_BRIGHT_RED

Bright red background text

var ON_BRIGHT_WHITE

Bright white background text

var ON_BRIGHT_YELLOW

Bright yellow background text

var ON_CYAN

Cyan background text

var ON_GREEN

Green background text

var ON_GREY

Grey background text (same as ON_BRIGHT_BLACK)

var ON_MAGENTA

Magenta background text

var ON_RED

Red background text

var ON_WHITE

White background text

var ON_YELLOW

Yellow background text

var OVERLINE

Overline text

var PRIMARY_FONT

Select primary font.

var PROPORTIONAL_SPACING

Proportional spacing. Not known to be used on terminals.

var RAPID_BLINK

Sets blinking to more than 150 times per minute. Rarely supported.

var RED

Red foreground text

var RESET

Remove all formatting (same as NORMAL)

var REVEAL

Unset conceal/hide (same as NO_CONCEAL and NO_HIDE)

var RIGHT_DOUBLE_LINE

Double line on right of text. Rarely supported.

var RIGHT_LINE

Line on right of text. Rarely supported.

var SLOW_BLINK

Sets blinking to less than 150 times per minute. Rarely supported.

var STRIKE

Crossed out text (same as CROSSED). Characters legible but marked as if for deletion.

var SUBSCRIPT

Subscript text. Implemented in mintty

var SUPERSCRIPT

Superscript text. Implemented in mintty

var UNDERLINE

Underline text. Style extensions exist for Kitty, VTE, mintty and iTerm2.

var WHITE

White foreground text

var YELLOW

Yellow foreground text

class Style (*attrs: Union[Style, int], end: Optional[Style] = None)

A collection of attributes defining the style of a string.

You can call Style objects to apply the style to a string.

>>> warning = Style(Attributes.BOLD, Attributes.YELLOW, Attributes.ITALIC)
>>> print(warning("This is a warning!"))

You can add Style objects together to create a Style with all their attributes combined.

>>> warning = Style(Attributes.YELLOW, Attributes.ITALIC)
>>> error = warning + Attributes.BOLD + Attributes.ON_RED
>>> print(error("This is an error!"))

You can also convert a Style object to a string to get the ANSI escape sequence for the style.

>>> print(f"{Attributes.YELLOW + Attributes.ITALIC + Attributes.BOLD}This is a warning!{Attributes.RESET}")

Args

*attrs

The attributes to apply. Can be a mix of Style objects or ints.

end

The style to apply after each styled string. If None (the default) it will reset all attributes.

Subclasses

• constyle._attributes.Attributes
• EightBit
• RGB