pygconsole

ANSI terminal emulation for Pygame.

About the project

This package provides a way to emulate a terminal onto a Pygame display, compliant with a subset of the ECMA-48 standard (aka ANSI escape codes). Once correctly implemented, it can replace entirely sys.stdout if you desire, or at least be used with print() built-in function, as simply as displaying a string on a legacy terminal.

Getting started

Prerequisites

Of course, pygconsole cannot run without Python ! More precisely, it requires at least the 3.8 version of our beloved language.

pygconsole depends on the following packages. The installation of pygconsole should install automatically those packages if they are missing on your system. If it fails, you can install them individually:

• pygame: version 2.1.0 or above

   pip install pygame
  

• colorlog: version 6.4.1 or above

   pip install colorlog
  

• numpy: version 1.6.2 or above

   pip install numpy
  

Installation

Install from PyPi with:

pip install pygconsole

As an alternative, you can download the *.whl file from the last release on the pygconsole Github repository, and execute the following command (replace "X.Y.Z" by the right version number):

pip install pygconsole-X.Y.Z-py3-none-any.whl

Usage

First, import the package with the following command:

import pygconsole

pygconsole is used in close coordination with pygame. So you have to import and initialize pygame for instance with the following lines:

import pygame
from pygame.locals import *

DISPLAY_SIZE = (1920,1080)
RESOURCE_DIR = os.path.join(os.path.dirname(__file__),"resources") # directory where graphical resources are stored
BACKGROUND_IMAGE = os.path.join(RESOURCE_DIR,"background.jpg") # Background image

pygame.init()
flags = FULLSCREEN|SCALED|DOUBLEBUF
screen_surface = pygame.display.set_mode(size=DISPLAY_SIZE,flags=flags)
background_surface = pygame.image.load(BACKGROUND_IMAGE)

Those lines initalize a full HD, fullscreen display, with a background image named background.jpg. For deeper information about pygame, read the official site.

Initialize an I/O text, buffered stream with:

iotextstream = pygconsole.io.TextIOConsoleWrapper(console_name="pygame_console")

Retrieve the console created "under the hoods" with this I/O stream:

console = pygconsole.console.Console.get_console(name="pygame_console")

Finally, retrieve the pygame.Surface object used for displaying the console on screen:

surface = console.surface

It is now possible to enter the display loop ! A possible example of display loop can be (take care to previously import the builtin module sys otherwise the sys.exit() command will raise an exception !) :

while True:
	# Events
	for event in pygame.event.get():
		if event.type == KEYDOWN:
			if event.key == K_ESCAPE:
				sys.exit() # Exit when hitting the ESCAPE key
			elif event.key == K_RETURN:
				print("", file=iotextstream) # New line
		if event.type == TEXTINPUT: # When typing a key with a writable character...
			print(event.text, end='', file=iotextstream) # Display the character
		
	# Background display
	screen_surface.blit(background_surface,(0,0))
	
	# Console display at coordinates (1000,620)
	screen_surface.blit(console.surface,(1000,620))
	
	# Screen rendering
		pygame.display.flip()

If you wish to custom the console, you can initialize it independantly, and assign it to an I/O stream in a second step.

my_console = pygconsole.console.get_console(name="custom_console",width=120,height=50)

iotextstream = pygconsole.io.TextIOConsoleWrapper(console_name="custom_console")

A console is identified by its name, 2 consoles with the same name are in reality the same instance of the Console class.

Recognised ECMA-48 controls

Apart from recognising the main displayable unicode characters, pygconsole supports also the following non-displayable values in the byte stream sent to the console:

'\x0a' 		# LF (Line Field): move cursor to the corresponding character position of the following line
'\x0d' 		# CR (Carriage Return): move cursor to the first position of the current line
'\x1b' 		# ESC (Escape): start an escape sequence (see below)

Escape sequences supported by pygconsole take the form:

ESC [ <param> ; <param> ... <command>

Where <param> is an integer, and <command> is a single letter. Zero or more params are passed to a <command>. If no params are passed, it is generally synonymous with passing a single zero. No spaces exist in the sequence; they have been inserted here simply to read more easily.

The exhaustive list of escape sequences supported by pygconsole is the following:

# Erase in Display
ESC [ 0 J 		# clear from cursor to end of screen
ESC [ 1 J		# clear from cursor to beginning of the screen
ESC [ 2 J		# clear entire screen
ESC [ 3 J		# clear entire screen and delete all lines saved in the scrollback buffer

# Screen scrolling
ESC [ n S		# Scroll up of n lines. New lines are added at the bottom of the screen
ESC [ n T		# Scroll down of n lines. New lines are added at the top of the screen

# general graphic rendition commands
ESC [ 0 m		# default rendition, cancels the effect of any preceding occurrence of SGR sequence ("m" command)
ESC [ 1 m		# bold characters
ESC [ 3 m		# italicized characters
ESC [ 4 m		# singly underlined characters
ESC [ 7 m		# negative image, swaps foreground and background colours
ESC [ 22 m		# normal intensity characters (not bold)
ESC [ 23 m		# not italicized characters
ESC [ 24 m		# not underlined characters
ESC [ 27 m		# positive image, colours are no more reversed

# Foreground
ESC [ 30 m		# black
ESC [ 31 m		# red
ESC [ 32 m		# green
ESC [ 33 m		# yellow
ESC [ 34 m		# blue
ESC [ 35 m		# magenta
ESC [ 36 m		# cyan
ESC [ 37 m		# white
ESC [ 90 m		# bright black (grey)
ESC [ 91 m		# bright red
ESC [ 92 m		# bright green
ESC [ 93 m		# bright yellow
ESC [ 94 m		# bright blue
ESC [ 95 m		# bright magenta
ESC [ 96 m		# bright cyan
ESC [ 97 m		# bright white

# Background
ESC [ 40 m		# black
ESC [ 41 m		# red
ESC [ 42 m		# green
ESC [ 43 m		# yellow
ESC [ 44 m		# blue
ESC [ 45 m		# magenta
ESC [ 46 m		# cyan
ESC [ 47 m		# white
ESC [ 100 m		# bright black (grey)
ESC [ 101 m		# bright red
ESC [ 102 m		# bright green
ESC [ 103 m		# bright yellow
ESC [ 104 m		# bright blue
ESC [ 105 m		# bright magenta
ESC [ 106 m		# bright cyan
ESC [ 107 m		# bright white

For instance, to display "Hello world !" in red:

print("\x1b[31mHello world !", file= iotextstream, flush=True)

Multiple numeric params to the 'm' command can be combined into a single sequence:

ESC [ 1 ; 92 ; 41 m		# bold, bright green characters on red background

The colon character : is also recognised as a separator (like the semicolon ;).

All other escape sequences of the form ESC [ <param> ; <param> ... <command>, and, more generally, all other ECMA-48 controls, are silently stripped from the output.

API documentation

The API documentation is not yet implemented, sorry for the inconvenience :-(. Until the completion of this chapter, you can refer to the source files, they are self-documented enough to understand how the package proceeds.

The most two important classes are:

pygconsole.io.TextIOConsoleWrapper()

A buffered text stream providing higher-level access to a BufferedIOConsole buffered binary stream. It inherits io.TextIOWrapper in the ìo Python built-in library. For further details about inherited elements, see https://docs.python.org/3/library/io.html . This class is generally used directly to write characters on the console, by objects using I/O streams (like print()).

pygconsole.console.Console()

Console objects represent terminals that can be displayed onto any pygame.Surface object (in particular the display surface given by the pygame.display.get_surface() method).

Note that this class should never be instantiated directly, but always through the get_console() static method. Multiple calls to get_console() with the same name will always return a reference to the same Console object.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement" or "bug", according to whether you want to share a proposal of a new function, or to record an anomaly.

Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE.md file for more information.

Acknowledgments

I would like greatfully to thank:

DejaVU authors for their astounding work on that famous font family I chose as the default font on pygconsole.

Karl MPhotography for the great picture I chose for the background of the testing set.

Make a README, Sayan Mondal, Hillary Nyakundi and othneildrew for providing very interesting materials to write good README files (far better than I can write by myself !).

Choose an open source license for helping to choose the best suitable license for this project.

pygame for their wonderful library.

colorama for their inspiring description regarding ANSI escape sequences.

python-colorlog for adding joyful colors to the logging outputs.

ECMA International for maintaining over years the ECMA-48 standard

Semantic Versioning for providing clear specifications for versioning projects.

Real Python for contributing really increasing skills in Python for everyone, novices or veterans.

GitHub for hosting this project, and helping to share it.

Pypi for providing a very convenient way to share modules and package to the entire Python community.

And, of course, all the former, current and further contributors of this project !