Package sista

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

Functions

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.

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 capsule.

Parameters

Returns

  • Capsule wrapping the Pawn handler.
def move_pawn(...)

Move a pawn inside this Field and return a status code.

Parameters

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

Returns

  • int: status code (0 == success).
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 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: Capsule, coords: Capsule) -> int

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

Parameters

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

Returns

  • int: status code (0 == success).
def apply_swaps(self)

Execute all scheduled pawn swaps in this SwappableField.

Returns

  • int: status code (0 == success).
def create_pawn(...)

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

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

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

  • Capsule wrapping the Pawn handler.
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.