From 47efac09afad8e6d7fc81d3b14c4b2a83e7b05ab Mon Sep 17 00:00:00 2001 From: Jan Wille Date: Mon, 4 Jul 2022 16:58:21 +0200 Subject: [PATCH] README update --- README.rst | 211 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 127 insertions(+), 84 deletions(-) diff --git a/README.rst b/README.rst index fdb335b..f76a04a 100644 --- a/README.rst +++ b/README.rst @@ -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/