escprint 1.0.3

Library for formatting and styling terminal outputs via ANSI escape sequences.

escprint

Library for formatting and styling terminal outputs via ANSI escape sequences.

Installation

pip install escprint

Usage

from escprint import esc

esc.print

This is useful for a basic print statement. The first argument is the string to print, while the rest are styles/colors to format the string with.

*Note that all styles are cleared after the print statement is executed

All of the keyword arguments valid for python's print function are valid, as well as several others, shown in examples below.

A list of valid formatting strings can be found at the bottom of this document.

esc.print("Hello World!", "red","underline", end="")

Different Escape Arguments can be deliminated by a "/"

esc.print("Hello World!", "red/underline", end="")

Keyword Args

Keyword	Description
bg	sets background color, either color code (int) or R,G,B (tuple)
fg	sets foreground color , either color code (int) or R,G,B (tuple)
prefix	sets prefix to prepend to string
precall	a function to call before print statement
postcall	a function to call after print statement

To get more specific with color preferences, you can use the fg or bg keyword argument to plug in either a color code value ranging from 0 to 255, or an (R,G,B) tuple. fg sets the foreground color, while bg sets the background.

These color codes can also be found at the bottom of this document.

esc.print("Print white color", fg=255)

esc.print("Print white color, with black background.", fg=(255,255,255), bg=(0,0,0))

Prefixes are also valid

esc.print("World!", "red/underline", prefix="Hello ")

precall & postcall keyword arguments can be passed as well. These are functions that will be called before and after the print statement, respectively.

esc.print("World", "red", precall=lambda:print("Hello"), postcall=lambda:print("!"))

esc.printf

Sometimes, we want different characters/words to have different styles.

esc.printf(
    "This is normal, ",
    ("but this is red and underlined, ", "red/underline"),
    ("and this is blue and italic", "blue/italic")
)

We can also set a default style as well, with the default keyword argument.

esc.printf(
    "This is red ",
    ("This is blue", "blue"),
    "This is still red",
    default="red"
)

All other keyword arguments valid for esc.print are valid for this function as well.

esc.printf(
    "These are separated by newlines",
    ["and this is red and underlined, ", "red/underline"],
    end="\n"
)

esc.create_fn

If we are constantly printing the same styles over and over, we might want to create a printing function to do it for us.

print_yellow_italic = esc.create_fn("yellow","italic")

print_yellow_italic("This will be yellow and italic", end="")

Note that the keyword arguments allowed for esc.print are valid when creating the function.

print_yellow_italic = esc.create_fn("yellow","italic",precall=print("'Ello Govna"))

esc.input

We also might want to format our inputs as well.

Here, the prompt is "What is your name? ". The prompts style is set via the prompt keyword argument. The input style will be set via the input keyword argument.

user_input = esc.input(
    "What is your name? ", 
    prompt="yellow/italic", 
    input="red/underline", 
    end=""
)

esc.set

This is used to set the terminal outputs to a style indefinitely.

esc.set("cyan","underline","italic")
# OR
esc.set("cyan/underline/italic")

The keyword arguments bg, fg, are valid keywords as well.

esc.set(fg=(122,56,255))

esc.clear

This is used to reset all terminal output styles to their default.

esc.set("red")
print("This is red")
esc.clear()
print("This is normal")

esc.cursor_up

This moves the cursor position up by an integer n, which defaults to 1.

esc.cursor_up(2)

esc.cursor_down

This moves the cursor position down by an integer n, which defaults to 1.

esc.cursor_down(2)

esc.cursor_left

This moves the cursor position left by an integer n, which defaults to 1.

esc.cursor_left(2)

esc.cursor_right

This moves the cursor position right by an integer n, which defaults to 1.

esc.cursor_right(2)

esc.erase_to_endln

This erases everything from the current position of your cursor to the end of the line.

esc.erase_to_endln()

esc.erase_screen

This erases everything on the screen.

esc.erase_screen()

esc.erase_line

This erases everything on the line the cursor is on.

esc.erase_line()

esc.erase_prev

This moves the cursor up 1, and erases everything on that line.

esc.erase_prev()

esc.hide_cursor

This hides the cursor.

esc.hide_cursor()

esc.show_cursor

This unhides, or shows the cursor.

esc.show_cursor()

esc.enable_alt_buffer

This enables an alternative buffer.

esc.enable_alt_buffer()

esc.disable_alt_buffer

This disables the alternative buffer.

esc.disable_alt_buffer()

esc.save_cursor

This saves the cursor position.

esc.save_cursor()

esc.restore_cursor

This restores the cursor position to the previously saved one.

esc.restore_cursor()

esc.save_screen

This saves the current screen.

esc.save_screen()

esc.restore_screen

This restores the saved screen.

esc.restore_screen()

esc.fg_code

Sets the foreground color to a color code.

esc.fg_code(255)

esc.bg_code

Sets the background color to a color code.

esc.fg_code(255)

esc.fg_code

Sets the foreground color to a color code.

esc.fg_code(255)

esc.bg_code

Sets the background color to a color code.

esc.bg_code(255)

esc.fg_rgb

Sets the foreground color to an rgb color code.

esc.fg_rgb(255, 142, 34)

esc.bg_code

Sets the background color to an rgb color code.

esc.bg_rgb(255, 142, 34)

esc.terminal_size

Returns an (x,y) pair representing the width and height of the screen in terms of columns/lines.

size = esc.terminal_size()
n_cols = size.x
n_lines = size.y
# move cursor halfway up the screen, and halfway to the right
esc.cursor_up(n_lines/2)
esc.cursor_right(n_cols/2)

esc.cursor_to_top

Sets the cursor position to the top of the screen.

esc.cursor_to_top()

esc.cursor_home

Sets the cursor position to the home position (0,0).

esc.cursor_home()

Formatting Strings

Text Decoration

String	Description
reset	reset formatting to default
bold	make text bold
dim	make text dim
blink	make text blink
italic	make text italic
i	italic shorthand
underline	underline text
u	underline shorthand

Color

String	Description
black	set foreground color to black
white	set foreground color to white
red	set foreground color to red
green	set foreground color to green
yellow	set foreground color to yellow
blue	set foreground color to blue
magenta	set foreground color to magenta
cyan	set foreground color to cyan
Black	set foreground color to bright black
White	set foreground color to bright white
Red	set foreground color to bright red
Green	set foreground color to bright green
Yellow	set foreground color to bright yellow
Blue	set foreground color to bright blue
Magenta	set foreground color to bright magenta
Cyan	set foreground color to bright cyan
bblack	set background color to black
bwhite	set background color to white
bred	set background color to red
bgreen	set background color to green
byellow	set background color to yellow
bblue	set background color to blue
bmagenta	set background color to magenta
bcyan	set background color to cyan
bBlack	set background color to bright black
bWhite	set background color to bright white
bRed	set background color to bright red
bGreen	set background color to bright green
bYellow	set background color to bright yellow
bBlue	set background color to bright blue
bMagenta	set background color to bright magenta
bCyan	set background color to bright cyan

Other

String	Description
reverse	reverse foreground & background
hidden	hide text
strike	strikethrough text
strikethrough	strikethrough text
delete	delete character
home	set cursor to home position
request	request cursor position
savecursor	save cursor position
restorecursor	restore cursor position

Color Codes

Resources

• Christian Petersen - ANSI Escape Sequences

MIT License

Copyright (c) 2023 Michael Schilling Munson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.