easy-ansi 0.2

Easy ANSI is a terminal framework API to give you an easy way to use colors, cursor control movements, and line/box drawing.

Easy ANSI

Easy ANSI is a terminal framework API to give you an easy way to use colors, cursor control movements, and line/box drawing. It is not meant as a replacement to more full-featured frameworks (such as curses or urwid), but as a tool to quickly create nice-looking screens in your terminal window. You can even create animations with the cursor controls.

You can find demo programs here.

Table of Contents

• Requirements
• General Usage
• Quick Reference
  • Screen Commands
  • Cursor Commands
  • Standard Colors
  • Attributes
  • 256 Color Palette
  • RGB Color Palette
  • Drawing Lines and Boxes
• Color Reference
  • Standard Color Reference

Requirements

• This library is not dependent on any operating system, but instead is dependent on the capabilities of the terminal you use.
• The Windows command prompt and PowerShell prompt do not support ANSI codes (as of this writing), and thus are not supported. You will find that terminal programs for Windows work well (Cygwin, Git Bash, PuTTY, etc).

General Usage

• All ANSI sequences come as either a command or a code (string). For example, to clear the screen, you can call the clear() method, but if you want to store the command to clear the screen, call the clear_code() method instead.
• Certain ANSI sequences may not work as expected when combined with other ANSI sequences. For example, mixing color palettes on the same line does not work well. You should always visually check your application.
• Certain terminal settings can change the behavior of certain ANSI codes. For example, many terminal emulators will display bright text as bold. You will have to experiment with your terminal settings for best results.

Quick Reference

Screen Commands

from easyansi import screen

Method	Description	Parameters
clear()	Clear the screen and move the cursor to 0, 0
clear_line(row)	Clear the line at the given row. If row is not provided, the row that the cursor is on will be cleared. The cursor will move to the beginning of the row cleared.	row (optional): The row number to clear.
get_size()	Return the size of the terminal. If the system cannot determine the size of the terminal, a default size of 80 columns by 24 rows is returned.
prnt(text)	A convenience method to print output to the screen without an ending newline character.	text: The text to output to the screen.

Cursor Commands

from easyansi import cursor

Method	Description	Parameters
locate(x, y)	Move the cursor to the x, y coordinates given. If only one of x or y is provided, the cursor will stay in the position of the other value. The upper-left corner is 0, 0.	x (optional): column y (optional): row
get_location()	Return the x, y coordinates of where the cursor is.
down(rows)	Move the cursor down a certain number of rows (default = 1).	rows: The number of rows to move the cursor down.
up(rows)	Move the cursor up a certain number of rows (default = 1).	rows: The number of rows to move the cursor up.
left(cols)	Move the cursor left a certain number of columns (default = 1).	cols: The number of columns to move the cursor left.
right(cols)	Move the cursor right a certain number of columns (default = 1).	cols: The number of columns to move the cursor right.
hide()	Hide the cursor.
show()	Show the cursor.

Standard Colors

See the color reference below.

from easyansi import colors

Method	Description	Parameters
color(fg, bg)	Set the foreground and/or background color from the 16-color palette.	fg: Foreground color index. bg: Background color index.
default(fg, bg)	Set the foreground and/or background color to the terminal default.	fg: Foreground color 0 (false) or 1 (true). bg: Background color 0 (false) or 1 (true).
reset()	Reset the colors and attributes to terminal defaults.

Attributes

from easyansi import attributes

Method	Description	Parameters
normal() bright() dim()	Set the text intensity to one of normal, bright, or dim. NOTE: Bright is often used to bold text.
italic() italic_off()	Set italic text on or off.
underline() underline_off()	Set underline text on or off.
reverse() reverse_off()	Set reverse text on or off.
strikethrough() strikethrough_off()	Set strike-through text on or off.
blink() blink_off()	Set blinking text on or off.
conceal() conceal_off()	Set concealed (hidden) text on or off. WARNING: Do NOT use this for password or other sensitive fields. Your text is still available to be copied from the terminal.
reset()	Reset the colors and attributes to terminal defaults.

256 Color Palette

See the color reference below.

from easyansi import colors_256

Method	Description	Parameters
color(fg, bg)	Set the foreground and/or background color from the 256-color palette.	fg: Foreground color index. bg: Background color index.
default(fg, bg)	Set the foreground and/or background color to the terminal default.	fg: Foreground color 0 (false) or 1 (true). bg: Background color 0 (false) or 1 (true).
reset()	Reset the colors and attributes to terminal defaults.

RGB Color Palette

from easyansi import colors_rgb

Method	Description	Parameters
color(r, g, b, bg_r, bg_g, bg_b)	Set the foreground and/or background color to the provided RGB values.	r: The foreground red value (0-255). g: The foreground green value (0-255). b: The foreground blue value (0-255). bg_r: The background red value (0-255). bg_g: The background green value (0-255). bg_b: The background blue value (0-255).
reset()	Reset the colors and attributes to terminal defaults.

Drawing Lines and Boxes

from easyansi.drawing import single
from easyansi.drawing import double
from easyansi.drawing import keyboard

Drawing Style	Description
single	Single line drawing characters.
double	Double line drawing characters.
keyboard	Line drawing characters only from keyboard characters.

from easyansi import drawing

Method	Description	Parameters
hline(length, char, style)	Draw a horizontal line to a given length, optionally composed of the given char(s) or of a given style.	length: Total length of the line. char: The character(s) to use to build the line. style: The line style to use to build the line. char will override the style.
vline(length, char, style)	Draw a vertical line to a given length, optionally composed of the given char(s) or of a given style.	length: Total length of the line. char: The character(s) to use to build the line. style: The line style to use to build the line. char will override the style.
box(width, height, style, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right, top_bottom, left_right, all_corners, all_sides, all_chars)	Draw a box. Only width and height is required. This utilizes the hline and vline methods internally.	width: Width of the box height: Height of the box. style: The line style to use top: The character(s) to use for the top line. bottom: The character(s) to use for the bottom line. left: The character(s) to use for the left line. right: The character(s) to use for the right line. top_left: The character to use for the top left corner. top_right: The character to use for the top right corner. bottom_left: The character to use for the bottom left corner. bottom_right: The character to use for the bottom_right corner. top_bottom: The character(s) to use for the top and bottom lines. left_right: The character(s) to use for the left and right lines. all_corners: The character to use for all the corners. all_sides: The character(s) to use for all sides. all_chars: The character to use for all drawing of the box.

Color Reference

Standard Color Reference

Color Index	Color Name
0	BLACK
1	RED
2	GREEN
3	YELLOW
4	BLUE
5	MAGENTA
6	CYAN
7	WHITE
8	BRIGHT_BLACK
9	BRIGHT_RED
10	BRIGHT_GREEN
11	BRIGHT_YELLOW
12	BRIGHT_BLUE
13	BRIGHT_MAGENTA
14	BRIGHT_CYAN
15	BRIGHT_WHITE