Add new cue: Password cue

A new cue is available to use: the Password cue.

This is especially useful when you need to retrieve some sensitive information from the user.

Author: giosali

README.md

@@ -207,11 +207,36 @@ This produces the following output:
 
 <img src="https://raw.githubusercontent.com/GBS3/cues/main/media/checkbox.gif" width="800">
 
+<h3 align="center"><i><b>Password</b></i></h3>
+
+You can use the `Password` class when you need input from the user but would prefer their input be hidden while they type as it may contain sensitive information.
+
+If you would like to to see an example of this in action, you can run the following command in your terminal:
+
+```
+python -m cues.password
+```
+
+```python
+from cues import Password
+
+
+name = 'password'
+message = 'Password:'
+
+cue = Password(name, message)
+answer = cue.send()
+print(answer)
+```
+
+This produces the following output:
+
+<img src="https://raw.githubusercontent.com/GBS3/cues/main/media/password.gif" width="800">
+
 ## To Do
 
- - [x] Bring support to macOS
- - [x] Bring support to Linux
  - [ ] JSON prompt
  - [x] Checkbox prompt
+ - [x] Password prompt
 
  ...*amongst other things!*

cues/__init__.py

@@ -30,5 +30,6 @@
     from .checkbox import Checkbox
     from .confirm import Confirm
     from .form import Form
+    from .password import Password
     from .select import Select
     from .survey import Survey

cues/constants.py

@@ -13,6 +13,8 @@
 FORM_MARKER_UNC = '○'
 FORM_MARKER_COM = '●'
 
+PASSWORD_MARKER = '*'
+
 SURVEY_PT = '○'
 SURVEY_PT_FILL = '●'
 SURVEY_LINE = '─'

cues/listen/ansi.py

@@ -57,6 +57,7 @@
 # Erase functions:
 
 CLEAR_LINE = '\x1b[K'  # Clears the current line
+CLEAR_ENTIRE_LINE = '\x1b[2K'  # Clears the entire line
 
 
 # Set mode:

cues/password.py

@@ -0,0 +1,144 @@
+# -*- coding: utf-8 -*-
+
+"""
+cues.password
+=============
+
+This module contains the Password class.
+"""
+
+from . import cursor
+from .cue import Cue
+from .listen import ansi
+
+
+class Password(Cue):
+    """Construct a Password object to retrieve hidden input from the user.
+
+    Password objects are useful when you require input from the user but
+    would like their input to be hidden as they type as it may contain
+    sensitive information.
+
+    Attributes
+    ----------
+    _password_fmt : str
+        The format for the password prompt.
+    """
+
+    __name__ = 'password'
+    __module__ = 'cues'
+
+    def __init__(self, name: str, message: str):
+        """
+
+        Parameters
+        ----------
+        name
+            The name of the Form instance.
+        message
+            Instructions or useful information regarding the prompt for the user.
+        """
+
+        super().__init__(name, message)
+
+        if message.strip()[-1].isalnum():
+            self._password_fmt = '[pink][?][/pink] {message} [grey]∙[/grey] {input}'
+            self._password_fmt_len = 7
+        else:
+            self._password_fmt = '[pink][?][/pink] {message} {input}'
+            self._password_fmt_len = 5
+
+    def send(self) -> dict:
+        """Returns a dict object containing user's response to the prompt.
+
+        Returns
+        -------
+        dict
+            Contains the user's response to the prompt.
+        """
+
+        self._draw()
+        return self.answer
+
+    def _draw(self):
+        """Assembles and prints the Password cue to the console.
+        """
+
+        up = self.keys.get('up')
+        down = self.keys.get('down')
+        right = self.keys.get('right')
+        left = self.keys.get('left')
+        backspace = self.keys.get('backspace')
+        enter = self.keys.get('enter')
+
+        padding = self._password_fmt_len + len(self._message)
+        input = ''
+        password = ''
+        buffer = ''
+
+        while True:
+            cursor.write(buffer + self._password_fmt.format(
+                message=self._message, input=password), color=True)
+
+            div, mod = divmod(padding + len(input), self.max_columns)
+            if not mod:
+                div -= 1
+
+            buffer = ''
+            for _ in range(div + 1):
+                buffer = ((ansi.CLEAR_ENTIRE_LINE + ansi.UP_ONE) * div) + \
+                    ansi.CLEAR_ENTIRE_LINE
+
+            key = self.listen_for_key()
+
+            if key == backspace:
+                input = input[:-1]
+                password = password[:-1]
+
+            elif key == enter:
+                cursor.move(x=-self.max_columns)
+                cursor.write(buffer)
+                break
+
+            elif (key == up) or (key == down) or (key == right) or (key == left):
+                pass
+
+            else:
+                input += chr(key)
+                password += '*'
+
+            cursor.move(x=-self.max_columns)
+
+        self.answer = {self._name: input}
+
+    @classmethod
+    def from_dict(cls, prompt: dict):
+        """Creates and instantiates a Password object from a dict object.
+
+        Parameters
+        ----------
+        prompt
+            A dict that contains a name key and a message key.
+
+        Returns
+        -------
+        cues.Password
+            A Password object to retrieve a single response from a user.
+        """
+
+        name = prompt['name']
+        message = prompt['message']
+        return cls(name, message)
+
+
+def main():
+    name = 'password'
+    message = 'Password:'
+
+    prompt = Password(name, message)
+    answer = prompt.send()
+    print(answer)
+
+
+if __name__ == '__main__':
+    main()

tests/test_password.py

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+
+"""
+tests.test_password
+===================
+
+A testing module for `cues.password`.
+"""
+
+import pytest
+
+from cues import cursor, password
+from cues.password import Password
+
+
+class TestPassword:
+    def setup(self):
+        self.name = 'password'
+        self.message = 'Password:'
+        self.message_endswith_alnum = 'Password'
+
+    def test_init(self):
+        cue = Password(self.name, self.message)
+
+        assert cue._name == self.name
+        assert cue._message == self.message
+
+    def test_init_with_message_endswith_alnum(self):
+        cue = Password(self.name, self.message_endswith_alnum)
+
+        assert cue._name == self.name
+        assert cue._message == self.message_endswith_alnum
+
+    def test_send(self, monkeypatch):
+        cue = Password(self.name, self.message)
+
+        monkeypatch.setattr(cue, '_draw', lambda: None)
+        assert cue.answer is None
+
+    def test_draw(self, monkeypatch):
+        cue = Password(self.name, self.message)
+        up = cue.keys.get('up')
+        down = cue.keys.get('down')
+        right = cue.keys.get('right')
+        left = cue.keys.get('left')
+        enter = cue.keys.get('enter')
+        backspace = cue.keys.get('backspace')
+
+        def generic_return_none(*args, **kwargs):
+            return None
+
+        moves = [backspace, 49, 50, 51, 52, up, down, right, left, enter]
+
+        def mock_listen_for_key():
+            if moves:
+                return moves.pop(0)
+
+        monkeypatch.setattr(cursor, 'write', generic_return_none)
+        monkeypatch.setattr(cue, 'listen_for_key', mock_listen_for_key)
+        monkeypatch.setattr(cursor, 'move', generic_return_none)
+
+        assert cue._draw() is None
+        assert cue.answer == {self.name: '1234'}
+
+    def test_from_dict(self):
+        cue = Password(self.name, self.message)
+
+        assert cue._name == self.name
+        assert cue._message == self.message
+
+    # For dev use only (do NOT use with CI):
+
+    # def test__draw(self):
+    #     print()
+    #     cue = Password(self.name, self.message)
+
+    #     answer = cue.send()
+    #     print(answer)
+
+    # def test__draw_message_endswith_alnum(self):
+    #     print()
+    #     cue = Password(self.name, self.message_endswith_alnum)
+
+    #     answer = cue.send()
+    #     print(answer)
+
+
+def test_main(monkeypatch):
+    monkeypatch.setattr(Password, 'send', lambda _: None)
+    assert password.main() is None