{"id":17143983,"url":"https://github.com/adamlwgriffiths/blessed-input","last_synced_at":"2025-03-24T10:17:19.129Z","repository":{"id":142682755,"uuid":"500248444","full_name":"adamlwgriffiths/blessed-input","owner":"adamlwgriffiths","description":"Sane terminal keyboard input handling in Blessed","archived":false,"fork":false,"pushed_at":"2022-06-06T02:29:27.000Z","size":12,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-29T15:35:07.839Z","etag":null,"topics":["blessed","input","keyboard","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adamlwgriffiths.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-06T00:50:36.000Z","updated_at":"2022-06-09T06:39:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"6687c476-8140-4c19-ae39-ddc2f6ddde15","html_url":"https://github.com/adamlwgriffiths/blessed-input","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamlwgriffiths%2Fblessed-input","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamlwgriffiths%2Fblessed-input/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamlwgriffiths%2Fblessed-input/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamlwgriffiths%2Fblessed-input/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamlwgriffiths","download_url":"https://codeload.github.com/adamlwgriffiths/blessed-input/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245249229,"owners_count":20584497,"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":["blessed","input","keyboard","python"],"created_at":"2024-10-14T20:42:48.856Z","updated_at":"2025-03-24T10:17:19.094Z","avatar_url":"https://github.com/adamlwgriffiths.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blessed Input\n\n_A terminal input sanitiser_\n\nThis is a small module which attempts to provide a sane method of determining\nwhat keys have been pressed, in order to enable more complicated input handling.\nIe, Ctrl, Alt, Shift, Meta, F-key combinations.\n\n*Without blessed-input*\n```\n# Ctrl + Down Arrow\nif key == '\\x1b[1;5B':\n    move_cursor_y(1)\n# Ctrl + HOME\nif key == '\\x1b[1;5H':\n    set_cursor_x(0)\n```\n\n*With blessed-input*\n```\nif key == [KEY_CTRL, KEY_DOWN]:\n    move_cursor_y(1)\nif key == [KEY_CTRL, KEY_HOME]:\n    set_cursor_x(0)\n```\n\n\nNormally when a key is pressed in blessed/ncurses, it's either a character, or\na series of terminal escape sequences, or a legacy mapping.\n\nThis can be incredibly unhelpful when you're trying to write simple code that\njust wants to perform an action on a key combination.\n\nWith this module, when an input is pressed, you instead get a a list of the keys\nthat were part of that event.\n\n\n## Usage\n\nAs a `blessed.inkey` replacement:\n```\nfrom blessed_input import get_key\n\n...\n\npressed = keys.get_key(term)\nprint(pressed)\n```\n\nThis function attempts to detect key sequences, and will receive\nfurther key events if this is the case using `receive_sequence`.\nIt then sends the key press 'string' input to `convert_keys`\nfor conversion to a list of key presses.\n\nKey sequences are always in the order:\n`[ KEY_META, KEY_CTRL, KEY_ALT, KEY_SHIFT, \u003ckey\u003e ]`\n\nThis should make matching patterns easier, as you don't need to look inside the list of each key, you just provide the sequence of keys you want in the above order.\n\nFor best compatibility, set your application to use `term.raw()` and `term.cbreak()`.\n\nTo get the 'text' version of a key, simply call `key.value` (as they are an enumeration).\n\nNote: that upper and lower-case keys are considered different characters.\nSo for standard characters, you should _not_ include the KEY_SHIFT in the combination.\n\nIe.\n`KEY_A                   = 'A'`\n`KEY_a                   = 'a'`\n\nIt should be noted that the meta keys will print the terminal key sequence.\n\nIe. `KEY_ESCAPE              = '\\x1b'`\n\nFunction-keys + Meta are converted properly.\nIe. you won't get F-24 being pressed, you'll get F1-F12 with the appropriate META key.\n\n## Demos\n\nSee demo.py for an example of a \"Text Editor-like\" application.\n\nSee debug_keys.py for an example of receiving key-events and printing out the key combinations.\n\n## Manual conversion\n\nIf you want to convert a key you've received from blessed/ncurses,\nrefer to the `get_key` implementation.\n\n## Caveats\n\nThe different ncurses modes act differently and have different reserved\nkey-combinations. YMMV.\n\nI've tried to parse every key combination I could get working (Ctrl, Alt, Shift, Meta, F-keys).\nI believe I got all the ones I can get working, to work.\n\nTerminals don't let you use some key sequences, as they are internal.\nEg. Ctrl+s turns on scroll-lock and cannot be used for \"Save\".\n\nKnown reserved key combinations that cannot be handled:\n\n* CTRL + i = TAB\n* CTRL + j = ENTER in non-\"raw\" mode\n* CTRL + m = ENTER in \"raw\" mode\n* CTRL + [ = ESCAPE\n\nThere are most likely others (CTRL+z, CTRL+s).\n\n## Opinion\n\nHaving to write this code demonstrated that it is _impossible_ to use a standard\nUnix terminal to write any sort of rich-input based application.\n\nThe difficulty in just getting a sane list of key events is just excessive.\nAnd the terminal's reserved key combinations occupy common industry established\nkey-combinations.\n\nThis is a deal-breaker.\n\nUse something native or make something in an embeddable webapp (webpy, etc),\nand make it act like a terminal.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamlwgriffiths%2Fblessed-input","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamlwgriffiths%2Fblessed-input","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamlwgriffiths%2Fblessed-input/lists"}