Welcome to Ansirithm, a lightweight Python utility for generating ANSI escape sequences for terminal styling, cursor control, screen manipulation, and text decoration.
Ansirithm provides a small collection of enums and helper functionality for constructing ANSI escape sequences without requiring raw escape-code strings throughout your application.
Ansirithm provides several conveniences:
- Foreground colors through
ForegroundColor. - Background colors through
BackgroundColor. - Font styles such as bold, faint, and italic.
- Text decorators including underline, strike-through, and overline.
- Terminal effects such as blinking, reverse video, and hidden text.
- Cursor movement through directional ANSI sequences.
- Cursor visibility control for hiding and showing the terminal cursor.
- Line navigation for moving between terminal lines.
- Screen and line erasing through standard ANSI erase sequences.
- Cursor teleportation for home, save, and restore operations.
- Automatic ANSI sequence construction through
Ansi.ansi(). - Context-managed reset behavior through
Ansi.reset.
Ansirithm intentionally keeps ANSI terminal control explicit while providing readable names for otherwise mysterious numerical escape codes.
It is designed for programmers who would rather write:
Ansi.ansi(ForegroundColor.RED)than remember that red is apparently 31.
Because naturally terminals require a secret numerical language to change the color of text.
Ansirithm uses Python's standard library and does not require external dependencies.
Import the required classes from the Ansirithm module.
from ansirithm import (
Ansi,
ForegroundColor,
BackgroundColor,
Fonts,
Decorators,
Effects,
Reset,
CursorMovement,
CursorVisibility,
LineNavigation,
Erasing,
Teleportation,
)Replace ansirithm with the module path used by your installation.
Ansirithm generates standard ANSI escape sequences that can be written directly to terminal output.
The primary interface for generating escape sequences is:
Ansi.ansi(*codes)The method accepts any number of ANSI style codes or action strings.
Example:
print(
Ansi.ansi(ForegroundColor.RED)
+ "Hello"
+ Ansi.ansi(Reset.RESET)
)This produces red text followed by a terminal style reset.
Multiple codes can be combined in a single call.
Ansi.ansi(
ForegroundColor.RED,
Fonts.BOLD
)The resulting sequence applies both styles.
Ansirithm separates ANSI codes into several categories according to their purpose.
Styling codes are integer-based ANSI SGR values.
They include:
- Foreground colors.
- Background colors.
- Fonts.
- Decorations.
- Effects.
- Reset operations.
These codes are combined into a single SGR escape sequence.
Action codes are string-based ANSI escape sequences used for terminal operations such as:
- Cursor movement.
- Cursor visibility.
- Line navigation.
- Screen erasing.
- Cursor positioning.
These sequences are emitted individually.
The ForegroundColor enum provides standard ANSI foreground colors.
| Color | ANSI Code |
|---|---|
BLACK |
30 |
RED |
31 |
GREEN |
32 |
YELLOW |
33 |
BLUE |
34 |
MAGENTA |
35 |
CYAN |
36 |
WHITE |
37 |
print(
Ansi.ansi(ForegroundColor.RED)
+ "Red text"
+ Ansi.ansi(Reset.RESET)
)Multiple styles can be combined:
print(
Ansi.ansi(
ForegroundColor.GREEN,
Fonts.BOLD
)
+ "Bold green text"
+ Ansi.ansi(Reset.RESET)
)The color remains active until another ANSI style sequence changes it or the terminal is reset.
Terminals, like humans, occasionally need to be explicitly told when something is over.
The BackgroundColor enum provides standard ANSI background colors.
| Color | ANSI Code |
|---|---|
BLACK |
40 |
RED |
41 |
GREEN |
42 |
YELLOW |
43 |
BLUE |
44 |
MAGENTA |
45 |
CYAN |
46 |
WHITE |
47 |
print(
Ansi.ansi(BackgroundColor.BLUE)
+ "Blue background"
+ Ansi.ansi(Reset.RESET)
)Foreground and background colors can be combined.
print(
Ansi.ansi(
ForegroundColor.WHITE,
BackgroundColor.BLUE
)
+ "White on blue"
+ Ansi.ansi(Reset.RESET)
)The Fonts enum provides common ANSI text styles.
| Style | ANSI Code |
|---|---|
BOLD |
1 |
FAINT |
2 |
ITALIC |
3 |
print(
Ansi.ansi(Fonts.BOLD)
+ "Bold text"
+ Ansi.ansi(Reset.RESET)
)Multiple font-related styles may be supplied together.
Ansi.ansi(
Fonts.BOLD,
Fonts.ITALIC
)Terminal support for individual styles may vary depending on the terminal emulator.
ANSI is a standard.
Terminal behavior is apparently more of a suggestion.
The Decorators enum provides ANSI text decoration codes.
| Decorator | ANSI Code |
|---|---|
UNDERLINE |
4 |
DOUBLE_UNDERLINE |
21 |
STRIKE |
9 |
OVERLINE |
53 |
print(
Ansi.ansi(Decorators.UNDERLINE)
+ "Underlined text"
+ Ansi.ansi(Reset.RESET)
)Decorators can be combined with colors and fonts.
print(
Ansi.ansi(
ForegroundColor.CYAN,
Fonts.BOLD,
Decorators.UNDERLINE
)
+ "Styled text"
+ Ansi.ansi(Reset.RESET)
)The Effects enum provides ANSI terminal effects.
| Effect | ANSI Code |
|---|---|
BLINK |
5 |
REVERSE |
7 |
HIDDEN |
8 |
print(
Ansi.ansi(Effects.REVERSE)
+ "Reverse video"
+ Ansi.ansi(Reset.RESET)
)Blinking behavior depends on terminal support.
The HIDDEN effect is commonly used for concealing terminal text, although terminal behavior can vary.
The Reset enum currently provides a single reset operation.
| Operation | ANSI Code |
|---|---|
RESET |
0 |
Use it to return terminal styling to its default state.
print(
Ansi.ansi(ForegroundColor.RED)
+ "Red"
+ Ansi.ansi(Reset.RESET)
+ " Normal"
)The reset sequence prevents styles from unintentionally affecting subsequent output.
This is particularly important when writing reusable terminal applications.
Otherwise your entire terminal may suddenly become red because one line of code got ambitious.
The CursorMovement enum provides directional cursor movement sequences.
| Direction | ANSI Command |
|---|---|
UP |
A |
DOWN |
B |
RIGHT |
C |
LEFT |
D |
These commands are represented as ANSI CSI sequences.
print(
Ansi.ansi(
CursorMovement.UP.value
)
)The cursor movement command itself does not specify a distance.
ANSI interprets an omitted movement parameter according to its standard default behavior.
The CursorVisibility enum controls whether the terminal cursor is visible.
| Operation | ANSI Sequence |
|---|---|
HIDE |
?25l |
SHOW |
?25h |
print(
Ansi.ansi(
CursorVisibility.HIDE.value
),
end=""
)print(
Ansi.ansi(
CursorVisibility.SHOW.value
),
end=""
)Cursor visibility control is useful for terminal interfaces, animations, progress displays, and other applications where a blinking cursor wandering around the screen would be less than helpful.
The LineNavigation enum provides ANSI sequences for moving between terminal lines.
| Operation | ANSI Command |
|---|---|
NEXT |
E |
PREV |
F |
print(
Ansi.ansi(
LineNavigation.NEXT.value
)
)The commands are emitted as ANSI CSI sequences by Ansi.ansi().
The Erasing enum provides ANSI commands for clearing terminal content.
| Operation | ANSI Command |
|---|---|
SCREEN |
2J |
SCROLL |
3J |
LINE |
K |
TO_START |
1K |
print(
Ansi.ansi(
Erasing.SCREEN.value
),
end=""
)print(
Ansi.ansi(
Erasing.LINE.value
),
end=""
)print(
Ansi.ansi(
Erasing.TO_START.value
),
end=""
)These operations allow terminal applications to manipulate visible output without relying exclusively on ordinary newline-based printing.
The Teleportation enum provides cursor-positioning and cursor-state commands.
| Operation | ANSI Command |
|---|---|
HOME |
H |
SAVE |
s |
RESTORE |
u |
The HOME sequence moves the cursor to the terminal's home position.
print(
Ansi.ansi(
Teleportation.HOME.value
),
end=""
)print(
Ansi.ansi(
Teleportation.SAVE.value
),
end=""
)print(
Ansi.ansi(
Teleportation.RESTORE.value
),
end=""
)Saving and restoring cursor position can be useful when temporarily writing terminal output and then returning to the previous cursor location.
A surprisingly useful ability for something that sounds like a science-fiction feature.
Multiple integer-based ANSI styles can be passed to Ansi.ansi() at once.
style = Ansi.ansi(
ForegroundColor.YELLOW,
BackgroundColor.BLUE,
Fonts.BOLD,
Decorators.UNDERLINE
)
print(
style
+ "Important message"
+ Ansi.ansi(Reset.RESET)
)All integer codes are combined into a single ANSI SGR sequence.
Conceptually, the generated sequence is equivalent to:
ESC[33;44;1;4m
followed by the provided text and then a reset sequence.
This allows complex terminal styling without manually constructing ANSI escape strings.
Ansi.ansi() also accepts lists and tuples.
For example:
styles = [
ForegroundColor.CYAN,
Fonts.BOLD,
Decorators.UNDERLINE
]
print(
Ansi.ansi(styles)
+ "Styled text"
+ Ansi.ansi(Reset.RESET)
)Nested collections can also be supplied alongside individual codes.
styles = [
ForegroundColor.GREEN,
Fonts.BOLD
]
Ansi.ansi(
styles,
Decorators.UNDERLINE
)Lists and tuples are flattened by one level before processing.
This makes it possible to construct reusable style collections.
Ansi.ansi() ignores None values.
This allows conditional styling to be constructed conveniently.
color = ForegroundColor.RED
optional_style = None
sequence = Ansi.ansi(
color,
optional_style,
Fonts.BOLD
)The None value is simply omitted.
This is useful when building terminal styles dynamically.
If no usable codes are supplied, Ansi.ansi() returns an empty string.
Ansi.ansi()Result:
""
Likewise:
Ansi.ansi(None, [], ())produces an empty string.
This allows ANSI sequence generation to safely participate in conditional formatting without requiring special handling for every empty case.
Ansirithm provides a small context manager through:
Ansi.resetThe object can be used with Python's with statement.
with Ansi.reset():
print("Styled output")The context manager's __enter__() method returns Ansi.ansi.
When the context exits, the reset sequence is printed automatically.
The intended purpose is to make temporary terminal styling easier to manage.
with Ansi.reset() as ansi:
print(
ansi(
ForegroundColor.RED,
Fonts.BOLD
)
+ "Temporary style"
)After the block completes, Ansirithm emits:
ESC[0m
This ensures the terminal returns to its default styling state.
No cleanup code required.
Because forgetting to reset terminal colors is how innocent shell sessions become crime scenes.
Ansirithm provides a predefined clear sequence.
Ansi.clearThe value is:
ESC[2J ESC[H
In Python:
print(Ansi.clear, end="")This performs two operations:
- Clears the terminal screen.
- Moves the cursor to the home position.
The sequence can therefore be used as a convenient terminal-clearing operation.
The following example demonstrates colors, fonts, decorations, resetting, and cursor control.
from ansirithm import (
Ansi,
ForegroundColor,
BackgroundColor,
Fonts,
Decorators,
Reset,
)
title = Ansi.ansi(
ForegroundColor.CYAN,
Fonts.BOLD,
Decorators.UNDERLINE
)
warning = Ansi.ansi(
ForegroundColor.YELLOW,
BackgroundColor.RED,
Fonts.BOLD
)
print(
title
+ "Ansirithm"
+ Ansi.ansi(Reset.RESET)
)
print(
warning
+ "Warning"
+ Ansi.ansi(Reset.RESET)
)
print("Normal terminal output.")The program demonstrates the basic Ansirithm workflow:
- Construct an ANSI style.
- Print styled text.
- Reset the terminal style.
- Continue with normal output.
The following example demonstrates cursor visibility, screen clearing, and cursor positioning.
from ansirithm import (
Ansi,
CursorVisibility,
Erasing,
Teleportation,
)
# Hide the cursor
print(
Ansi.ansi(CursorVisibility.HIDE.value),
end=""
)
# Clear the screen
print(
Ansi.ansi(Erasing.SCREEN.value),
end=""
)
# Move to the home position
print(
Ansi.ansi(Teleportation.HOME.value),
end=""
)
print("Ansirithm terminal demo")
# Restore cursor visibility
print(
Ansi.ansi(CursorVisibility.SHOW.value),
end=""
)This demonstrates how Ansirithm can be used for simple terminal interfaces and screen-based applications.
Because Ansi.ansi() accepts collections and optional values, styles can be assembled dynamically.
from ansirithm import (
Ansi,
ForegroundColor,
Fonts,
Decorators,
)
styles = [
ForegroundColor.MAGENTA,
Fonts.BOLD,
]
underline = Decorators.UNDERLINE
sequence = Ansi.ansi(
styles,
underline
)
print(
sequence
+ "Dynamic styling"
+ Ansi.ansi(0)
)This approach makes it possible to construct reusable terminal themes.
For example:
SUCCESS = Ansi.ansi(
ForegroundColor.GREEN,
Fonts.BOLD
)
ERROR = Ansi.ansi(
ForegroundColor.RED,
Fonts.BOLD
)
INFO = Ansi.ansi(
ForegroundColor.CYAN
)These styles can then be reused throughout an application.
ForegroundColor.BLACK
ForegroundColor.RED
ForegroundColor.GREEN
ForegroundColor.YELLOW
ForegroundColor.BLUE
ForegroundColor.MAGENTA
ForegroundColor.CYAN
ForegroundColor.WHITEBackgroundColor.BLACK
BackgroundColor.RED
BackgroundColor.GREEN
BackgroundColor.YELLOW
BackgroundColor.BLUE
BackgroundColor.MAGENTA
BackgroundColor.CYAN
BackgroundColor.WHITEFonts.BOLD
Fonts.FAINT
Fonts.ITALICDecorators.UNDERLINE
Decorators.DOUBLE_UNDERLINE
Decorators.STRIKE
Decorators.OVERLINEEffects.BLINK
Effects.REVERSE
Effects.HIDDENReset.RESETCursorMovement.UP
CursorMovement.DOWN
CursorMovement.RIGHT
CursorMovement.LEFTCursorVisibility.HIDE
CursorVisibility.SHOWLineNavigation.NEXT
LineNavigation.PREVErasing.SCREEN
Erasing.SCROLL
Erasing.LINE
Erasing.TO_STARTTeleportation.HOME
Teleportation.SAVE
Teleportation.RESTOREAnsi.ansi(*codes)
Ansi.reset
Ansi.clearAnsirithm is designed to provide a readable Python interface over standard ANSI terminal escape sequences.
The library deliberately represents ANSI codes using named enums rather than requiring users to memorize numerical constants and control sequences.
The architecture separates terminal functionality into logical categories:
ForegroundColorhandles text color.BackgroundColorhandles background color.Fontshandles font-style attributes.Decoratorshandles text decorations.Effectshandles terminal effects.Resethandles style reset operations.CursorMovementhandles directional cursor movement.CursorVisibilityhandles cursor visibility.LineNavigationhandles line-based cursor navigation.Erasinghandles terminal content removal.Teleportationhandles cursor positioning and position storage.
Ansi.ansi() then provides the common mechanism for converting these values into actual ANSI escape sequences.
Ansirithm does not attempt to replace terminal emulators or implement a terminal itself.
It simply makes the existing ANSI control system less unpleasant to use.
Which, frankly, is already a respectable contribution to civilization.
Ansirithm is intentionally lightweight and currently provides only a subset of ANSI terminal functionality.
The current implementation does not provide:
- 256-color support.
- True-color RGB sequences.
- Cursor positioning with arbitrary row and column parameters.
- Terminal input handling.
- Keyboard event parsing.
- Terminal size detection.
- Platform-specific console APIs.
- Automatic terminal capability detection.
- Automatic ANSI disabling for unsupported terminals.
- Full ANSI/ECMA-48 sequence coverage.
Terminal support for individual effects may vary between terminal emulators.
The library generates ANSI sequences but does not verify whether the receiving terminal supports them.
A compact Ansirithm program can therefore look like this:
from ansirithm import (
Ansi,
ForegroundColor,
Fonts,
Decorators,
Reset,
)
style = Ansi.ansi(
ForegroundColor.CYAN,
Fonts.BOLD,
Decorators.UNDERLINE
)
print(
style
+ "Hello from Ansirithm"
+ Ansi.ansi(Reset.RESET)
)Output:
Hello from Ansirithm
The terminal handles the actual styling through ANSI escape sequences.
Ansirithm simply provides names for the machinery.
Because apparently \033[36;1;4m was considered a perfectly reasonable user interface.