meerschaum.utils.prompt

  1#! /usr/bin/env python
  2# -*- coding: utf-8 -*-
  3# vim:fenc=utf-8
  4
  5"""
  6Functions for interacting with the user.
  7"""
  8
  9from __future__ import annotations
 10import os
 11from meerschaum.utils.typing import Any, Union, Optional, Tuple, List
 12
 13
 14def prompt(
 15    question: str,
 16    icon: bool = True,
 17    default: Union[str, Tuple[str, str], None] = None,
 18    default_editable: Optional[str] = None,
 19    detect_password: bool = True,
 20    is_password: bool = False,
 21    wrap_lines: bool = True,
 22    noask: bool = False,
 23    **kw: Any
 24) -> str:
 25    """
 26    Ask the user a question and return the answer.
 27    Wrapper around `prompt_toolkit.prompt()` with modified behavior.
 28    For example, an empty string returns default instead of printing it for the user to delete
 29    (`prompt_toolkit` behavior).
 30
 31    Parameters
 32    ----------
 33    question: str
 34        The question to print to the user.
 35
 36    icon: bool, default True
 37        If True, prepend the configured icon.
 38
 39    default: Union[str, Tuple[str, str], None], default None
 40        If the response is '', return the default value.
 41
 42    default_editable: Optional[str], default None
 43        If provided, auto-type this user-editable string in the prompt.
 44
 45    detect_password: bool, default True
 46        If `True`, set the input method to a censored password box if the word `password`
 47        appears in the question.
 48
 49    is_password: default False
 50        If `True`, set the input method to a censored password box.
 51        May be overridden by `detect_password` unless `detect_password` is set to `False`.
 52
 53    wrap_lines: bool, default True
 54        If `True`, wrap the text across multiple lines.
 55        Flag is passed onto `prompt_toolkit`.
 56
 57    noask: bool, default False
 58        If `True`, only print the question and return the default answer.
 59
 60    Returns
 61    -------
 62    A `str` of the input provided by the user.
 63
 64    """
 65    from meerschaum.utils.packages import attempt_import
 66    from meerschaum.utils.formatting import colored, ANSI, CHARSET, highlight_pipes, fill_ansi
 67    from meerschaum.config import get_config
 68    from meerschaum.config.static import _static_config
 69    from meerschaum.utils.misc import filter_keywords
 70    from meerschaum.utils.daemon import running_in_daemon
 71    noask = check_noask(noask)
 72    if not noask:
 73        prompt_toolkit = attempt_import('prompt_toolkit')
 74    question_config = get_config('formatting', 'question', patch=True)
 75
 76    ### if a default is provided, append it to the question.
 77    default_answer = default
 78    if default is not None:
 79        question += " (default: "
 80        if isinstance(default, tuple) and len(default) > 1:
 81            question += f"{default[0]} [{default[1]}]"
 82            default_answer = default[0]
 83        else:
 84            question += f"{default}"
 85        question += ")"
 86
 87    ### detect password
 88    if (detect_password and 'password' in question.lower()) or is_password:
 89        kw['is_password'] = True
 90
 91    ### Add the icon and only color the first line.
 92    lines = question.split('\n')
 93    first_line = lines[0]
 94    other_lines = '' if len(lines) <= 1 else '\n'.join(lines[1:])
 95
 96    if ANSI:
 97        first_line = fill_ansi(highlight_pipes(first_line), **question_config['ansi']['rich'])
 98        other_lines = highlight_pipes(other_lines)
 99
100    _icon = question_config[CHARSET]['icon']
101    question = (' ' + _icon + ' ') if icon and len(_icon) > 0 else ''
102    question += first_line
103    if len(other_lines) > 0:
104        question += '\n' + other_lines
105    question += ' '
106
107    if not running_in_daemon():
108        answer = (
109            prompt_toolkit.prompt(
110                prompt_toolkit.formatted_text.ANSI(question),
111                wrap_lines=wrap_lines,
112                default=default_editable or '',
113                **filter_keywords(prompt_toolkit.prompt, **kw)
114            ) if not noask else ''
115        )
116    else:
117        print(question, end='\n', flush=True)
118        try:
119            answer = input() if not noask else ''
120        except EOFError:
121            answer = ''
122    if noask:
123        print(question)
124    if answer == '' and default is not None:
125        return default_answer
126    return answer
127
128
129def yes_no(
130        question: str = '',
131        options: Tuple[str, str] = ('y', 'n'),
132        default: str = 'y',
133        wrappers: Tuple[str, str] = ('[', ']'),
134        icon: bool = True,
135        yes: bool = False,
136        noask: bool = False,
137        **kw : Any
138    ) -> bool:
139    """
140    Print a question and prompt the user with a yes / no input.
141    Returns `True` for `'yes'`, False for `'no'`.
142
143    Parameters
144    ----------
145    question: str, default ''
146        The question to print to the user.
147
148    options: Tuple[str, str], default ('y', 'n')
149        The `y/n` options. The first is considered `True`, and all options must be lower case.
150
151    default: str, default y
152        The default option. Is represented with a capital to distinguish that it's the default.
153
154    wrappers: Tuple[str, str], default ('[', ']')
155        Text to print around the '[y/n]' options.
156
157    icon: bool, default True
158        If True, prepend the configured question icon.
159
160    Returns
161    -------
162    A bool indicating the user's choice.
163
164    Examples
165    --------
166    ```python-repl
167    >>> yes_no("Do you like me?", default='y')
168     ❓ Do you like me? [Y/n]
169    True
170    >>> yes_no("Cats or dogs?", options=('cats', 'dogs'))
171     ❓ Cats or dogs? [cats/dogs]
172     Please enter a valid response.
173     ❓ Cats or dogs? [cats/dogs] dogs
174    False
175    ```
176    """
177    from meerschaum.utils.warnings import error, warn
178    from meerschaum.utils.formatting import ANSI, UNICODE
179    from meerschaum.utils.packages import attempt_import
180
181    default = options[0] if yes else default
182    noask = yes or check_noask(noask)
183
184    ending = f" {wrappers[0]}" + "/".join(
185        [
186            o.upper() if o.lower() == default.lower()
187            else o.lower() for o in options
188        ]
189    ) + f"{wrappers[1]}"
190    while True:
191        try:
192            answer = prompt(question + ending, icon=icon, detect_password=False, noask=noask)
193            success = True
194        except KeyboardInterrupt:
195            success = False
196        
197        if not success:
198            error(f"Error getting response. Aborting...", stack=False)
199        if answer == "":
200            answer = default
201
202        if answer.lower() in options:
203            break
204        warn('Please enter a valid reponse.', stack=False)
205    
206    return answer.lower() == options[0].lower()
207
208def choose(
209        question: str,
210        choices: List[Union[str, Tuple[str, str]]],
211        default: Union[str, List[str], None] = None,
212        numeric: bool = True,
213        multiple: bool = False,
214        as_indices: bool = False,
215        delimiter: str = ',',
216        icon: bool = True,
217        warn: bool = True,
218        noask: bool = False,
219        **kw
220    ) -> Union[str, Tuple[str], None]:
221    """
222    Present a list of options and return the user's choice.
223
224    Parameters
225    ----------
226    question: str
227        The question to be printed.
228
229    choices: List[Union[str, Tuple[str, str]]
230        A list of options.
231        If an option is a tuple of two strings, the first string is treated as the index
232        and not displayed. In this case, set `as_indices` to `True` to return the index.
233
234    default: Union[str, List[str], None], default None
235        If the user declines to enter a choice, return this value.
236
237    numeric: bool, default True
238        If `True`, number the items in the list and ask for a number as input.
239        If `False`, require the user to type the complete string.
240
241    multiple: bool, default False
242        If `True`, allow the user to choose multiple answers separated by `delimiter`.
243
244    as_indices: bool, default False
245        If `True`, return the indices for the choices.
246        If a choice is a tuple of two strings, the first is assumed to be the index.
247        Otherwise the index in the list is returned.
248
249    delimiter: str, default ','
250        If `multiple`, separate answers by this string. Raise a warning if this string is contained
251        in any of the choices.
252
253    icon: bool, default True
254        If `True`, include the question icon.
255
256    warn: bool, default True
257        If `True`, raise warnings when invalid input is entered.
258
259    noask: bool, default False
260        If `True`, skip printing the question and return the default value.
261
262    Returns
263    -------
264    A string for a single answer or a tuple of strings if `multiple` is `True`.
265
266    """
267    from meerschaum.utils.warnings import warn as _warn
268    from meerschaum.utils.packages import attempt_import
269    from meerschaum.utils.misc import print_options
270    noask = check_noask(noask)
271
272    ### Handle empty choices.
273    if len(choices) == 0:
274        _warn(f"No available choices. Returning default value '{default}'.", stacklevel=3)
275        return default
276
277    ### If the default case is to include multiple answers, allow for multiple inputs.
278    if isinstance(default, list):
279        multiple = True
280
281    choices_indices = {}
282    for i, c in enumerate(choices):
283        if isinstance(c, tuple):
284            i, c = c
285        choices_indices[i] = c
286
287    def _enforce_default(d):
288        if d is not None and d not in choices and d not in choices_indices and warn:
289            _warn(
290                f"Default choice '{default}' is not contained in the choices {choices}. "
291                + "Setting numeric = False.",
292                stacklevel = 3
293            )
294            return False
295        return True
296
297    ### Throw a warning if the default isn't a choice.
298    for d in (default if isinstance(default, list) else [default]):
299        if not _enforce_default(d):
300            numeric = False
301            break
302
303    _default = default
304    _choices = list(choices_indices.values())
305    if multiple:
306        question += f"\n    Enter your choices, separated by '{delimiter}'.\n"
307
308    altered_choices = {}
309    altered_indices = {}
310    altered_default_indices = {}
311    delim_replacement = '_' if delimiter != '_' else '-'
312    can_strip_start_spaces, can_strip_end_spaces = True, True
313    for i, c in choices_indices.items():
314        if isinstance(c, tuple):
315            key, c = c
316        if can_strip_start_spaces and c.startswith(' '):
317            can_strip_start_spaces = False
318        if can_strip_end_spaces and c.endswith(' '):
319            can_strip_end_spaces = False
320
321    if multiple:
322        ### Check if the defaults have the delimiter.
323        for i, d in enumerate(default if isinstance(default, list) else [default]):
324            if d is None or delimiter not in d:
325                continue
326            new_d = d.replace(delimiter, delim_replacement)
327            altered_choices[new_d] = d
328            altered_default_indices[i] = new_d
329        for i, new_d in altered_default_indices.items():
330            if not isinstance(default, list):
331                default = new_d
332                break
333            default[i] = new_d
334
335        ### Check if the choices have the delimiter.
336        for i, c in choices_indices.items():
337            if delimiter in c and not numeric and warn:
338                _warn(
339                    f"The delimiter '{delimiter}' is contained within choice '{c}'.\n"
340                    + f"Replacing the string '{delimiter}' with '{delim_replacement}' in "
341                    + "the choice for correctly parsing input (will be replaced upon returning the prompt).",
342                    stacklevel = 3,
343                )
344                new_c = c.replace(delimiter, delim_replacement)
345                altered_choices[new_c] = c
346                altered_indices[i] = new_c
347        for i, new_c in altered_indices.items():
348            choices_indices[i] = new_c
349        default = delimiter.join(default) if isinstance(default, list) else default
350
351    question_options = []
352    if numeric:
353        _choices = [str(i + 1) for i, c in enumerate(choices)]
354        _default = ''
355        if default is not None:
356            for d in (default.split(delimiter) if multiple else [default]):
357                if d not in choices and d in choices_indices:
358                    d_index = d
359                    d_value = choices_indices[d]
360                    for _i, _option in enumerate(choices):
361                        if (
362                            isinstance(_option, tuple) and (
363                                _option[1] == d_value
364                                or
365                                _option[0] == d_index
366                            )
367                        ) or d_index == _i:
368                            d = _option
369
370                _d = str(choices.index(d) + 1)
371                _default += _d + delimiter
372        _default = _default[:-1 * len(delimiter)]
373        #  question += '\n'
374        choices_digits = len(str(len(choices)))
375        for i, c in enumerate(choices_indices.values()):
376            question_options.append(
377                f"  {i + 1}. "
378                + (" " * (choices_digits - len(str(i + 1))))
379                + f"{c}\n"
380            )
381        default_tuple = (_default, default) if default is not None else None
382    else:
383        default_tuple = default
384        #  question += '\n'
385        for c in choices_indices.values():
386            question_options.append(f"{c}\n")
387
388    if 'completer' not in kw:
389        WordCompleter = attempt_import('prompt_toolkit.completion').WordCompleter
390        kw['completer'] = WordCompleter(choices_indices.values(), sentence=True)
391
392    valid = False
393    while not valid:
394        print_options(question_options, header='')
395        answer = prompt(
396            question,
397            icon = icon,
398            default = default_tuple,
399            noask = noask,
400            **kw
401        )
402        ### Split along the delimiter.
403        _answers = [answer] if not multiple else [a for a in answer.split(delimiter)]
404
405        ### Remove trailing spaces if possible.
406        _answers = [(_a.rstrip(' ') if can_strip_end_spaces else _a) for _a in _answers]
407
408        ### Remove leading spaces if possible.
409        _answers = [(_a.lstrip(' ') if can_strip_start_spaces else _a) for _a in _answers]
410
411        ### Remove empty strings.
412        _answers = [_a for _a in _answers if _a]
413
414        if multiple and len(_answers) == 0:
415            _answers = default_tuple if isinstance(default_tuple, list) else [default_tuple]
416        answers = [altered_choices.get(a, a) for a in _answers]
417
418        valid = (len(answers) > 1 or not (len(answers) == 1 and answers[0] is None))
419        for a in answers:
420            if (
421                not a in {_original for _new, _original in altered_choices.items()}
422                and not a in _choices
423                and a != default
424                and not noask
425            ):
426                valid = False
427                break
428        if valid:
429            break
430        if warn:
431            _warn(f"Please pick a valid choice.", stack=False)
432
433    if not multiple:
434        if not numeric:
435            return answer
436        try:
437            _answer = choices[int(answer) - 1]
438            if as_indices and isinstance(choice, tuple):
439                return _answer[0]
440            return _answer
441        except Exception as e:
442            _warn(f"Could not cast answer '{answer}' to an integer.", stacklevel=3)
443
444    if not numeric:
445        return answers
446    _answers = []
447    for a in answers:
448        try:
449            _answer = choices[int(a) - 1]
450            _answer_to_return = altered_choices.get(_answer, _answer)
451            if isinstance(_answer_to_return, tuple) and as_indices:
452                _answer_to_return = _answer_to_return[0]
453            _answers.append(_answer_to_return)
454        except Exception as e:
455            _warn(f"Could not cast answer '{a}' to an integer.", stacklevel=3)
456    return _answers
457
458
459def get_password(
460        username: Optional[str] = None,
461        minimum_length: Optional[int] = None,
462        confirm: bool = True,
463        **kw: Any
464    ) -> str:
465    """
466    Prompt the user for a password.
467
468    Parameters
469    ----------
470    username: Optional[str], default None
471        If provided, print the username when asking for a password.
472
473    minimum_length: Optional[int], default None
474        If provided, enforce a password of at least this length.
475
476    confirm: bool, default True
477        If `True`, prompt the user for a password twice.
478
479    Returns
480    -------
481    The password string (censored from terminal output when typing).
482
483    Examples
484    --------
485    ```python-repl
486    >>> get_password()
487     ❓ Password: *******
488     ❓ Confirm password: *******
489    'hunter2'
490    ```
491
492    """
493    from meerschaum.utils.warnings import warn
494    while True:
495        password = prompt(
496            f"Password" + (f" for user '{username}':" if username is not None else ":"),
497            is_password = True,
498            **kw
499        )
500        if minimum_length is not None and len(password) < minimum_length:
501            warn(
502                "Password is too short. " +
503                f"Please enter a password that is at least {minimum_length} characters.",
504                stack = False
505            )
506            continue
507
508        if not confirm:
509            return password
510
511        _password = prompt(
512            f"Confirm password" + (f" for user '{username}':" if username is not None else ":"),
513            is_password = True,
514            **kw
515        )
516        if password != _password:
517            warn(f"Passwords do not match! Please try again.", stack=False)
518            continue
519        else:
520            return password
521
522
523def get_email(username: Optional[str] = None, allow_omit: bool = True, **kw: Any) -> str:
524    """
525    Prompt the user for an email and enforce that it's valid.
526
527    Parameters
528    ----------
529    username: Optional[str], default None
530        If provided, print the username in the prompt.
531
532    allow_omit: bool, default True
533        If `True`, allow the user to omit the email.
534
535    Returns
536    -------
537    The provided email string.
538
539    Examples
540    --------
541    ```python-repl
542    >>> get_email()
543     ❓ Email (empty to omit): foo@foo
544     Invalid email! Please try again.
545     ❓ Email (empty to omit): foo@foo.com
546    'foo@foo.com'
547    ```
548    """
549    from meerschaum.utils.warnings import warn
550    from meerschaum.utils.misc import is_valid_email
551    while True:
552        email = prompt(
553            f"Email" + (f" for user '{username}'" if username is not None else "") +
554            (" (empty to omit):" if allow_omit else ": "),
555            **kw
556        )
557        if (allow_omit and email == '') or is_valid_email(email):
558            return email
559        warn(f"Invalid email! Please try again.", stack=False)
560
561
562def check_noask(noask: bool = False) -> bool:
563    """
564    Flip `noask` to `True` if `MRSM_NOASK` is set.
565    """
566    from meerschaum.config.static import STATIC_CONFIG
567    NOASK = STATIC_CONFIG['environment']['noask']
568    if noask:
569        return True
570    return (
571        os.environ.get(NOASK, 'false').lower()
572        in ('1', 'true')
573    )