Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
127 additions
and
84 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,161 +1,204 @@ | ||
| See it at: | ||
| | |GitHub badge| |PyPi badge| |python versions badge| |licence badge| | ||
| | |test status| |coverage status| |pip downloads badge| | ||
| - `pypi`_ | ||
| - `GitHub`_ | ||
| python-readchar | ||
| *************** | ||
|
|
||
| ============== =============== ========= ============ | ||
| VERSION DOWNLOADS TESTS COVERAGE | ||
| ============== =============== ========= ============ | ||
| |pip version| |pip downloads| |travis| |coveralls| | ||
| ============== =============== ========= ============ | ||
|
|
||
| Library to easily read single chars and key strokes. | ||
|
|
||
| Goal and Philosophy | ||
| =================== | ||
| Library to easily read single chars and keystrokes. | ||
|
|
||
| Born as a `python-inquirer`_ requirement. | ||
|
|
||
| The idea is to have a portable way to read **single** characters and **key-strokes**. | ||
|
|
||
|
|
||
| Documentation | ||
| ============= | ||
|
|
||
| Installation | ||
| ------------ | ||
| ============ | ||
|
|
||
| simply install it via :code:`pip`: | ||
|
|
||
| :: | ||
| .. code:: bash | ||
| pip install readchar | ||
| The :code:`readchar` library works with python 3.6, 3.7, 3.8, 3.9 and 3.10. | ||
| Or download the source code from PyPi_. | ||
|
|
||
|
|
||
| Usage | ||
| ----- | ||
| ===== | ||
|
|
||
| Usage example: | ||
| Simply read a character or keystroke: | ||
|
|
||
| .. code:: python | ||
| import readchar | ||
| c = readchar.readchar() | ||
| key = readchar.readkey() | ||
| React to different kinds of keypresses: | ||
|
|
||
| .. code:: python | ||
| from readchar import readkey, key | ||
| while True: | ||
| k = readkey() | ||
| if k == "a": | ||
| # do stuff | ||
| if k == key.DOWN: | ||
| # do stuff | ||
| if k == key.ENTER: | ||
| break | ||
| API | ||
| ---- | ||
| === | ||
|
|
||
| There are just two methods: | ||
|
|
||
| :code:`readchar()` | ||
| ////////////////// | ||
| :code:`readchar() -> str` | ||
| ------------------------- | ||
|
|
||
| Reads one character from :code:`stdin`, returning it as a string with length 1. Waits until a character is available. | ||
|
|
||
| As only ASCII characters are actually a single character, you usually want to use the next function, that also handles longer keys. | ||
|
|
||
|
|
||
| :code:`readkey() -> str` | ||
| ------------------------ | ||
|
|
||
| Reads the next keystroke from :code:`stdin`, returning it as a string. Waits until a keystroke is available. | ||
|
|
||
| A keystroke can be: | ||
|
|
||
| Reads the next char from :code:`stdin`, returning it as a string with length 1. | ||
| - single characters as returned by :code:`readchar()`. These include: | ||
|
|
||
| - character for normal keys: 'a', 'Z', '9',... | ||
| - special characters like 'ENTER', 'BACKSPACE', 'TAB',... | ||
| - combinations with 'CTRL': 'CTRL'+'A',... | ||
|
|
||
| :code:`readkey()` | ||
| ///////////////// | ||
| - keys that are made up of multiple characters: | ||
|
|
||
| Reads the next key-stroke from :code:`stdin`, returning it as a string. | ||
| - characters for cursors/arrows: 🡩, 🡪, 🡫, 🡨 | ||
| - navigation keys: 'INSERT', 'HOME',... | ||
| - function keys: 'F1' to 'F12' | ||
| - combinations with 'ALT': 'ALT'+'A',... | ||
| - combinations with 'CTRL' and 'ALT': 'CTRL'+'ALT'+'SUPR',... | ||
|
|
||
| A key-stroke can have: | ||
| .. attention:: | ||
|
|
||
| - 1 character for normal keys: 'a', 'z', '9'... | ||
| - 2 characters for combinations with ALT: ALT+A, ... | ||
| - 3 characters for cursors: ->, <-, ... | ||
| - 4 characters for combinations with CTRL and ALT: CTRL+ALT+SUPR, ... | ||
| 'CTRL'+'C' will not be returned by :code:`readkey()`, but instead raise a :code:`KeyboardInterupt`. If you what to handle it yourself, | ||
| use :code:`readchar()`. | ||
|
|
||
| There is a list of previously captured chars with their names in :code:`readchar.key`, in order to be used in comparisons and so on. This list is not enough tested and it can have mistakes, so use it carefully. Please, report them if found. | ||
|
|
||
| :code:`key` module | ||
| --------------------- | ||
|
|
||
| This submodule contains a list of available keys to compare against. The constants are defined depending on your operating system, so it should be | ||
| fully portable. If a key is listed here for your platform, :code:`readkey()` can read it and you can compare against it. | ||
|
|
||
|
|
||
| OS Support | ||
| ---------- | ||
| ========== | ||
|
|
||
| This library actively supports these operating systems: | ||
|
|
||
| - Linux | ||
| - Windows | ||
|
|
||
| Some operating systems are enabled, but not actively tested or supported: | ||
|
|
||
| This library supports GNU/Linux and Windows. Please, if you can try it in another OS and find a bug, put an issue or send the pull-request. | ||
| - macOS | ||
| - FreeBSD | ||
|
|
||
| Theoretically every Unix based system should work, but they will not be actively tested. It is also required that somebody provides initial test | ||
| results before the OS is enabled and added to the list. Feel free to open a PR for that. | ||
|
|
||
| Thank you! | ||
|
|
||
|
|
||
| How to contribute | ||
| ================= | ||
|
|
||
| You can download the code, make some changes with their tests, and make a pull-request. | ||
| You can download the code, make some changes with their tests, and open a pull-request. | ||
|
|
||
| In order to develop or running the tests, you can do: | ||
| In order to develop and run the tests, follow these steps: | ||
|
|
||
| 1. Clone the repository. | ||
| 1. Clone the repository. | ||
|
|
||
| .. code:: bash | ||
| .. code:: bash | ||
| git clone https://github.com/magmax/python-readchar.git | ||
| git clone https://github.com/magmax/python-readchar.git | ||
| 2. Create a virtual environment: | ||
| 2. Create a virtual environment: | ||
|
|
||
| .. code:: bash | ||
| .. code:: bash | ||
| python -m venv .venv | ||
| python -m venv .venv | ||
| 3. Enter in the virtual environment | ||
| 3. Enter the virtual environment | ||
|
|
||
| .. code:: bash | ||
| on Linux systems: | ||
|
|
||
| source .venv/bin/activate | ||
| .. code:: bash | ||
| 4. Install dependencies | ||
| source .venv/bin/activate | ||
| .. code:: bash | ||
| or for Windows systems: | ||
|
|
||
| pip install -r requirements.txt | ||
| .. code:: bash | ||
| 5. Install the local version of readchar (in edit mode so it automatically reflects changes) | ||
| .venv\Scripts\activate | ||
| .. code:: bash | ||
| 4. Install dependencies | ||
|
|
||
| pip install -e . | ||
| .. code:: bash | ||
| 6. Run tests | ||
| pip install -r requirements.txt | ||
| .. code:: bash | ||
| 5. Install the local version of readchar (in edit mode, so it automatically reflects changes) | ||
|
|
||
| make | ||
| .. code:: bash | ||
| pip install -e . | ||
| Please, **Execute the tests before any pull-request**. This will avoid invalid builds. | ||
| 6. Run tests | ||
|
|
||
| .. code:: bash | ||
| Licence | ||
| ======= | ||
| make | ||
| Copyright (c) 2014-2021 Miguel Angel Garcia (`@magmax_en`_). | ||
| (or run the command used inside the Makefile manually, if you don't have/want :code:`make`) | ||
|
|
||
| Based on previous work on gist `getch()-like unbuffered character reading from stdin on both Windows and Unix (Python recipe)`_, started by `Danny Yoo`_. | ||
|
|
||
| Licensed under `the MIT licence`_. | ||
| Please, **Execute the tests before any pull-request**. This will avoid invalid builds. | ||
|
|
||
|
|
||
| .. |travis| image:: https://travis-ci.org/magmax/python-readchar.png | ||
| :target: `Travis`_ | ||
| :alt: Travis results | ||
| ------ | ||
|
|
||
| .. |coveralls| image:: https://coveralls.io/repos/magmax/python-readchar/badge.png | ||
| :target: `Coveralls`_ | ||
| :alt: Coveralls results_ | ||
| *Copyright (c) 2014-2022 Miguel Angel Garcia* | ||
|
|
||
| .. |pip version| image:: https://img.shields.io/pypi/v/readchar.svg | ||
| :target: https://pypi.python.org/pypi/readchar | ||
| :alt: Latest PyPI version | ||
|
|
||
| .. |pip downloads| image:: https://img.shields.io/pypi/dm/readchar.svg | ||
| :target: https://pypi.python.org/pypi/readchar | ||
| .. |GitHub badge| image:: https://badges.aleen42.com/src/github.svg | ||
| :target: GitHub_ | ||
| :alt: GitHub Repository | ||
| .. |PyPi badge| image:: https://img.shields.io/pypi/v/readchar.svg | ||
| :target: PyPi_ | ||
| :alt: Latest PyPI version | ||
| .. |Python versions badge| image:: https://img.shields.io/pypi/pyversions/readchar | ||
| :target: PyPi_ | ||
| :alt: supported Python versions | ||
| .. |licence badge| image:: https://img.shields.io/pypi/l/readchar?color=blue | ||
| :target: licence_ | ||
| :alt: Project licence | ||
| .. |test status| image:: https://github.com/magmax/python-readchar/actions/workflows/run-tests.yml/badge.svg?branch=master | ||
| :target: github.com/magmax/python-readchar/actions/workflows/run-tests.yml?query=branch%3Amaster | ||
| :alt: Automated testing results | ||
| .. |coverage status| image:: https://coveralls.io/repos/github/magmax/python-readchar/badge.svg?branch=master | ||
| :target: https://coveralls.io/github/magmax/python-readchar?branch=master | ||
| :alt: Coveralls results | ||
| .. |pip downloads badge| image:: https://img.shields.io/pypi/dd/readchar.svg | ||
| :target: PyPi_ | ||
| :alt: Number of PyPI downloads | ||
|
|
||
| .. _pypi: https://pypi.python.org/pypi/readchar | ||
| .. _GitHub: https://github.com/magmax/python-readchar | ||
| .. _PyPi: https://pypi.python.org/pypi/readchar | ||
| .. _licence: LICENCE | ||
| .. _python-inquirer: https://github.com/magmax/python-inquirer | ||
| .. _Travis: https://travis-ci.org/magmax/python-readchar | ||
| .. _Coveralls: https://coveralls.io/r/magmax/python-readchar | ||
| .. _@magmax_en: https://twitter.com/magmax_en | ||
|
|
||
| .. _the MIT licence: LICENCE | ||
| .. _getch()-like unbuffered character reading from stdin on both Windows and Unix (Python recipe): http://code.activestate.com/recipes/134892/ | ||
| .. _Danny Yoo: http://code.activestate.com/recipes/users/98032/ |