README update

Author: Cube707

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/