Package sista

Memory-safe and OS-agnostic library for making terminal videogames and animations

Functions

def clear_screen(...)

Clear the terminal and reposition the cursor to top-left.

Parameters

  • spaces (bool, optional):
  • True (default): clear visible content and scrollback buffer.
  • False: only reposition cursor to top-left.

Raises

  • RuntimeError: if the underlying API reports a failure.
def create_ansi_settings(...)

Create an ANSI settings object and return it as a capsule.

create_ansi_settings(fgcolor=F_WHITE, bgcolor=B_BLACK, attribute=A_RESET) -> Capsule

Parameters

  • fgcolor (int): Foreground color (one of the F_* constants).
  • bgcolor (int): Background color (one of the B_* constants).
  • attribute (int): Text attribute (one of the A_* constants).

Returns

  • Capsule wrapping the ANSISettings handler.
def create_border(...)

Create a Border object that uses a single-character symbol and ANSI settings.

Parameters

  • symbol (str): Single character string used to draw border bricks.
  • ansi_settings (Capsule): Capsule returned by create_ansi_settings().

Returns

  • Capsule wrapping the Border handler.
def create_coordinates(...)

Create a Coordinates object and return it as a capsule.

Parameters

  • y (int): Row index.
  • x (int): Column index.

Returns

  • Capsule wrapping a Coordinates struct.
def print(...)

Print a message to the terminal using Sista's configured output stream.

Parameters

  • message (str): Message to print (a single text line).
def reset_ansi(...)

Reset all ANSI text attributes and colors to the terminal defaults.

Raises RuntimeError if the underlying API reports a failure.

def reset_attribute(...)

Disable/reset a terminal text attribute using one of the A_* constants.

Parameters

  • attribute (int): One of the A_* constants (e.g. A_RESET).
def set_attribute(...)

Enable a terminal text attribute using one of the A_* constants.

Parameters

  • attribute (int): One of the A_* constants (e.g. A_UNDERLINE).
def set_background_color(...)

Set the terminal background color using one of the B_* constants.

Parameters

  • color (int): One of the B_* constants (e.g. B_BLUE).
def set_foreground_color(...)

Set the terminal foreground color using one of the F_* constants.

Parameters

  • color (int): One of the F_* constants (e.g. F_RED).

Classes

class Cursor (*args, **kwargs)

Class representing a terminal cursor for movement operations.

Create with Cursor.

Provides: move, go_to, go_to_coordinates.

Methods

def go_to(...)

Move the cursor to the absolute (y, x) position.

Parameters

  • y (int): Row index to move to.
  • x (int): Column index to move to.
def go_to_coordinates(...)

Move the cursor to the position described by a Coordinates capsule.

Parameters

def move(...)

Move the cursor in the specified direction by the given amount.

Parameters

  • direction (int): One of the DIRECTION_* constants.
  • amount (int): Number of positions to move the cursor.
class Field (*args, **kwargs)

Class representing a terminal Field for pawns and borders.

Create with Field(width: int, height: int).

Provides: create_pawn, move_pawn, print_with_border.

Methods

def create_pawn(...)

Create a Pawn inside this Field and return a Pawn object.

Parameters

Returns

def move_pawn(...)

Move a pawn inside this Field.

Parameters

  • pawn (Pawn): Pawn object to move.
  • y (int): Y coordinate of the destination.
  • x (int): X coordinate of the destination.

Raises

  • IndexError: destination is out of bounds.
  • RuntimeError: destination is occupied or another API error occurs.
def print_with_border(...)

Render this Field to the terminal using the given Border object.

Parameters

  • border (Capsule): Capsule for the Border to draw around the field.
class Pawn (*args, **kwargs)

Class representing a Pawn owned by a Field or SwappableField.

Instances are created by Field.create_pawn()(…) and SwappableField.create_pawn()(…).

class SwappableField (*args, **kwargs)

Class representing a terminal SwappableField for pawns and borders.

Create with SwappableField(width: int, height: int).

Provides: create_pawn, print_with_border, add_pawn_to_swap, apply_swaps.

Methods

def add_pawn_to_swap(...)

add_pawn_to_swap(self, pawn: Pawn, coords: Capsule) -> None

Schedule a pawn to be swapped to the given coordinates in the next swap operation.

Parameters

  • pawn (Pawn): Pawn object to schedule for swapping.
  • coords (Capsule): Capsule for the target Coordinates.

Raises

  • IndexError: destination is out of bounds.
  • RuntimeError: destination is occupied or another API error occurs.
def apply_swaps(self)

Execute all scheduled pawn swaps in this SwappableField.

Raises

  • RuntimeError: if applying swaps fails.
def create_pawn(...)

create_pawn(self, symbol: str, ansi_settings: Capsule, coords: Capsule) -> Pawn

Create a Pawn inside this SwappableField and return a Pawn object.

Parameters

  • symbol (str): Single character string used to represent the pawn.
  • ansi_settings (Capsule): Capsule returned by create_ansi_settings().
  • coords (Capsule): Capsule returned by create_coordinates().

Returns

def print_with_border(...)

print_with_border(self, border: Capsule) -> None

Render this SwappableField to the terminal using the given Border object.

Parameters

  • border (Capsule): Capsule for the Border to draw around the field.