GitLocker: The Coding Marketplace

Description:

pixy 1.0.3

pixy

pixy is a Python library for adding colour and style to terminal text.

Getting Started

Installation
Usage

Documentation
Examples
Tests
License

Terminal output can be styled using ANSII escape code. pixy provides a simple to use yet comprehensive wrapper, abstracting away the complexities.
pixy supports:

3-bit, 4-bit and 8-bit colour;
24-bit true colour RGB;
changing the foreground and background colour;
text decorators e.g. blink, underline, bold, italic, strike-through;
custom fonts for compliant terminals;
custom ANSII codes for development on non-spec-compliant terminals.

Getting Started
Installation
pixy can be installed using pip.
$ python3 -m pip install pixy

Usage
pixy lets you style text straight out of the box.
import pixy

# Print "Hello World" in red.
print(pixy.red("Hello World"))

It provides the flexibility to format text as you wish.
import pixy

# Create a string "Hello" with bold text and blue background.
s1 = pixy.pring("Hello", pixy.decorators.bold + pixy.background.blue)

# Concatenate the two strings, giving everything a red background (the
# red background won't be applied to "Hello" because we've already
# given it a blue background!)
print(pixy.pring(s1 + " World. Lorem ipsum dolor...", pixy.background.red))

Documentation
Not all terminals support all ANSII escape codes. Please check the terminal you are testing on supports the features you are using before opening an issue.
Helpers
You can create a string of a certain colour using the helper functions below:

pixy.black(text)
pixy.red(text)
pixy.green(text)
pixy.yellow(text)
pixy.blue(text)
pixy.magenta(text)
pixy.cyan(text)
pixy.white(text)

Example
import pixy

# Print "Hello World" in red.
print(pixy.red("Hello World"))

pixy.pring(text, style)
pixy.pring allows you to generate a string with any of the styles documented below. You can use more than one style by adding them together.

text - the text to apply the style to.
style - the style to apply to the text.

Example
import pixy

# Print "Hello World" with green text and white background.
print(pixy.pring(
"Hello World",
pixy.foreground.green + pixy.background.white
))

pixy.foreground, pixy.background
pixy.foreground and pixy.background contain the variables: black,
red, green, yellow, blue, magenta, cyan, white.
Using the pixy.foreground variant of the colour will apply the colour
to the foreground and the pixy.background variant will apply it to the
background.
These colours are known as the 3-bit colours and almost all terminals support
them. Most terminals also let you make them bright by adding the
pixy.decorators.bold style.
Example
import pixy

# Print "Hello World" with green text.
print(pixy.pring("Hello World", pixy.foreground.green))

pixy.decorators
Decorators let you apply other styles to the text.

Decorator
Description
Support

pixy.decorators.bold
Bold/bright

pixy.decorators.faint
Faint/dimmed

pixy.decorators.italic
Italicised

pixy.decorators.underline
Underlined

pixy.decorators.slow_blink
Slow blink (less than 150 per minute)

pixy.decorators.rapid_blink
Rapid blink (150+ per minute)
Not widely supported

pixy.decorators.invert
Swap foreground and background colours

pixy.decorators.conceal
Hide
Not widely supported

pixy.decorators.strike
Strike-through

pixy.decorators.fraktur
Fraktur
Rarely supported

pixy.decorators.double_underline
Double underline

pixy.decorators.framed

Not widely supported

pixy.decorators.encircled

Not widely supported

pixy.decorators.overlined
Overlined

(Descriptions adapted from Wikipedia)
Example
import pixy

# "Hello World" underlined.
print(pixy.pring("Hello World", pixy.decorators.underline))

pixy.ExtendedColour(code, background=False)
With pixy.ExtendedColour you can select from a pre-defined selection of 256
colours.

code - corresponds to a colour code found
here.

background - boolean value indicating if this is a background or
foreground colour.

Example
import pixy

# Print "Hello World" in violet.
print(pixy.pring("Hello World", pixy.ExtendedColour(99)))

# Print "Hello World" with a violet background.
print(pixy.pring("Hello World", pixy.ExtendedColour(99, True)))

pixy.TrueColour(red, green, blue, background=False)
With pixy.TrueColour you can create an RGB colour.

red - value between 0 and 255 indicating the intensity of the
red component.

green - value between 0 and 255 indicating the intensity of the
green component.

blue - value between 0 and 255 indicating the intensity of the
blue component.

background - boolean value indicating if this is a background or
foreground colour.

Example
import pixy

# Print "Hello World" in violet.
print(pixy.pring("Hello World", pixy.TrueColour(238, 130, 238)))

# Print "Hello World" with a violet background.
print(pixy.pring("Hello World", pixy.TrueColour(238, 130, 238, True)))

pixy.Font(code)
Allows you to change the font used. Most terminals do not support this.

code - a number between 0 and 8 corresponding to a font.

Example
import pixy

print(pixy.pring("Hello World", pixy.Font(3)))

pixy.EscapeSequence(...)
pixy.EscapeSequence can be used in instances that you want to defined your own ANSII escape sequence.
pixy.EscapeSequence takes a variable number of arguments - each argument should be an ANSII code.
Example
import pixy

# Bright blue using ANSII code 94 supported by some terminals
print(pixy.pring("Hello World", pixy.EscapeSequence(94)))

Examples
Blinking Text
import pixy

print(pixy.pring("Hello World", pixy.decorators.slow_blink))

Concatenation
import pixy

# "Hello" in red.
s1 = pixy.pring("Hello", pixy.foreground.red)

# " World" in blue.
s2 = pixy.pring(" World", pixy.foreground.blue)

# Concatenate the strings, add a white background and make
# them bold.
s3 = pixy.pring(s1 + s2, pixy.background.white + pixy.decorators.bold)

print(s3)

Colour shades
import pixy

for i in range(0, 0xFF, 3):
colour = pixy.TrueColour(i, 0, 0, background=True)
print(pixy.pring(" ", colour), end="")

print()

for i in range(0, 0xFF, 3):
colour = pixy.TrueColour(0, i, 0, background=True)
print(pixy.pring(" ", colour), end="")

print()

for i in range(0, 0xFF, 3):
colour = pixy.TrueColour(0, 0, i, background=True)
print(pixy.pring(" ", colour), end="")

print()

Colour gradient
import pixy

def gradient(colour_a, colour_b):

output = []

for i in range(0, 100, 2):

p = i / 100

output.append((
int(colour_a[0] + p * (colour_b[0] - colour_a[0])),
int(colour_a[1] + p * (colour_b[1] - colour_a[1])),
int(colour_a[2] + p * (colour_b[2] - colour_a[2]))
))

return output

red_to_green = gradient((255, 0, 0), (0, 255, 0))
green_to_blue = gradient((0, 255, 0), (0, 0, 255))
blue_to_red = gradient((0, 0, 255), (255, 0, 0))

for colour in red_to_green:
print(pixy.pring(" ", pixy.TrueColour(*colour, background=True)), end="")

print()

for colour in green_to_blue:
print(pixy.pring(" ", pixy.TrueColour(*colour, background=True)), end="")

print()

for colour in blue_to_red:
print(pixy.pring(" ", pixy.TrueColour(*colour, background=True)), end="")

print()

License
pixy is licensed under the MIT license.