`getpass`'s `echo_char` should be restricted to a single ASCII character

[benjaminjohnson01]

Bug report

Bug description:

Running getpass.getpass(echo_char="***") works until a character is entered, at which point a traceback error occurs.

import getpass
getpass.getpass(echo_char="***")

Password: Traceback (most recent call last):
  File "<python-input-10>", line 1, in <module>
    getpass.getpass(echo_char="***")
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "...\pythoncore-3.14-64\Lib\getpass.py", line 129, in win_getpass
    msvcrt.putwch(echo_char)
    ~~~~~~~~~~~~~^^^^^^^^^^^
TypeError: putwch(): argument must be a unicode character, not a string of length 3

Validation should occur upon input for this argument, and getpass should raise a ValueError stating: "'echo_char' must be a single-character ASCII string, not a string of length 3" (with ASCII only being bolded in this write-up for emphasis that a Unicode character cannot be used).

Additionally, the error message language should be revised when a non-ASCII string is entered:

import getpass
getpass.getpass(echo_char="Æ")

Traceback (most recent call last):
  File "<python-input-11>", line 1, in <module>
    getpass.getpass(echo_char="Æ")
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "...\pythoncore-3.14-64\Lib\getpass.py", line 109, in win_getpass
    _check_echo_char(echo_char)
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^
  File "...\pythoncore-3.14-64\Lib\getpass.py", line 149, in _check_echo_char
    raise ValueError("'echo_char' must be a printable ASCII string, "
                     f"got: {echo_char!r}")
ValueError: 'echo_char' must be a printable ASCII string, got: 'Æ'

Better language would be: "'echo_char' must be a single-character ASCII string, got: 'Æ'".

With agreement, I can submit a pull request.

CPython versions tested on:

3.14

Operating systems tested on:

Windows

Linked PRs

• gh-138514: getpass: restrict echo_char to a single ASCII character #138591
• [3.14] gh-138514: getpass: restrict echo_char to a single ASCII character (GH-138591) #138988

[brianschubert]

Note that the error when using a multi-character echo_char only occurs on Windows; the unix implementation is able to handle multi-character values (whether intended or not).

[benjaminjohnson01]

If multi-character values are allowed on Unix-based systems, should this issue instead be resolved by adjusting the code to work with multi-character echo_char strings on Windows?

[uranusjr]

the unix implementation is able to handle multi-character values

Does it? It does the same check right at the top

cpython/Lib/getpass.py

Line 46 in fc0305a

_check_echo_char(echo_char)

Reading the implementation, I’m inclined to say the feature should only accept ASCII, and it’s a bug if it behaves otherwise.

[donBarbos]

Thank you for noticing this inconsistency!
I would prefer to keep the ability to pass in strings longer than a single character, allowing for a more permissive behavior.
I don’t currently have access to a Windows machine to test this, but it seems the issue could be solved fairly easily by adding the output one at a time:

if echo_char:
    for c in echo_char: # new loop
        msvcrt.putwch(c)

And I’d like to point out that it would be great if tests for Windows could be implemented (for a separate issue #130524), since they are still missing. That way, we could ensure consistent behavior across all implementations.

[benjaminjohnson01]

I can implement multi-character acceptance on Windows! I could also complete the test cases, because I have a Windows machine to test on.

[brianschubert]

I think it would be preferable to limit this to single characters strings for the reasons @picnixz gave in #130496 (comment). Support for longer strings and/or non-ASCII characters can always be added later.

It also seems that the unix implementation doesn't work with multi-character strings either, just in a different way. It can accept and print longer strings, but the output becomes garbled if you try to delete characters

[brianschubert]

Another possibly unintended behavior: passing echo_char disables line editing on the Unix implementation. For example, the result of entering foo CTRL+U bar varies depending on if echo_char is passed:

>>> getpass.getpass()
Password: 
'bar'
>>> getpass.getpass(echo_char="*")
Password: *******
'foo\x15bar'

[benjaminjohnson01]

I agree. While I like the idea of handling multi-character strings in theory, it does not seem necessary for most users, and if it adds complexity with additional edge cases, perhaps it is worth modifying this feature to accept only a single ASCII character.

If so, does the proposed language in the bug report sound good?

I have both Windows and Unix machines, and I am happy to implement these changes for both the Windows and Unix implementations.

[benjaminjohnson01]

As for line editing -- I think it should be allowed in all cases on Unix systems.