Package: pygconsole
pygconsoleANSI terminal emulation for Pygame.About the projectThis package provides a way to emulate a terminal onto a Pygame display, compliant with a subset of theECMA-48 standard(akaANSI escape codes). Once correctly implemented, it can replace entirelysys.stdoutif you desire, or at least be used withprint()built-in function, as simply as displaying a string on a legacy terminal.Getting startedPrerequisitesOf 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 abovepipinstallpygamecolorlog: version 6.4.1 or abovepipinstallcolorlognumpy: version 1.6.2 or abovepipinstallnumpyInstallationInstall from PyPi with:pipinstallpygconsoleAs an alternative, you can download the*.whlfile from the lastrelease on the pygconsole Github repository, and execute the following command (replace "X.Y.Z" by the right version number):pipinstallpygconsole-X.Y.Z-py3-none-any.whlUsageFirst, import the package with the following command:importpygconsolepygconsole is used in close coordination with pygame. So you have to import and initialize pygame for instance with the following lines:importpygamefrompygame.localsimport*DISPLAY_SIZE=(1920,1080)RESOURCE_DIR=os.path.join(os.path.dirname(__file__),"resources")# directory where graphical resources are storedBACKGROUND_IMAGE=os.path.join(RESOURCE_DIR,"background.jpg")# Background imagepygame.init()flags=FULLSCREEN|SCALED|DOUBLEBUFscreen_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 namedbackground.jpg. For deeper information about pygame, read theofficial 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.surfaceIt is now possible to enter the display loop ! A possible example of display loop can be (take care to previously import the builtin modulesysotherwise thesys.exit()command will raise an exception !) :whileTrue:# Eventsforeventinpygame.event.get():ifevent.type==KEYDOWN:ifevent.key==K_ESCAPE:sys.exit()# Exit when hitting the ESCAPE keyelifevent.key==K_RETURN:print("",file=iotextstream)# New lineifevent.type==TEXTINPUT:# When typing a key with a writable character...print(event.text,end='',file=iotextstream)# Display the character# Background displayscreen_surface.blit(background_surface,(0,0))# Console display at coordinates (1000,620)screen_surface.blit(console.surface,(1000,620))# Screen renderingpygame.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 controlsApart 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 whiteFor 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 backgroundThe colon character:is also recognised as a separator (like the semicolon;).All other escape sequences of the formESC [ <param> ; <param> ... <command>, and, more generally, all other ECMA-48 controls, are silently stripped from the output.API documentationThe 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ìoPython built-in library. For further details about inherited elements, seehttps://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 (likeprint()).pygconsole.console.Console()Console objects represent terminals that can be displayed onto anypygame.Surfaceobject (in particular the display surface given by thepygame.display.get_surface()method).Note that this class should never be instantiated directly, but always through theget_console()static method. Multiple calls toget_console()with the same name will always return a reference to the same Console object.ContributingContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make aregreatly 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 ProjectCreate 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 RequestLicenseDistributed under the MIT License. SeeLICENSE.mdfile for more information.AcknowledgmentsI would like greatfully to thank:DejaVUauthors for their astounding work on that famous font family I chose as the default font on pygconsole.Karl MPhotographyfor the great picture I chose for the background of the testing set.Make a README,Sayan Mondal,Hillary Nyakundiandothneildrewfor providing very interesting materials to write good README files (far better than I can write by myself !).Choose an open source licensefor helping to choose the best suitable license for this project.pygamefor their wonderful library.coloramafor their inspiring description regarding ANSI escape sequences.python-colorlogfor adding joyful colors to the logging outputs.ECMA Internationalfor maintaining over years theECMA-48 standardSemantic Versioningfor providing clear specifications for versioning projects.Real Pythonfor contributing really increasing skills in Python for everyone, novices or veterans.GitHubfor hosting this project, and helping to share it.Pypifor 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 !