[](https://pypi.python.org/pypi/teletype)
[](https://en.wikipedia.org/wiki/MIT_License)
[](https://github.com/ambv/black)
# teletype
**teletype** is a high-level cross platform tty library compatible with Python 3.7+. It provides a consistent interface between the terminal and cmd.exe by building on top of [terminfo](https://invisible-island.net/ncurses/terminfo.src.html) and [msvcrt](https://msdn.microsoft.com/en-us/library/abx4dbyh.aspx) and has no dependencies.
# Installation
`$ pip install teletype`
# I/O Utilities (teletype.io)
## Reading Key Strokes
You can read keystrokes from stdin using `get_key`. Regular keys get returned as a string with a single character, e.g. `"a"`, `"1"`, `"&"`, etc., while special keys and key combinations are returned as a string description, e.g. `"space"`, `"f12"`, `"page-up"`, `"ctrl-c"`, etc. A listing of the supported key combinations are listed in the [`codes`](https://github.com/jkwill87/teletype/blob/master/teletype/codes/common.py) module.
```python
from teletype.io import get_key
print("Delete C:/ Drive? [y/n]")
selection = ""
while selection.lower() not in ("y", "n"):
selection = get_key()
if selection in ("ctrl-c", "ctrl-z", "escape"):
selection = "n"
if selection == "y":
print("Deleting C:/ drive...")
delete_c_drive()
else:
print("Leaving C:/ drive alone")
```
## Styling Output
You can style strings with COLOURS and effects using `style_format`. Styles can be passed in either as a space delimited string or in a collection (e.g. a tuple, set, list, etc.). The passed `text` string is then wrapped in the appropriate ASCII escape sequences and returned. When `print`ed the appropriate styles will be applied.
Alternatively you can you just pass these same parameters to `style_print` and accomplish this in one fell swoop. `style_print` takes the same parameters as the regular print function and can be used in place. In python3 you can even import style_print as print and use it in place. In order to pull this compatibility off for python2, the `style` argument must be specified explitly when calling, however, e.g. `style_print("yolo", style="yellow")`.
Lastly, you can use `strip_format` to clear a string of any escape sequences that have been previously applied.
```python
from teletype.io import style_format, style_print, strip_format
# All of these will do the same thing, that is print the message in red and bold
print(style_format("I want to stand out!", "bold red"))
print(style_format("I want to stand out!", ("red", "bold")))
style_print("I want to stand out!", style=["red", "bold"])
# Styles are cleared afterwards so everything else gets printed normally
print("I want to be boring")
# If for whatever reason you want to unstyle text, thats a thing too
text = style_format("I don't actually want too be styled", ("red", "bold"))
print(strip_format(text))
```
## Cursor manipulation
The package includes quite a few helper functions to move the CURSOR around the screen. These include `erase_lines`, `erase_screen`, `hide_cursor`, `show_cursor`, and `move_cursor`; all of which are fairly self explanitory. The only word of caution is to remember to reset CURSOR visibility as its state will persist after the python interpreter has exited.
# Components (teletype.components)
The package also includes components, higher level UI classes that are composed from the I/O functions and can be easily incorporated to any CLI application.
## SelectOne
```python
In [1]: from teletype.components import SelectOne
...:
...: picker = SelectOne(choices=["dog", "bird", "cat", "monkey", "gorilla"])
...: print("Your Favourite Animal?")
...: choice = picker.prompt()
...: print("Your choice: " + choice)
```
```
Your Favourite Animal?
❱ dog
bird
cat
monkey
gorilla
Your choice: dog
```
## SelectMany
```python
In [2]: from teletype.components import SelectMany
...:
...: picker = SelectMany(choices=["dog", "bird", "cat", "monkey", "gorilla"])
...: print("Your Favourite Animals?")
...: choices = picker.prompt()
...: print("Your choices: " + ", ".join(choices))
```
```
Your Favourite Animals?
❱● dog
○ bird
○ cat
○ monkey
○ gorilla
Your choices: dog
```
## ProgressBar
```python
In [3]: from time import sleep
...: from teletype.components import ProgressBar
...:
...: iterations = 15
...:
...: def iterable():
...: for _ in range(iterations):
...: sleep(0.2)
...: yield
...:
...: ProgressBar("Progress Bar").process(iterable(), iterations)
```
```
Progress Bar: 15/15▐████████████████████████████████████████████████▌100%
```
## ChoiceHelper
Although not a component in and of itself, `ChoiceHelper` can help you wrap your objects to make full use of components like `SelectOne`, `SelectMany`, or `SelectApproval`. This is completely optional-- normally these just use the string representations of objects for display, e.g. just printing options which are strings or calling their underlying `__str__` methods.
### Seperate Values from Labels
Sometimes this isn't an option or you might want to seperate the label of an object from its value. `ChoiceHelper` lets you specifiy these fields explicitly. You can apply styles, too.
```python
In [4]: from teletype.components import SelectOne, ChoiceHelper
...:
...: choices = [
...: ChoiceHelper(["corgi", "greyhound", "bulldog"], label="dog", style="blue"),
...: ChoiceHelper(["siamese", "chartreux", "ragdoll"], label="cat", style="red"),
...: ChoiceHelper(["zebra", "beta", "gold"], "fish", style="green")
...: ]
...:
...: print("favourite pet")
...: pet = SelectOne(choices).prompt()
...:
...: print("favourite breed")
...: breed = SelectOne(pet).prompt()
```
```
favourite pet
❱ dog
cat
fish
favourite breed
❱ corgi
greyhound
bulldog
```
### Mnemonics
Another cool thing that `ChoiceHelper`s let you do is use mneumonics. These can be specified either using a single character, in which case they are underlined, or as a single character wrapped in square brackets, in which case they will be indicated using square brackets (e.g. for compatibility with dumb terminals).
This is used under the hood for `SelectApproval` to quickly select yes by pressing `y` and no by pressing `n`.
## Styling Components (teletype.components.config)
You can set component styles using `io.style_format`.
```python
from teletype.io import style_format, style_print
from teletype.components import ProgressBar, SelectMany
style = "red bold"
arrow = io.style_format(CHARS_DEFAULT["arrow"], style)
choices = ["dogs", "cats", "fish"]
io.style_print("\nSelect One", style=style)
SelectOne(choices, arrow=arrow).prompt()
```
You can also change character sets using `set_char(key, value)` where value is the unicode character you want to use and key is one of:
- `arrow`
- `block`
- `left-edge`
- `right-edge`
- `selected`
- `unselected`
# License
MIT. See LICENSE.txt for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/jkwill87/teletype",
"name": "teletype",
"maintainer": "Jessy Williams",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "jessy@jessywilliams.com",
"keywords": "tty cli terminal",
"author": "Jessy Williams",
"author_email": "jessy@jessywilliams.com",
"download_url": "https://files.pythonhosted.org/packages/90/a4/eea7f11ff995492743e43319741b21e36762f44fc3cbc7c34b03f6d4322c/teletype-1.3.4.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/teletype)\n[](https://en.wikipedia.org/wiki/MIT_License)\n[](https://github.com/ambv/black)\n\n\n# teletype\n\n**teletype** is a high-level cross platform tty library compatible with Python 3.7+. It provides a consistent interface between the terminal and cmd.exe by building on top of [terminfo](https://invisible-island.net/ncurses/terminfo.src.html) and [msvcrt](https://msdn.microsoft.com/en-us/library/abx4dbyh.aspx) and has no dependencies.\n\n\n# Installation\n\n`$ pip install teletype`\n\n\n# I/O Utilities (teletype.io)\n\n## Reading Key Strokes\n\nYou can read keystrokes from stdin using `get_key`. Regular keys get returned as a string with a single character, e.g. `\"a\"`, `\"1\"`, `\"&\"`, etc., while special keys and key combinations are returned as a string description, e.g. `\"space\"`, `\"f12\"`, `\"page-up\"`, `\"ctrl-c\"`, etc. A listing of the supported key combinations are listed in the [`codes`](https://github.com/jkwill87/teletype/blob/master/teletype/codes/common.py) module.\n\n```python\nfrom teletype.io import get_key\n\nprint(\"Delete C:/ Drive? [y/n]\")\nselection = \"\"\nwhile selection.lower() not in (\"y\", \"n\"):\n selection = get_key()\n if selection in (\"ctrl-c\", \"ctrl-z\", \"escape\"):\n selection = \"n\"\nif selection == \"y\":\n print(\"Deleting C:/ drive...\")\n delete_c_drive()\nelse:\n print(\"Leaving C:/ drive alone\")\n```\n\n## Styling Output\n\nYou can style strings with COLOURS and effects using `style_format`. Styles can be passed in either as a space delimited string or in a collection (e.g. a tuple, set, list, etc.). The passed `text` string is then wrapped in the appropriate ASCII escape sequences and returned. When `print`ed the appropriate styles will be applied.\n\nAlternatively you can you just pass these same parameters to `style_print` and accomplish this in one fell swoop. `style_print` takes the same parameters as the regular print function and can be used in place. In python3 you can even import style_print as print and use it in place. In order to pull this compatibility off for python2, the `style` argument must be specified explitly when calling, however, e.g. `style_print(\"yolo\", style=\"yellow\")`.\n\nLastly, you can use `strip_format` to clear a string of any escape sequences that have been previously applied.\n\n```python\nfrom teletype.io import style_format, style_print, strip_format\n\n\n# All of these will do the same thing, that is print the message in red and bold\nprint(style_format(\"I want to stand out!\", \"bold red\"))\nprint(style_format(\"I want to stand out!\", (\"red\", \"bold\")))\nstyle_print(\"I want to stand out!\", style=[\"red\", \"bold\"])\n\n\n# Styles are cleared afterwards so everything else gets printed normally\nprint(\"I want to be boring\")\n\n\n# If for whatever reason you want to unstyle text, thats a thing too\ntext = style_format(\"I don't actually want too be styled\", (\"red\", \"bold\"))\nprint(strip_format(text))\n```\n\n## Cursor manipulation\n\nThe package includes quite a few helper functions to move the CURSOR around the screen. These include `erase_lines`, `erase_screen`, `hide_cursor`, `show_cursor`, and `move_cursor`; all of which are fairly self explanitory. The only word of caution is to remember to reset CURSOR visibility as its state will persist after the python interpreter has exited.\n\n\n# Components (teletype.components)\n\nThe package also includes components, higher level UI classes that are composed from the I/O functions and can be easily incorporated to any CLI application.\n\n## SelectOne\n\n```python\nIn [1]: from teletype.components import SelectOne\n ...:\n ...: picker = SelectOne(choices=[\"dog\", \"bird\", \"cat\", \"monkey\", \"gorilla\"])\n ...: print(\"Your Favourite Animal?\")\n ...: choice = picker.prompt()\n ...: print(\"Your choice: \" + choice)\n```\n\n```\nYour Favourite Animal?\n \u2771 dog\n bird\n cat\n monkey\n gorilla\nYour choice: dog\n```\n\n## SelectMany\n\n```python\nIn [2]: from teletype.components import SelectMany\n ...:\n ...: picker = SelectMany(choices=[\"dog\", \"bird\", \"cat\", \"monkey\", \"gorilla\"])\n ...: print(\"Your Favourite Animals?\")\n ...: choices = picker.prompt()\n ...: print(\"Your choices: \" + \", \".join(choices))\n```\n\n```\nYour Favourite Animals?\n\u2771\u25cf dog\n \u25cb bird\n \u25cb cat\n \u25cb monkey\n \u25cb gorilla\nYour choices: dog\n```\n\n## ProgressBar\n\n```python\nIn [3]: from time import sleep\n ...: from teletype.components import ProgressBar\n ...:\n ...: iterations = 15\n ...:\n ...: def iterable():\n ...: for _ in range(iterations):\n ...: sleep(0.2)\n ...: yield\n ...:\n ...: ProgressBar(\"Progress Bar\").process(iterable(), iterations)\n```\n\n```\nProgress Bar: 15/15\u2590\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u258c100%\n```\n\n## ChoiceHelper\n\nAlthough not a component in and of itself, `ChoiceHelper` can help you wrap your objects to make full use of components like `SelectOne`, `SelectMany`, or `SelectApproval`. This is completely optional-- normally these just use the string representations of objects for display, e.g. just printing options which are strings or calling their underlying `__str__` methods.\n\n### Seperate Values from Labels\n\nSometimes this isn't an option or you might want to seperate the label of an object from its value. `ChoiceHelper` lets you specifiy these fields explicitly. You can apply styles, too.\n\n```python\nIn [4]: from teletype.components import SelectOne, ChoiceHelper\n ...:\n ...: choices = [\n ...: ChoiceHelper([\"corgi\", \"greyhound\", \"bulldog\"], label=\"dog\", style=\"blue\"),\n ...: ChoiceHelper([\"siamese\", \"chartreux\", \"ragdoll\"], label=\"cat\", style=\"red\"),\n ...: ChoiceHelper([\"zebra\", \"beta\", \"gold\"], \"fish\", style=\"green\")\n ...: ]\n ...:\n ...: print(\"favourite pet\")\n ...: pet = SelectOne(choices).prompt()\n ...:\n ...: print(\"favourite breed\")\n ...: breed = SelectOne(pet).prompt()\n```\n\n```\nfavourite pet\n \u2771 dog\n cat\n fish\n\nfavourite breed\n \u2771 corgi\n greyhound\n bulldog\n```\n\n### Mnemonics\n\nAnother cool thing that `ChoiceHelper`s let you do is use mneumonics. These can be specified either using a single character, in which case they are underlined, or as a single character wrapped in square brackets, in which case they will be indicated using square brackets (e.g. for compatibility with dumb terminals).\n\nThis is used under the hood for `SelectApproval` to quickly select yes by pressing `y` and no by pressing `n`.\n\n## Styling Components (teletype.components.config)\n\nYou can set component styles using `io.style_format`.\n\n```python\nfrom teletype.io import style_format, style_print\nfrom teletype.components import ProgressBar, SelectMany\n\nstyle = \"red bold\"\narrow = io.style_format(CHARS_DEFAULT[\"arrow\"], style)\nchoices = [\"dogs\", \"cats\", \"fish\"]\n\nio.style_print(\"\\nSelect One\", style=style)\nSelectOne(choices, arrow=arrow).prompt()\n```\n\nYou can also change character sets using `set_char(key, value)` where value is the unicode character you want to use and key is one of:\n\n- `arrow`\n- `block`\n- `left-edge`\n- `right-edge`\n- `selected`\n- `unselected`\n\n\n# License\n\nMIT. See LICENSE.txt for details.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A high-level cross platform tty library",
"version": "1.3.4",
"split_keywords": [
"tty",
"cli",
"terminal"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "0df738cd3fc342f8a5283f54ec7f3008",
"sha256": "cc8ff31b61f0d1b858e863c41fa884c668b7387ed19b085922327df030c6843f"
},
"downloads": -1,
"filename": "teletype-1.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0df738cd3fc342f8a5283f54ec7f3008",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15462,
"upload_time": "2022-04-05T03:35:48",
"upload_time_iso_8601": "2022-04-05T03:35:48.717171Z",
"url": "https://files.pythonhosted.org/packages/da/c6/50bd8034e7c95b7b29bf9c6d96da806fc87636598bb3d6db1cd1e1e79d4e/teletype-1.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "e27f8e681406626163da1062f57f6af6",
"sha256": "b81a69338c3d1a532062a2851b0d51723beafa69d4d382b713be230a02bd618a"
},
"downloads": -1,
"filename": "teletype-1.3.4.tar.gz",
"has_sig": false,
"md5_digest": "e27f8e681406626163da1062f57f6af6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15447,
"upload_time": "2022-04-05T03:35:50",
"upload_time_iso_8601": "2022-04-05T03:35:50.957580Z",
"url": "https://files.pythonhosted.org/packages/90/a4/eea7f11ff995492743e43319741b21e36762f44fc3cbc7c34b03f6d4322c/teletype-1.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-04-05 03:35:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jkwill87",
"github_project": "teletype",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "teletype"
}
JSON
