ANSI terminal emulation for Pygame.
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.
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
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
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.
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.
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.
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!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
Distributed under the MIT License. See LICENSE.md
file for more information.
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 !