jk_console 0.2024.4.24__tar.gz

jk_console-0.2024.4.24/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.1
+Name: jk_console
+Version: 0.2024.4.24
+Summary: This python module provides a variety of essential functions for implementing versatile programs using the console. (Please have a look at the documentation for details.)
+Keywords: console,terminal,colors,stdin
+Author-email: Jürgen Knauth <pubsrc@binary-overflow.de>
+Maintainer-email: Jürgen Knauth <pubsrc@binary-overflow.de>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: msvcrt; platform_system=='Windows'
+Requires-Dist: jk_terminal_essentials >= 0.2024.2.2
+
+jk_console
+==========
+
+Introduction
+------------
+
+This python module provides a variety of essential functionality for implementing versatile programs using the console. This includes:
+
+* reading single key stokes from STDIN
+* modifying cursor color
+* retrieving the dimensions of the console
+* placeing the cursor at (almost) any position within the console
+
+Information about this module can be found here:
+
+* [github.org](https://github.com/jkpubsrc/python-module-jk-console)
+* [pypi.python.org](https://pypi.python.org/pypi/jk_console)
+
+Why this module?
+----------------
+
+If you want to write some more sophisticated command line programs it will get complicated. Python does not provide any support for
+reading single key strokes, colorizing output as well as more detailed control of the cursor is nothing Python takes care of. This
+module fills the gap.
+
+Limitations of this module
+--------------------------
+
+Special keys like function keys, cursor keys and similar are communicated by console windows using escape codes. Whenever you press these
+keys a sequence of characters is sent by the console.
+
+Reading these kind of key strokes from console is therefore based on reading multiple keys. Unfortunately you cannot know how many keys are
+sent. Therefor you need to know how to interpret these sequences as they greatly differ in length.
+
+The `Console` class contains a register of these sequences for common key strokes. Whenever such a key is read the class tries to parse it.
+If a known keystroke is encountered it is returned as a complete string. This way `readKey()` will try to always return a single key - even
+if this key is represented by multiple characters.
+
+That implies: The `Console` class needs to know about all these character sequences. That means: **All special keys this module should
+recognize must be hard coded into this module.** Whenever a known sequence is encountered it can be read completely and be recognized
+as a single key stroke event. (And if the sequence is not known this mechanism will not work properly.)
+
+This module has been adapted to recognize all common special keys a user could press in a standard Linux console window. This has been tested
+on Ubuntu Linux. Please have in mind that this might differ from other platforms or even from other console implementations. At the moment
+of writing these lines I as the author of `Console` have no information about how well other platforms and terminal implementations follow
+these standards. I have no possibility to test this on other platforms at this point in time. So if you encounter any difficulties or have
+more information please contact me. I'll gladly extend this module.
+
+How to use this module
+----------------------
+
+### Import this module
+
+Please include this module into your application using the following code:
+
+```python
+from jk_console import Console
+```
+
+### Reading single key strokes
+
+In order to read a single key stroke invoke the following command:
+
+```python
+key = Console.Input.readKey()
+```
+
+The variable `key` will then contain either a single character if a regular key or a set of characters if some specicial key has been pressed.
+
+Please note that Ctrl+C is not catched by the application if you invoke `readKey()` but returned as a regular key stroke.
+
+Please see *Limitations of this module* for information about when decoding key strokes might fail.
+
+### Converting key strokes to text
+
+In order to get a human readable representation of a key stroke use the following code:
+
+```python
+keyStr = Console.Input.ALL_KEYS_TO_KEY_NAME.get(key)
+```
+
+### Clearing the console screen
+
+You can clear the current console screen by invoking the following method:
+
+```python
+Console.clear()
+```
+
+### Move cursor to a specific position on the console screen
+
+You can move the cursor to a specific line and column number in a console using the following code:
+
+```python
+Console.moveCursorTo(lineNo, colNo)
+```
+
+Please note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.
+
+### Print text at a specific position on the console screen
+
+You can print some text at a specific line and column number using the following code:
+
+```python
+Console.printAt(lineNo, colNo, someText)
+```
+
+Please note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.
+
+Please also note that this command will move the cursor as well. This implies that printing at the very end of a line will cause a wrap around
+and the cursor will be moved to the beginning of the next line. If that happens at the very last character of your console window this will
+cause the console to add a new line and thus scrolling all existing text one line upwards.
+
+### Get current cursor position
+
+In order to retrieve the current cursor position invoke `getCursorPosition()`:
+
+```python
+lineNo, colNo = Console.getCursorPosition()
+```
+
+Please note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.
+
+### Get the size of the console
+
+In order to retrieve the dimensions of your console view port invoke `getSize()` and/or `width()` and `height()`:
+
+```python
+height, width = Console.getSize()
+```
+
+### Use color methods
+
+You can perfom colorized output using the predefined constants for foreground and background.
+
+Example:
+
+```python
+print(Console.ForeGround.CYAN + "Hello World!" + Console.RESET)
+```
+
+Alternatively you can invoke one of these color methods:
+
+* `rgb256(r, g, b)` - which will create a text string representing your color using `int` values in the range of [0..255]
+* `rgb1(r, g, b)` - which will create a text string representing your color using `float` values in the range of [0..1]
+* `hsl1(h, s, l)` - which will create a text string representing your color using `float` values in the range of [0..1]
+
+Example:
+
+```python
+print(Console.BackGround.rgb256(128, 0, 0) + "Hello World!" + Console.RESET)
+```
+Please note that the current color settings are valid for all future printing to the console.
+
+### Resetting color
+
+In order to reset color settings use the folloiwing code:
+
+```python
+print(Console.RESET)
+```
+
+Contact Information
+-------------------
+
+This is Open Source code. That not only gives you the possibility of freely using this code it also
+allows you to contribute. Feel free to contact the author(s) of this software listed below, either
+for comments, collaboration requests, suggestions for improvement or reporting bugs:
+
+* Jürgen Knauth: jknauth@uni-goettingen.de, pubsrc@binary-overflow.de
+
+License
+-------
+
+This software is provided under the following license:
+
+* Apache Software License 2.0
+
+
+
+

jk_console-0.2024.4.24/README.md

@@ -0,0 +1,180 @@
+jk_console
+==========
+
+Introduction
+------------
+
+This python module provides a variety of essential functionality for implementing versatile programs using the console. This includes:
+
+* reading single key stokes from STDIN
+* modifying cursor color
+* retrieving the dimensions of the console
+* placeing the cursor at (almost) any position within the console
+
+Information about this module can be found here:
+
+* [github.org](https://github.com/jkpubsrc/python-module-jk-console)
+* [pypi.python.org](https://pypi.python.org/pypi/jk_console)
+
+Why this module?
+----------------
+
+If you want to write some more sophisticated command line programs it will get complicated. Python does not provide any support for
+reading single key strokes, colorizing output as well as more detailed control of the cursor is nothing Python takes care of. This
+module fills the gap.
+
+Limitations of this module
+--------------------------
+
+Special keys like function keys, cursor keys and similar are communicated by console windows using escape codes. Whenever you press these
+keys a sequence of characters is sent by the console.
+
+Reading these kind of key strokes from console is therefore based on reading multiple keys. Unfortunately you cannot know how many keys are
+sent. Therefor you need to know how to interpret these sequences as they greatly differ in length.
+
+The `Console` class contains a register of these sequences for common key strokes. Whenever such a key is read the class tries to parse it.
+If a known keystroke is encountered it is returned as a complete string. This way `readKey()` will try to always return a single key - even
+if this key is represented by multiple characters.
+
+That implies: The `Console` class needs to know about all these character sequences. That means: **All special keys this module should
+recognize must be hard coded into this module.** Whenever a known sequence is encountered it can be read completely and be recognized
+as a single key stroke event. (And if the sequence is not known this mechanism will not work properly.)
+
+This module has been adapted to recognize all common special keys a user could press in a standard Linux console window. This has been tested
+on Ubuntu Linux. Please have in mind that this might differ from other platforms or even from other console implementations. At the moment
+of writing these lines I as the author of `Console` have no information about how well other platforms and terminal implementations follow
+these standards. I have no possibility to test this on other platforms at this point in time. So if you encounter any difficulties or have
+more information please contact me. I'll gladly extend this module.
+
+How to use this module
+----------------------
+
+### Import this module
+
+Please include this module into your application using the following code:
+
+```python
+from jk_console import Console
+```
+
+### Reading single key strokes
+
+In order to read a single key stroke invoke the following command:
+
+```python
+key = Console.Input.readKey()
+```
+
+The variable `key` will then contain either a single character if a regular key or a set of characters if some specicial key has been pressed.
+
+Please note that Ctrl+C is not catched by the application if you invoke `readKey()` but returned as a regular key stroke.
+
+Please see *Limitations of this module* for information about when decoding key strokes might fail.
+
+### Converting key strokes to text
+
+In order to get a human readable representation of a key stroke use the following code:
+
+```python
+keyStr = Console.Input.ALL_KEYS_TO_KEY_NAME.get(key)
+```
+
+### Clearing the console screen
+
+You can clear the current console screen by invoking the following method:
+
+```python
+Console.clear()
+```
+
+### Move cursor to a specific position on the console screen
+
+You can move the cursor to a specific line and column number in a console using the following code:
+
+```python
+Console.moveCursorTo(lineNo, colNo)
+```
+
+Please note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.
+
+### Print text at a specific position on the console screen
+
+You can print some text at a specific line and column number using the following code:
+
+```python
+Console.printAt(lineNo, colNo, someText)
+```
+
+Please note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.
+
+Please also note that this command will move the cursor as well. This implies that printing at the very end of a line will cause a wrap around
+and the cursor will be moved to the beginning of the next line. If that happens at the very last character of your console window this will
+cause the console to add a new line and thus scrolling all existing text one line upwards.
+
+### Get current cursor position
+
+In order to retrieve the current cursor position invoke `getCursorPosition()`:
+
+```python
+lineNo, colNo = Console.getCursorPosition()
+```
+
+Please note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.
+
+### Get the size of the console
+
+In order to retrieve the dimensions of your console view port invoke `getSize()` and/or `width()` and `height()`:
+
+```python
+height, width = Console.getSize()
+```
+
+### Use color methods
+
+You can perfom colorized output using the predefined constants for foreground and background.
+
+Example:
+
+```python
+print(Console.ForeGround.CYAN + "Hello World!" + Console.RESET)
+```
+
+Alternatively you can invoke one of these color methods:
+
+* `rgb256(r, g, b)` - which will create a text string representing your color using `int` values in the range of [0..255]
+* `rgb1(r, g, b)` - which will create a text string representing your color using `float` values in the range of [0..1]
+* `hsl1(h, s, l)` - which will create a text string representing your color using `float` values in the range of [0..1]
+
+Example:
+
+```python
+print(Console.BackGround.rgb256(128, 0, 0) + "Hello World!" + Console.RESET)
+```
+Please note that the current color settings are valid for all future printing to the console.
+
+### Resetting color
+
+In order to reset color settings use the folloiwing code:
+
+```python
+print(Console.RESET)
+```
+
+Contact Information
+-------------------
+
+This is Open Source code. That not only gives you the possibility of freely using this code it also
+allows you to contribute. Feel free to contact the author(s) of this software listed below, either
+for comments, collaboration requests, suggestions for improvement or reporting bugs:
+
+* Jürgen Knauth: jknauth@uni-goettingen.de, pubsrc@binary-overflow.de
+
+License
+-------
+
+This software is provided under the following license:
+
+* Apache Software License 2.0
+
+
+

jk_console-0.2024.4.24/jk_console/CharacterBuffer.py

@@ -0,0 +1,204 @@
+
+
+
+
+from .Console import *
+from .ConsoleBuffer import *
+from .Rect import *
+
+
+
+
+
+
+class CharacterBuffer(object):
+
+	class _Cell(object):
+
+		def __init__(self, bgColor:str):
+			self.col = bgColor
+			self.c = " "
+		#
+
+		def clear(self, bgColor:str):
+			self.col = bgColor
+			self.c = " "
+		#
+
+	#
+
+	def __init__(self, width:int, height:int, bgColor:str = Console.RESET):
+		self.__bgColor = bgColor
+		self.__width = width
+		self.__height = height
+		self.__widthM1 = self.__width - 1
+		self.__heightM1 = self.__height - 1
+		self.__numberOfCells = self.__width * self.__height
+
+		self.__lineNumbers = tuple(range(0, self.__height))
+		self.__columnNumbers = tuple(range(0, self.__width))
+
+		self._currentBuffer = [ [CharacterBuffer._Cell(bgColor) for x in self.__columnNumbers] for y in self.__lineNumbers]
+	#
+
+	@property
+	def bounds(self):
+		return Rect(0, 0, self.__width, self.__height)
+	#
+
+	@property
+	def size(self):
+		return self.__width, self.__height
+	#
+
+	@property
+	def width(self):
+		return self.__width
+	#
+
+	@property
+	def height(self):
+		return self.__height
+	#
+
+	def clear(self):
+		bgColor = self.__bgColor
+		for y in self.__lineNumbers:
+			for x in self.__columnNumbers:
+				self._currentBuffer[y][x].clear(bgColor)
+	#
+
+	def set(self, x:int, y:int, color:str, character:str):
+		assert len(character) == 1
+
+		cell = self._currentBuffer[y][x]
+		if color != None:
+			cell.c = character
+		if color != None:
+			cell.col = color
+	#
+
+	def fill(self, x:int, y:int, w:int, h:int, color:str, character:str):
+		assert len(character) == 1
+
+		for iy in range(y, y + h):
+			row = self._currentBuffer[iy]
+			for ix in range(x, x + w):
+				cell = row[ix]
+				cell.c = character
+				if color != None:
+					cell.col = color
+	#
+
+	def printText(self, x:int, y:int, color:str, text:str):
+		assert len(text) > 0
+
+		i = 0
+		for c in text:
+			cell = self._currentBuffer[y][x + i]
+			cell.c = c
+			if color != None:
+				cell.col = color
+			i += 1
+	#
+
+	def copyToCharacterBuffer1(self, srcX:int, srcY:int, width:int, height:int, destX:int, destY:int, otherBuffer):
+		assert isinstance(otherBuffer, CharacterBuffer)
+
+		rSrc = Rect(srcX, srcY, width, height)
+		assert self.bounds.isOtherRectInRect(rSrc)
+		rDest = Rect(destX, destY, width, height)
+		assert otherBuffer.bounds.isOtherRectInRect(rDest)
+
+		deltaX = destX - srcX
+		deltaY = destY - srcY
+
+		# ----------------
+
+		for srcIY in range(srcY, srcY + height):
+			srcRow = self._currentBuffer[srcIY]
+			destRow = otherBuffer._currentBuffer[srcIY + deltaY]
+			for srcIX in range(srcX, srcX + width):
+				srcCell = srcRow[srcIX]
+				destCell = destRow[srcIX + deltaX]
+				destCell.c = srcCell.c
+				destCell.col = srcCell.col
+	#
+
+	def copyToCharacterBuffer0(self, destX:int, destY:int, otherBuffer):
+		assert isinstance(otherBuffer, CharacterBuffer)
+
+		width = self.__width
+		height = self.__height
+
+		rDest = Rect(destX, destY, width, height)
+		assert otherBuffer.bounds.isOtherRectInRect(rDest)
+
+		deltaX = destX
+		deltaY = destY
+		srcX = 0
+		srcY = 0
+
+		# ----------------
+
+		for srcIY in range(srcY, srcY + height):
+			srcRow = self._currentBuffer[srcIY]
+			destRow = otherBuffer._currentBuffer[srcIY + deltaY]
+			for srcIX in range(srcX, srcX + width):
+				srcCell = srcRow[srcIX]
+				destCell = destRow[srcIX + deltaX]
+				destCell.c = srcCell.c
+				destCell.col = srcCell.col
+	#
+
+	def copyToConsoleBuffer1(self, srcX:int, srcY:int, width:int, height:int, destX:int, destY:int, otherBuffer:ConsoleBuffer):
+		rSrc = Rect(srcX, srcY, width, height)
+		assert self.bounds.isOtherRectInRect(rSrc)
+		rDest = Rect(destX, destY, width, height)
+		assert otherBuffer.bounds.isOtherRectInRect(rDest)
+
+		deltaX = destX - srcX
+		deltaY = destY - srcY
+
+		# ----------------
+
+		for srcIY in range(srcY, srcY + height):
+			srcRow = self._currentBuffer[srcIY]
+			destRow = otherBuffer._currentBuffer[srcIY + deltaY]
+			for srcIX in range(srcX, srcX + width):
+				srcCell = srcRow[srcIX]
+				destCell = destRow[srcIX + deltaX]
+				destCell.c = srcCell.c
+				destCell.col = srcCell.col
+				destCell.bChanged = True
+	#
+
+	def copyToConsoleBuffer0(self, destX:int, destY:int, otherBuffer:ConsoleBuffer):
+		width = self.__width
+		height = self.__height
+
+		rDest = Rect(destX, destY, width, height)
+		assert otherBuffer.bounds.isOtherRectInRect(rDest)
+
+		deltaX = destX
+		deltaY = destY
+		srcX = 0
+		srcY = 0
+
+		# ----------------
+
+		for srcIY in range(srcY, srcY + height):
+			srcRow = self._currentBuffer[srcIY]
+			destRow = otherBuffer._currentBuffer[srcIY + deltaY]
+			for srcIX in range(srcX, srcX + width):
+				srcCell = srcRow[srcIX]
+				destCell = destRow[srcIX + deltaX]
+				destCell.c = srcCell.c
+				destCell.col = srcCell.col
+				destCell.bChanged = True
+	#
+
+#
+
+
+