| Name | jk-console JSON |
| Version |
0.2023.2.8
JSON |
| download |
| home_page | |
| 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.) |
| upload_time | 2023-02-08 22:03:13 |
| maintainer | |
| docs_url | None |
| author | Jürgen Knauth |
| requires_python | |
| license | Apache2 |
| keywords |
console
terminal
colors
stdin
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
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
Raw data
{
"_id": null,
"home_page": "",
"name": "jk-console",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "console,terminal,colors,stdin",
"author": "J\u00fcrgen Knauth",
"author_email": "pubsrc@binary-overflow.de",
"download_url": "https://files.pythonhosted.org/packages/86/c2/a26d65f9368df52afc82919c1631e39e3f54fe1061fd82c421f9cbc060c9/jk_console-0.2023.2.8.tar.gz",
"platform": null,
"description": "jk_console\n==========\n\nIntroduction\n------------\n\nThis python module provides a variety of essential functionality for implementing versatile programs using the console. This includes:\n\n* reading single key stokes from STDIN\n* modifying cursor color\n* retrieving the dimensions of the console\n* placeing the cursor at (almost) any position within the console\n\nInformation about this module can be found here:\n\n* [github.org](https://github.com/jkpubsrc/python-module-jk-console)\n* [pypi.python.org](https://pypi.python.org/pypi/jk_console)\n\nWhy this module?\n----------------\n\nIf you want to write some more sophisticated command line programs it will get complicated. Python does not provide any support for\nreading single key strokes, colorizing output as well as more detailed control of the cursor is nothing Python takes care of. This\nmodule fills the gap.\n\nLimitations of this module\n--------------------------\n\nSpecial keys like function keys, cursor keys and similar are communicated by console windows using escape codes. Whenever you press these\nkeys a sequence of characters is sent by the console.\n\nReading these kind of key strokes from console is therefore based on reading multiple keys. Unfortunately you cannot know how many keys are\nsent. Therefor you need to know how to interpret these sequences as they greatly differ in length.\n\nThe `Console` class contains a register of these sequences for common key strokes. Whenever such a key is read the class tries to parse it.\nIf a known keystroke is encountered it is returned as a complete string. This way `readKey()` will try to always return a single key - even\nif this key is represented by multiple characters.\n\nThat implies: The `Console` class needs to know about all these character sequences. That means: **All special keys this module should\nrecognize must be hard coded into this module.** Whenever a known sequence is encountered it can be read completely and be recognized\nas a single key stroke event. (And if the sequence is not known this mechanism will not work properly.)\n\nThis module has been adapted to recognize all common special keys a user could press in a standard Linux console window. This has been tested\non Ubuntu Linux. Please have in mind that this might differ from other platforms or even from other console implementations. At the moment\nof writing these lines I as the author of `Console` have no information about how well other platforms and terminal implementations follow\nthese standards. I have no possibility to test this on other platforms at this point in time. So if you encounter any difficulties or have\nmore information please contact me. I'll gladly extend this module.\n\nHow to use this module\n----------------------\n\n### Import this module\n\nPlease include this module into your application using the following code:\n\n```python\nfrom jk_console import Console\n```\n\n### Reading single key strokes\n\nIn order to read a single key stroke invoke the following command:\n\n```python\nkey = Console.Input.readKey()\n```\n\nThe 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.\n\nPlease note that Ctrl+C is not catched by the application if you invoke `readKey()` but returned as a regular key stroke.\n\nPlease see *Limitations of this module* for information about when decoding key strokes might fail.\n\n### Converting key strokes to text\n\nIn order to get a human readable representation of a key stroke use the following code:\n\n```python\nkeyStr = Console.Input.ALL_KEYS_TO_KEY_NAME.get(key)\n```\n\n### Clearing the console screen\n\nYou can clear the current console screen by invoking the following method:\n\n```python\nConsole.clear()\n```\n\n### Move cursor to a specific position on the console screen\n\nYou can move the cursor to a specific line and column number in a console using the following code:\n\n```python\nConsole.moveCursorTo(lineNo, colNo)\n```\n\nPlease note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.\n\n### Print text at a specific position on the console screen\n\nYou can print some text at a specific line and column number using the following code:\n\n```python\nConsole.printAt(lineNo, colNo, someText)\n```\n\nPlease note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.\n\nPlease 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\nand 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\ncause the console to add a new line and thus scrolling all existing text one line upwards.\n\n### Get current cursor position\n\nIn order to retrieve the current cursor position invoke `getCursorPosition()`:\n\n```python\nlineNo, colNo = Console.getCursorPosition()\n```\n\nPlease note that row and column numbers are **always** counted starting at zero. So `(0, 0)` specifies the upper left corner of the console.\n\n### Get the size of the console\n\nIn order to retrieve the dimensions of your console view port invoke `getSize()` and/or `width()` and `height()`:\n\n```python\nheight, width = Console.getSize()\n```\n\n### Use color methods\n\nYou can perfom colorized output using the predefined constants for foreground and background.\n\nExample:\n\n```python\nprint(Console.ForeGround.CYAN + \"Hello World!\" + Console.RESET)\n```\n\nAlternatively you can invoke one of these color methods:\n\n* `rgb256(r, g, b)` - which will create a text string representing your color using `int` values in the range of [0..255]\n* `rgb1(r, g, b)` - which will create a text string representing your color using `float` values in the range of [0..1]\n* `hsl1(h, s, l)` - which will create a text string representing your color using `float` values in the range of [0..1]\n\nExample:\n\n```python\nprint(Console.BackGround.rgb256(128, 0, 0) + \"Hello World!\" + Console.RESET)\n```\nPlease note that the current color settings are valid for all future printing to the console.\n\n### Resetting color\n\nIn order to reset color settings use the folloiwing code:\n\n```python\nprint(Console.RESET)\n```\n\nContact Information\n-------------------\n\nThis is Open Source code. That not only gives you the possibility of freely using this code it also\nallows you to contribute. Feel free to contact the author(s) of this software listed below, either\nfor comments, collaboration requests, suggestions for improvement or reporting bugs:\n\n* J\u00fcrgen Knauth: jknauth@uni-goettingen.de, pubsrc@binary-overflow.de\n\nLicense\n-------\n\nThis software is provided under the following license:\n\n* Apache Software License 2.0",
"bugtrack_url": null,
"license": "Apache2",
"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.)",
"version": "0.2023.2.8",
"split_keywords": [
"console",
"terminal",
"colors",
"stdin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86c2a26d65f9368df52afc82919c1631e39e3f54fe1061fd82c421f9cbc060c9",
"md5": "c5e77a0e39edd342930397d6a7ee9aa8",
"sha256": "0a17e2565c9bf6aaf1bf2fd30dbda9cf110d2f81163b620e4782fb39287ec034"
},
"downloads": -1,
"filename": "jk_console-0.2023.2.8.tar.gz",
"has_sig": false,
"md5_digest": "c5e77a0e39edd342930397d6a7ee9aa8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 39064,
"upload_time": "2023-02-08T22:03:13",
"upload_time_iso_8601": "2023-02-08T22:03:13.944233Z",
"url": "https://files.pythonhosted.org/packages/86/c2/a26d65f9368df52afc82919c1631e39e3f54fe1061fd82c421f9cbc060c9/jk_console-0.2023.2.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-08 22:03:13",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "jk-console"
}
