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