{"id":22520723,"url":"https://github.com/jkwill87/teletype","last_synced_at":"2025-08-03T20:30:53.499Z","repository":{"id":57473906,"uuid":"145024645","full_name":"jkwill87/teletype","owner":"jkwill87","description":"high-level cross-platform tty library","archived":false,"fork":false,"pushed_at":"2022-04-05T03:35:11.000Z","size":736,"stargazers_count":18,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-13T21:46:49.730Z","etag":null,"topics":["cli","color","component","python","terminal","terminfo","tty","widgets"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkwill87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-16T18:23:06.000Z","updated_at":"2023-12-07T22:50:01.000Z","dependencies_parsed_at":"2022-09-26T17:40:59.309Z","dependency_job_id":null,"html_url":"https://github.com/jkwill87/teletype","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkwill87%2Fteletype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkwill87%2Fteletype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkwill87%2Fteletype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkwill87%2Fteletype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkwill87","download_url":"https://codeload.github.com/jkwill87/teletype/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228562150,"owners_count":17937234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","color","component","python","terminal","terminfo","tty","widgets"],"created_at":"2024-12-07T05:08:26.085Z","updated_at":"2024-12-07T05:08:26.685Z","avatar_url":"https://github.com/jkwill87.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![pypi](https://img.shields.io/pypi/v/teletype.svg?style=for-the-badge)](https://pypi.python.org/pypi/teletype)\n[![licence](https://img.shields.io/github/license/jkwill87/teletype.svg?style=for-the-badge)](https://en.wikipedia.org/wiki/MIT_License)\n[![code style black](https://img.shields.io/badge/Code%20Style-Black-black.svg?style=for-the-badge)](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\"`, `\"\u0026\"`, 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 ❱ 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❱● dog\n ○ bird\n ○ cat\n ○ monkey\n ○ 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▐████████████████████████████████████████████████▌100%\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 ❱ dog\n   cat\n   fish\n\nfavourite breed\n ❱ 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkwill87%2Fteletype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkwill87%2Fteletype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkwill87%2Fteletype/lists"}