easy-ansi 0.3

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.

UPDATE: Windows 10 does have support for ANSI sequences, but you must turn it on. See below for details.

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 is instead dependent on the capabilities of the terminal / terminal software you use.
• This library does not depend on any other external libraries.
• The Windows 10 Command Prompt and PowerShell prompt do support ANSI codes, but you must enable it.
  1. Open up the Registry Editor
  2. Navigate to HKEY_CURRENT_USER\Console\
  3. Create an entry "VirtualTerminalLevel" if it does not exist.
  4. Set this entry to a DWORD value of 1.
• Other Windows terminal software will work with ANSI, such as Cygwin, Git Bash, PuTTY, etc.
• Linux / BSD will be the most supported environments for this library because of their first-class support of ANSI.
• I do not have a Mac of any kind to test Easy ANSI against, but because OS X is a BSD-based operating system, I assume Easy ANSI will work well on Apple computers.

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. You should always visually check your application.
  • Mixing color palettes on the same line does not seem to work.
  • Not every terminal supports every attribute. You can check how attributes will display in the demo program colors_demo.py.
• 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. The cursor will move to the beginning of the row cleared.	row: 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. The upper-left corner is 0, 0.	x: column y: row
locate_column(x)	Move the cursor to column x on the current line	x: column
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.
next_line(rows_down)	Move the cursor to the beginning of rows_down row (default = 1).	rows_down: The number of rows down to go to the beginning of.
previous_line(rows_up)	Move the cursor to the beginning of rows_up row (default = 1).	rows_up: The number of rows up to go to the beginning of.
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 the same as 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	Color Index	Color Name
0	BLACK	8	BRIGHT_BLACK
1	RED	9	BRIGHT_RED
2	GREEN	10	BRIGHT_GREEN
3	YELLOW	11	BRIGHT_YELLOW
4	BLUE	12	BRIGHT_BLUE
5	MAGENTA	13	BRIGHT_MAGENTA
6	CYAN	14	BRIGHT_CYAN
7	WHITE	15	BRIGHT_WHITE