XulbuX

Appearance

Ansi Module ​

Provides the S and Term classes for typed, operator-based terminal styling, as well as terminal cursor and screen control.

The Easy Styling ​

First, let's take a look at a small example of what a highly styled output could look like using this module:

python
S(
    ("First normal & unstyled text. ", (S.BOLD | S.UNDERLINE | S.BR.GREEN)("Bright green, bold, and underlined text.")),
    ((S.hex("#000") | S.BG.hex("#A8F"))("Black text with a purple background."), " And then ", S.ITALIC("(boring)"), " plain text again."),
    sep="\n",
).print()
terminal 
First normal & unstyled text. Bright green, bold, and underlined text.
Black text with a purple background. And then (boring) plain text again.

How all of this exactly works is explained in the sections below. 🠫

Styles and Groups ​

In this module, you apply styles and colors using S attributes.
Every style attribute supports two operators:

  • | combines two or more styles into a single immutable group, e.g., S.BOLD | S.RED → bold + red foreground
  • () applies the style (or group) to the given text and auto-resets the style after it, e.g., S.BOLD("hello") → bold "hello", reset back to normal afterwards (S.BOLD | S.RED)("hello") → same idea, combined

A list of all possible style attributes can be found below.

Auto Resetting Styles ​

Every _Style, _StyleGroup, _ColorStyle or _Link call automatically generates the matching reset sequence behind its text, just like shown in the following example:

python
S(
    ("This is plain text, ", S.BR.BLUE("which is bright blue now.")),
    "Now it was automatically reset to plain again.",
    sep="\n",
).print()
terminal 
This is plain text, which is bright blue now.
Now it was automatically reset to plain again.

Only the specific styles that were applied are reset; other styling in scope is left intact:

python
S.CYAN(
    "This is cyan text, ", S.DIM("which is dimmed now."),
    "\nNow it's not dimmed anymore but still cyan.",
).print()
terminal 
This is cyan text, which is dimmed now.
Now it's not dimmed anymore but still cyan.

Bare (Open-Only) Styles ​

Passing a style object without calling it emits only its opening ANSI sequence at that position, with no matching close/reset appended.
This is the typed equivalent of […] (open bracket without closing braces) from the legacy string syntax:

python
S(
    S.RED, "[ERROR] Something went wrong!",
    S.RESET, " Back to normal.",
).print()
terminal 
[ERROR] Something went wrong! Back to normal.

Any style type supports bare usage: S.RED (_Style), S.hex("#A8F") (_ColorStyle), S.link("url") (_Link), and S.BOLD | S.RED (_StyleGroup).
Bare styles can also appear inside tuples and nested calls:

python
S.ITALIC("a", S.MAGENTA, "B", S.RESET_FG, "c").print()
terminal 
aBc

Nesting and Multi-Segment Groups ​

A style call accepts either a single piece of text or any number of mixed segments.
Strings, S objects, bare style objects, and raw tuples can be mixed freely:

  • S.X("text") – Apply X to "text", auto-reset after.
  • S.X | S.Y – Combine X and Y into a single group.
  • (S.X | S.Y)("text") – Apply the group to "text".
  • S.X("a", S.Y("b"), "c") – Nested multi-segment: Y is applied only to "b".
  • S.X – Bare: emit only the opening sequence, no auto-reset.
  • ("a", S.X("b"), "c") – Same-line group; passed as a single tuple to S(…).

Inside S(*segments, sep="\n"), every positional argument is treated as one logical line and joined by sep.
An empty string argument "" therefore produces a blank line.

All Possible Style Attributes ​

  • Text styles:
    • S.BOLD
    • S.DIM
    • S.ITALIC
    • S.UNDERLINE
    • S.INVERSE
    • S.BLINK
    • S.HIDDEN
    • S.STRIKE
    • S.DOUBLE_UNDERLINE
  • Standard foreground colors:
    • S.BLACK, S.RED, S.GREEN, S.YELLOW, S.BLUE, S.MAGENTA, S.CYAN, S.WHITE
  • Bright foreground colors (S.BR.*):
    • S.BR.BLACK, S.BR.RED, S.BR.GREEN, …
  • Standard background colors (S.BG.*):
    • S.BG.BLACK, S.BG.RED, S.BG.GREEN, …
  • Bright background colors (S.BG.BR.*):
    • S.BG.BR.RED, S.BG.BR.GREEN, …
  • 24-bit true-color (foreground / background):
    • S.rgb(255, 96, 112)
    • S.hex("#FF6070") or S.hex("F67")
    • S.BG.rgb(0, 100, 255)
    • S.BG.hex("#0064FF") or S.BG.hex("06F")
  • 256-color palette (foreground / background):
    • S.color256(210)
    • S.BG.color256(69)
  • Hyperlinks (OSC 8):
    • S.link("https://example.com")("click here")
    • (S.link("…") | S.BR.BLUE)("click here")
  • Specific resets (only needed in advanced use; auto-reset usually covers it):
    • S.RESET_BOLD, S.RESET_DIM, S.RESET_ITALIC, S.RESET_UNDERLINE, S.RESET_BLINK, S.RESET_INVERSE, S.RESET_HIDDEN, S.RESET_STRIKE, S.RESET_FG, S.RESET_BG
  • Total reset (resets every previously applied styles):
    • S.RESET

Terminal Control – the Term class ​

Term exposes commonly used non-styling ANSI sequences for cursor- and screen-control.
These are plain strings (or string-returning helpers), so they can be passed directly into a S(…) call or written to sys.stdout:

  • CLEAR_LINE – Erase the entire current line.
  • CLEAR_LINE_TO_END – Erase from the cursor to the end of the line.
  • CLEAR_LINE_TO_START – Erase from the line start to the cursor.
  • CLEAR_SCREEN – Erase the whole screen.
  • CLEAR_SCREEN_TO_END – Erase from the cursor to the end of the screen.
  • CLEAR_SCREEN_TO_START – Erase from the screen start to the cursor.
  • CLEAR_SCROLLBACK – Erase the scrollback buffer.
  • CUR_HIDE / CUR_SHOW – Hide/show the cursor.
  • CUR_HOME – Move cursor to home position (0, 0).
  • CUR_SAVE / CUR_RESTORE – Save/restore cursor position (ANSI.SYS).
  • CUR_SAVE_DEC / CUR_RESTORE_DEC – Save/restore cursor position (DEC ESC 7/8).
  • ALT_SCREEN – Enter the alternate screen buffer.
  • MAIN_SCREEN – Leave the alternate screen buffer.
  • BELL – Terminal bell signal (\x07).
  • up(n) – Move the cursor up by n rows.
  • down(n) – Move the cursor down by n rows.
  • right(n) – Move the cursor right by n columns.
  • left(n) – Move the cursor left by n columns.
  • row(row) – Move the cursor to an absolute row position (1-based, VPA).
  • col(col) – Move the cursor to an absolute column position (1-based, CHA).
  • move(row, col) – Move the cursor to an absolute (row, col) position.
  • scroll_up(n) – Scroll page up by n lines.
  • scroll_down(n) – Scroll page down by n lines.
  • title(text) – Set the terminal window / tab title (OSC 2).
  • cursor_shape(shape) – Change cursor shape (DECSCUSR 1-6).
  • clipboard_copy(text) – Copy text to system clipboard via OSC 52.
  • cwd(path) – Notify terminal of current working directory via OSC 7.

ColorInput ​

python
type ColorInput = _ColorStyle | _Color256Style | _Style | _ColorBase | Rgba | Hsla | Hexa

Supported color representations for ANSI gradient styles.

GradientStop ​

python
type GradientStop = ColorInput | tuple[ColorInput, float | int]

A color stop for ANSI gradients: a color or a (color, position) tuple.

S ​

python
class S(self, /, *segments: Renderable, sep: str = "", _reset_codes: tuple[int, ...] = )

Build a styled string from a sequence of segments (strings, S objects, bare styles, or raw tuples), joined by sep, or use class-level style attributes and methods to apply ANSI styling.

  • segments – Any number of segments to render. Each positional argument represents one logical line.
  • sep – The separator inserted between two adjacent positional arguments (default "").

After construction the instance exposes:

  • ansi – The fully rendered ANSI escape string, ready to be written to a terminal.
  • raw – ansi with every ANSI escape sequence stripped (computed on demand).
  • code_positions – A tuple of (position, sequence) pairs giving the start offset of every ANSI escape sequence inside ansi (computed on demand).

Every style attribute supports | for combining and () for applying to text.

Example Usage ​

python
from xulbux import S

# Combine styles using operator `|`:
status = (S.BOLD | S.BR.GREEN)("SUCCESS")

# Nesting and joining styled items:
header = S(S.BOLD("Options: "), S(", ").join([S.CYAN("fast"), S.CYAN("safe")]))

# Direct terminal printing:
status.print()

.join() ​

python
def join(self, iterable: Iterable[Renderable], /) -> S

Join a sequence of segments using the current object as the separator.

  • iterable – The segments to join, e.g., a list of strings or S objects.

Example Usage ​

python
S(", ").join(["Apple", S.BOLD("Banana"), "Cherry"]).print()
terminal 
Apple, Banana, Cherry

.ljust() ​

python
def ljust(self, width: int, fill_char: Renderable = " ", /) -> S

Return the object left justified in a string of length width (visible chars).

  • width – The total visible width of the resulting string.
  • fill_char – The character to use for padding (default is a space).

Example Usage ​

python
S.RED("Text").ljust(10, ".").print()
terminal 
Text......

.rjust() ​

python
def rjust(self, width: int, fill_char: Renderable = " ", /) -> S

Return the object right justified in a string of length width (visible chars).

  • width – The total visible width of the resulting string.
  • fill_char – The character to use for padding (default is a space).

Example Usage ​

python
S.GREEN("Text").rjust(10, ".").print()
terminal 
......Text

.center() ​

python
def center(self, width: int, fill_char: Renderable = " ", /) -> S

Return the object centered in a string of length width (visible chars).

  • width – The total visible width of the resulting string.
  • fill_char – The character to use for padding (default is a space).

Example Usage ​

python
S.BOLD("Text").center(10, "-").print()
terminal 
---Text---

.wrap() ​

python
def wrap(self, width: int, /) -> list[S]

Wrap the object to fit within a given line width (in visible characters), preserving ANSI styling across all wrapped lines.

  • width – The maximum visible width of each line.

.print() ​

python
def print(self, /, *, end: str = "\n", flush: bool = True, file: TextIO | None = None) -> None

Write the rendered ANSI string straight to sys.stdout (configuring the terminal for ANSI on first use) or to a custom file-like object.

  • end – The string to append at the end of the output (default "\n").
  • flush – Whether to flush the output stream after writing (default True).
  • file – The file-like object to write to (default sys.stdout).

Example Usage ​

python
S.GREEN("Operation successful!").print()
terminal 
Operation successful!

.input() ​

python
def input(self, /, *, reset_ansi: bool = False) -> str

Use the rendered ANSI string as an input prompt and return the user's input.

  • reset_ansi – If true, all ANSI styling will be reset after the user confirmed the input and the program continues to run.

Example Usage ​

python
S.BOLD("Enter value: ").input()
terminal 
Enter value:

.RESET ​

python
RESET: ClassVar[_Style] = _Style(0)

Reset all styling to default.

.RESET_BOLD ​

python
RESET_BOLD: ClassVar[_Style] = _Style(22)

Reset bold (also resets dim, as they share the same code).

.RESET_DIM ​

python
RESET_DIM: ClassVar[_Style] = _Style(22)

Reset dim (also resets bold, as they share the same code).

.RESET_ITALIC ​

python
RESET_ITALIC: ClassVar[_Style] = _Style(23)

Reset italic.

.RESET_UNDERLINE ​

python
RESET_UNDERLINE: ClassVar[_Style] = _Style(24)

Reset underline and double underline.

.RESET_INVERSE ​

python
RESET_INVERSE: ClassVar[_Style] = _Style(27)

Reset inverse.

.RESET_HIDDEN ​

python
RESET_HIDDEN: ClassVar[_Style] = _Style(28)

Reset hidden.

.RESET_STRIKETHROUGH ​

python
RESET_STRIKETHROUGH: ClassVar[_Style] = _Style(29)

Reset strikethrough.

python
RESET_BLINK: ClassVar[_Style] = _Style(25)

Reset blink.

.RESET_FG ​

python
RESET_FG: ClassVar[_Style] = _Style(39)

Reset foreground color.

.RESET_BG ​

python
RESET_BG: ClassVar[_Style] = _Style(49)

Reset background color.

.BOLD ​

python
BOLD: ClassVar[_Style] = _Style(1)

Bold text.

Note that this is also reset by RESET_DIM.

.DIM ​

python
DIM: ClassVar[_Style] = _Style(2)

Dim text.

Note that this is also reset by RESET_BOLD.

.ITALIC ​

python
ITALIC: ClassVar[_Style] = _Style(3)

Italic text.

.UNDERLINE ​

python
UNDERLINE: ClassVar[_Style] = _Style(4)

Underline text.

python
BLINK: ClassVar[_Style] = _Style(5)

Blinking text.

.INVERSE ​

python
INVERSE: ClassVar[_Style] = _Style(7)

Inverse colors (swap foreground and background colors).

.HIDDEN ​

python
HIDDEN: ClassVar[_Style] = _Style(8)

Hidden (invisible) text.

.STRIKETHROUGH ​

python
STRIKETHROUGH: ClassVar[_Style] = _Style(9)

Strikethrough text.

.DOUBLE_UNDERLINE ​

python
DOUBLE_UNDERLINE: ClassVar[_Style] = _Style(21)

Double underline text.

.BLACK ​

python
BLACK: ClassVar[_FgStyle] = _FgStyle(30)

Black foreground.

.RED ​

python
RED: ClassVar[_FgStyle] = _FgStyle(31)

Red foreground.

.GREEN ​

python
GREEN: ClassVar[_FgStyle] = _FgStyle(32)

Green foreground.

.YELLOW ​

python
YELLOW: ClassVar[_FgStyle] = _FgStyle(33)

Yellow foreground.

.BLUE ​

python
BLUE: ClassVar[_FgStyle] = _FgStyle(34)

Blue foreground.

.MAGENTA ​

python
MAGENTA: ClassVar[_FgStyle] = _FgStyle(35)

Magenta foreground.

.CYAN ​

python
CYAN: ClassVar[_FgStyle] = _FgStyle(36)

Cyan foreground.

.WHITE ​

python
WHITE: ClassVar[_FgStyle] = _FgStyle(37)

Bright white foreground.

.BR ​

python
BR: ClassVar[type[_BrNS]] = _BrNS

.BG ​

python
BG: ClassVar[type[_BgNS]] = _BgNS

.rgb() ​

python
def rgb(*args: Any) -> _FgColorStyle

24-bit foreground color from RGB components or an rgba object.

S.rgb(170, 136, 255)("text") or S.rgb(my_rgba)("text")

.hex() ​

python
def hex(color: str | int | hexa, /) -> _FgColorStyle

24-bit foreground color from hex string, hex integer, or hexa object.

S.hex("#A8F")("text"), S.hex(0xAA88FF), or S.hex(my_hexa)("text")

.color256() ​

python
def color256(code: int, /) -> _FgColor256Style

256-color palette foreground color (code in range [0, 255] inclusive).

S.color256(196)("text")

python
def link(url: str | Path, /) -> _Link

Clickable hyperlink. Accepts strings or pathlib.Path objects.
If a pathlib.Path is passed, it is automatically resolved and converted to a URI.

python
>>> S.link("https://example.com")("click here")
>>> S.link(Path("docs/readme.md"))("open file")

.gradient() ​

python
def gradient(
        *colors: GradientStop | Sequence[GradientStop],
        angle: float | int = 0.0,
        space: Literal["rgb", "hsl", "hsl_long", "linear_rgb", "oklab"] = "hsl",
        granularity: Literal["char", "word", "line"] = "char",
        skip_whitespace: bool = True,
        cell_aspect_ratio: float = 2.0,
        color_depth: Literal["truecolor", "256", "auto"] = "auto",
    ) -> _GradientStyle

Create a gradient style that smoothly transitions colors across text or terminal blocks.

  • colors – Sequence of colors or (color, position) tuples defining the gradient stops.
  • angle – Direction angle in degrees (0.0 = left-to-right, 90.0 = top-to-bottom, 180.0 = right-to-left, 270.0 = bottom-to-top, 45.0 = top-left to bottom-right).
  • space – Color space to interpolate in ("rgb", "hsl", "hsl_long", "linear_rgb", or "oklab"). Default is "hsl".
  • granularity – Coloring granularity ("char", "word", or "line").
  • skip_whitespace – Whether to skip emitting color escape sequences over whitespace.
  • cell_aspect_ratio – Font cell aspect ratio for 2D geometry correction (default 2.0).
  • color_depth – Color mode ("truecolor", "256", or "auto").

Raises ValueError if colors is empty or any option is invalid.

FgColorStyle ​

python
type FgColorStyle = _FgStyle | _FgColorStyle | _FgColor256Style

A single foreground color style code (e.g., S.RED, S.BR.BLUE, S.hex("#A8F"), S.color256(196)).
Excludes background colors and non-color styles like S.BOLD.

is_fg_color_style() ​

python
def is_fg_color_style(obj: object, /) -> TypeIs[FgColorStyle]

Returns true if obj is an instance that matches the FgColorStyle type.

BgColorStyle ​

python
type BgColorStyle = _BgStyle | _BgColorStyle | _BgColor256Style

A single background color style code (e.g., S.BG.RED, S.BG.hex("#A8F"), S.BG.color256(196)).
Excludes foreground colors and non-color styles like S.BOLD.

is_bg_color_style() ​

python
def is_bg_color_style(obj: object, /) -> TypeIs[BgColorStyle]

Returns true if obj is an instance that matches the BgColorStyle type.

ColorStyle ​

python
type ColorStyle = FgColorStyle | BgColorStyle

Any single foreground or background color style code (e.g., S.RED, S.BG.BLUE, S.hex("#A8F")).
Excludes non-color styles like S.BOLD.

is_color_style() ​

python
def is_color_style(obj: object, /) -> TypeIs[ColorStyle]

Returns true if obj is an instance that matches the ColorStyle type.

BaseStyle ​

python
type BaseStyle = _Style | _ColorStyle | _Color256Style | _GradientStyle | _Link

Any single style code, color style, link, or gradient style that can be combined via | and applied to text.

is_base_style() ​

python
def is_base_style(obj: object, /) -> TypeIs[BaseStyle]

Returns true if obj is an instance that matches the BaseStyle type.

AnyStyle ​

python
type AnyStyle = BaseStyle | _StyleGroup

Any single style or group of styles that can be combined via | and applied to text.

is_any_style() ​

python
def is_any_style(obj: object, /) -> TypeIs[AnyStyle]

Returns true if obj is an instance that matches the AnyStyle type.

TextSegment ​

python
type TextSegment = str | S

A single segment that contains actual text: a plain string or a styled S object.
Strictly excludes bare style objects (e.g., S.RED, S.BOLD | S.BLUE) that do not contain text.

is_text_segment() ​

python
def is_text_segment(obj: object, /) -> TypeIs[TextSegment]

Returns true if obj is an instance that matches the TextSegment type (has actual text).

RenderSegment ​

python
type RenderSegment = str | _SBase

A single segment: a plain string, a bare style object (open-only), or a styled S object.

is_render_segment() ​

python
def is_render_segment(obj: object, /) -> TypeIs[RenderSegment]

Returns true if obj is an instance that matches the RenderSegment type.

TextRenderable ​

python
type TextRenderable = TextSegment | tuple[TextRenderable, ...]

Anything that contains actual textual content to be rendered, strictly excluding bare styles.
Can be passed to a _Style call, or as a positional argument to S(…). Can be arbitrarily nested in tuples.

is_text_renderable() ​

python
def is_text_renderable(obj: object, /) -> TypeIs[TextRenderable]

Returns true if obj is an instance that matches the TextRenderable type.

Renderable ​

python
type Renderable = RenderSegment | tuple[Renderable, ...]

Anything that can be styled or rendered.
Can be passed to a _Style call, or as a positional argument to S(…). Can be arbitrarily nested in tuples.

is_renderable() ​

python
def is_renderable(obj: object, /) -> TypeIs[Renderable]

Returns true if obj is an instance that matches the Renderable type.

Term ​

python
class Term

Common ANSI terminal control sequences (cursor, screen, title, clipboard, modes) as plain strings or string-returning static methods.

Values can be passed straight into an S(…) call or written to sys.stdout.

Example Usage ​

python
import sys
from xulbux import Term

# Switch to alternate screen and hide cursor:
sys.stdout.write(Term.ALT_SCREEN + Term.CUR_HIDE)
sys.stdout.flush()

# Move cursor up 2 rows and clear line:
sys.stdout.write(Term.up(2) + Term.CLEAR_LINE)
sys.stdout.flush()

# Restore main screen and cursor:
sys.stdout.write(Term.CUR_SHOW + Term.MAIN_SCREEN)
sys.stdout.flush()

.BELL ​

python
BELL: ClassVar[str] = "\x07"

Terminal bell character to trigger an audio or visual alert.

.CLEAR_LINE ​

python
CLEAR_LINE: ClassVar[str] = "\x1b[2K"

Erase the entire current line.

.CLEAR_LINE_TO_END ​

python
CLEAR_LINE_TO_END: ClassVar[str] = "\x1b[0K"

Erase from the cursor to the end of the current line.

.CLEAR_LINE_TO_START ​

python
CLEAR_LINE_TO_START: ClassVar[str] = "\x1b[1K"

Erase from the beginning of the line up to the cursor.

.CLEAR_SCREEN ​

python
CLEAR_SCREEN: ClassVar[str] = "\x1b[2J"

Erase the whole screen.

.CLEAR_SCREEN_TO_END ​

python
CLEAR_SCREEN_TO_END: ClassVar[str] = "\x1b[0J"

Erase from the cursor to the end of the screen.

.CLEAR_SCREEN_TO_START ​

python
CLEAR_SCREEN_TO_START: ClassVar[str] = "\x1b[1J"

Erase from the beginning of the screen up to the cursor.

.CLEAR_SCROLLBACK ​

python
CLEAR_SCROLLBACK: ClassVar[str] = "\x1b[3J"

Erase the terminal scrollback history buffer.

.CUR_HIDE ​

python
CUR_HIDE: ClassVar[str] = "\x1b[?25l"

Hide the cursor.

.CUR_SHOW ​

python
CUR_SHOW: ClassVar[str] = "\x1b[?25h"

Show the cursor.

.CUR_HOME ​

python
CUR_HOME: ClassVar[str] = "\x1b[H"

Move the cursor to the home position (0,0) (CUP/HVP).

.CUR_SAVE ​

python
CUR_SAVE: ClassVar[str] = "\x1b[s"

Save the current cursor position (ANSI.SYS / SCO).

.CUR_RESTORE ​

python
CUR_RESTORE: ClassVar[str] = "\x1b[u"

Restore the previously saved cursor position (ANSI.SYS / SCO).

.CUR_SAVE_DEC ​

python
CUR_SAVE_DEC: ClassVar[str] = "\x1b7"

Save cursor position and attributes (DEC private sequence ESC 7).

.CUR_RESTORE_DEC ​

python
CUR_RESTORE_DEC: ClassVar[str] = "\x1b8"

Restore cursor position and attributes (DEC private sequence ESC 8).

.ALT_SCREEN ​

python
ALT_SCREEN: ClassVar[str] = "\x1b[?1049h"

Enter the alternate screen buffer.

.MAIN_SCREEN ​

python
MAIN_SCREEN: ClassVar[str] = "\x1b[?1049l"

Leave the alternate screen buffer.

.BRACKETED_PASTE_ENABLE ​

python
BRACKETED_PASTE_ENABLE: ClassVar[str] = "\x1b[?2004h"

Enable bracketed paste mode (wraps pasted text in paste brackets).

.BRACKETED_PASTE_DISABLE ​

python
BRACKETED_PASTE_DISABLE: ClassVar[str] = "\x1b[?2004l"

Disable bracketed paste mode.

.LINE_WRAP_ENABLE ​

python
LINE_WRAP_ENABLE: ClassVar[str] = "\x1b[?7h"

Enable line wrapping (DECAWM).

.LINE_WRAP_DISABLE ​

python
LINE_WRAP_DISABLE: ClassVar[str] = "\x1b[?7l"

Disable line wrapping (DECAWM).

.RESET ​

python
RESET: ClassVar[str] = "\x1bc"

Hard reset to initial state (RIS).

.SOFT_RESET ​

python
SOFT_RESET: ClassVar[str] = "\x1b[!p"

Soft terminal reset to sensible defaults (DECSTR).

.up() ​

python
def up(n: int = 1, /) -> str

Move the cursor up by n rows.

.down() ​

python
def down(n: int = 1, /) -> str

Move the cursor down by n rows.

.left() ​

python
def left(n: int = 1, /) -> str

Move the cursor left by n columns.

python
def right(n: int = 1, /) -> str

Move the cursor right by n columns.

.prev_line() ​

python
def prev_line(n: int = 1, /) -> str

Move the cursor to the beginning of the previous line, n lines up.

.next_line() ​

python
def next_line(n: int = 1, /) -> str

Move the cursor to the beginning of the next line, n lines down.

.row() ​

python
def row(row: int = 1, /) -> str

Move the cursor to absolute row row in the current column (1-based, VPA).

.col() ​

python
def col(col: int = 1, /) -> str

Move the cursor to absolute column col in the current row (1-based, CHA).

.move() ​

python
def move(row: int, col: int, /) -> str

Move the cursor to absolute position (row, col) (1-based, CUP).

.insert_lines() ​

python
def insert_lines(n: int = 1, /) -> str

Insert n blank lines at the current row (IL).

.delete_lines() ​

python
def delete_lines(n: int = 1, /) -> str

Delete n lines starting from the current row (DL).

.insert_chars() ​

python
def insert_chars(n: int = 1, /) -> str

Insert n blank characters at the current cursor position (ICH).

.delete_chars() ​

python
def delete_chars(n: int = 1, /) -> str

Delete n characters at the current cursor position (DCH).

.scroll_up() ​

python
def scroll_up(n: int = 1, /) -> str

Scroll page up by n lines.

.scroll_down() ​

python
def scroll_down(n: int = 1, /) -> str

Scroll page down by n lines.

.title() ​

python
def title(text: str, /) -> str

Set the terminal window / tab title (OSC 2).

.cursor_shape() ​

python
def cursor_shape(
        shape: Literal[
            1,
            2,
            3,
            4,
            5,
            6,
            "blinking_block",
            "steady_block",
            "blinking_underline",
            "steady_underline",
            "blinking_bar",
            "steady_bar",
        ],
        /,
    ) -> str

Set the terminal cursor shape (DECSCUSR).

  • shape – An integer in range [1, 6] inclusive, or a string name of the shape:
    • 1 "blinking_block"
    • 2 "steady_block"
    • 3 "blinking_underline"
    • 4 "steady_underline"
    • 5 "blinking_bar"
    • 6 "steady_bar"

.clipboard_copy() ​

python
def clipboard_copy(text: str, /) -> str

Copy text to the system clipboard (OSC 52).

.cwd() ​

python
def cwd(path: str | Path, /) -> str

Notify the terminal of the current working directory (OSC 7).

Released under the MIT License.

✨ From XulbuX ✨