Rename argument

Author: donBarbos

Doc/library/getpass.rst

@@ -16,7 +16,7 @@
 
 The :mod:`getpass` module provides two functions:
 
-.. function:: getpass(prompt='Password: ', stream=None, mask=None)
+.. function:: getpass(prompt='Password: ', stream=None, *, echochar=None)
 
    Prompt the user for a password without echoing.  The user is prompted using
    the string *prompt*, which defaults to ``'Password: '``.  On Unix, the
@@ -25,10 +25,11 @@ The :mod:`getpass` module provides two functions:
    (:file:`/dev/tty`) or if that is unavailable to ``sys.stderr`` (this
    argument is ignored on Windows).
 
-   The *mask* argument controls how user input is displayed while typing. If
-   *mask* is ``None`` (default), input remains hidden. If *mask* is a string,
-   each typed character is replaced with the given string. For example,
-   ``mask='*'`` will display asterisks instead of the actual input.
+   The *echochar* argument controls how user input is displayed while typing.
+   If *echochar* is ``None`` (default), input remains hidden. If *echochar* is
+   a string, each typed character is replaced with the given string.
+   For example, ``echochar='*'`` will display asterisks instead of the actual
+   input.
 
    If echo free input is unavailable getpass() falls back to printing
    a warning message to *stream* and reading from ``sys.stdin`` and

Doc/whatsnew/3.14.rst

@@ -562,7 +562,9 @@ getopt
 getpass
 -------
 
-* Add optional argument *mask* for :meth:`getpass.getpass`.
+* Support keyboard feedback by :func:`getpass.getpass` via the keyword-only
+  optional argument ``echochar``. Placeholder characters are rendered whenever
+  a character is entered, and removed when a character is deleted.
   (Contributed by Semyon Moroz in :gh:`77065`.)
 
 

Lib/getpass.py

@@ -1,7 +1,7 @@
 """Utilities to get a password and/or the current user name.
 
-getpass(prompt[, stream[, mask]]) - Prompt for a password, with echo
-turned off.
+getpass(prompt[, stream[, echochar]]) - Prompt for a password, with echo
+turned off and optional keyboard feedback.
 getuser() - Get the user name from the environment or password database.
 
 GetPassWarning - This UserWarning is issued when getpass() cannot prevent
@@ -26,14 +26,15 @@
 class GetPassWarning(UserWarning): pass
 
 
-def unix_getpass(prompt='Password: ', stream=None, mask=None):
+def unix_getpass(prompt='Password: ', stream=None, *, echochar=None):
     """Prompt for a password, with echo turned off.
 
     Args:
       prompt: Written on stream to ask for the input.  Default: 'Password: '
       stream: A writable file object to display the prompt.  Defaults to
               the tty.  If no tty is available defaults to sys.stderr.
-      mask: A string used to mask input (e.g., '*'). If None, input is hidden.
+      echochar: A string used to mask input (e.g., '*').  If None, input is
+              hidden.
     Returns:
       The seKr3t input.
     Raises:
@@ -70,14 +71,14 @@ def unix_getpass(prompt='Password: ', stream=None, mask=None):
                 old = termios.tcgetattr(fd)     # a copy to save
                 new = old[:]
                 new[3] &= ~termios.ECHO  # 3 == 'lflags'
-                if mask:
+                if echochar:
                     new[3] &= ~termios.ICANON
                 tcsetattr_flags = termios.TCSAFLUSH
                 if hasattr(termios, 'TCSASOFT'):
                     tcsetattr_flags |= termios.TCSASOFT
                 try:
                     termios.tcsetattr(fd, tcsetattr_flags, new)
-                    if not mask:
+                    if not echochar:
                         passwd = _raw_input(prompt, stream, input=input)
                         stream.write('\n')
                         return passwd
@@ -92,14 +93,14 @@ def unix_getpass(prompt='Password: ', stream=None, mask=None):
                         if char == '\x03':
                             raise KeyboardInterrupt
                         if char == '\x7f' or char == '\b':
-                            if mask and passwd:
-                                stream.write("\b \b" * len(mask))
+                            if echochar and passwd:
+                                stream.write("\b \b" * len(echochar))
                                 stream.flush()
                             passwd = passwd[:-1]
                         else:
                             passwd += char
-                            if mask:
-                                stream.write(mask)
+                            if echochar:
+                                stream.write(echochar)
                                 stream.flush()
                 finally:
                     termios.tcsetattr(fd, tcsetattr_flags, old)
@@ -120,7 +121,7 @@ def unix_getpass(prompt='Password: ', stream=None, mask=None):
         return passwd
 
 
-def win_getpass(prompt='Password: ', stream=None, mask=None):
+def win_getpass(prompt='Password: ', stream=None, *, echochar=None):
     """Prompt for password with echo off, using Windows getwch()."""
     if sys.stdin is not sys.__stdin__:
         return fallback_getpass(prompt, stream)
@@ -135,16 +136,16 @@ def win_getpass(prompt='Password: ', stream=None, mask=None):
         if c == '\003':
             raise KeyboardInterrupt
         if c == '\b':
-            if mask and pw:
-                for _ in mask:
+            if echochar and pw:
+                for _ in echochar:
                     msvcrt.putwch('\b')
                     msvcrt.putwch(' ')
                     msvcrt.putwch('\b')
             pw = pw[:-1]
         else:
             pw = pw + c
-            if mask:
-                msvcrt.putwch(mask)
+            if echochar:
+                msvcrt.putwch(echochar)
     msvcrt.putwch('\r')
     msvcrt.putwch('\n')
     return pw

Misc/NEWS.d/next/Library/2025-02-24-07-08-11.gh-issue-77065.8uW0Wf.rst

@@ -1,2 +1,2 @@
-Added optional argument *mask* for :meth:`getpass.getpass`. Patch by
-Semyon Moroz.
+Add keyword-only optional argument *mask* for :meth:`getpass.getpass`.
+Patch by Semyon Moroz.