| 1 |
:mod:`!getpass` --- Portable password input |
| 2 |
=========================================== |
| 3 |
|
| 4 |
.. module:: getpass |
| 5 |
:synopsis: Portable reading of passwords and retrieval of the userid. |
| 6 |
|
| 7 |
.. moduleauthor:: Piers Lauder <[email protected]> |
| 8 |
.. sectionauthor:: Fred L. Drake, Jr. <[email protected]> |
| 9 |
.. Windows (& Mac?) support by Guido van Rossum. |
| 10 |
|
| 11 |
**Source code:** :source:`Lib/getpass.py` |
| 12 |
|
| 13 |
-------------- |
| 14 |
|
| 15 |
.. include:: ../includes/wasm-notavail.rst |
| 16 |
|
| 17 |
The :mod:`!getpass` module provides two functions: |
| 18 |
|
| 19 |
.. function:: getpass(prompt='Password: ', stream=None, *, echo_char=None) |
| 20 |
|
| 21 |
Prompt the user for a password without echoing. The user is prompted using |
| 22 |
the string *prompt*, which defaults to ``'Password: '``. On Unix, the |
| 23 |
prompt is written to the file-like object *stream* using the replace error |
| 24 |
handler if needed. *stream* defaults to the controlling terminal |
| 25 |
(:file:`/dev/tty`) or if that is unavailable to ``sys.stderr`` (this |
| 26 |
argument is ignored on Windows). |
| 27 |
|
| 28 |
The *echo_char* argument controls how user input is displayed while typing. |
| 29 |
If *echo_char* is ``None`` (default), input remains hidden. Otherwise, |
| 30 |
*echo_char* must be a single printable ASCII character and each |
| 31 |
typed character is replaced by it. For example, ``echo_char='*'`` will |
| 32 |
display asterisks instead of the actual input. |
| 33 |
|
| 34 |
If echo free input is unavailable getpass() falls back to printing |
| 35 |
a warning message to *stream* and reading from ``sys.stdin`` and |
| 36 |
issuing a :exc:`GetPassWarning`. |
| 37 |
|
| 38 |
.. note:: |
| 39 |
If you call getpass from within IDLE, the input may be done in the |
| 40 |
terminal you launched IDLE from rather than the idle window itself. |
| 41 |
|
| 42 |
.. note:: |
| 43 |
On Unix systems, when *echo_char* is set, the terminal will be |
| 44 |
configured to operate in |
| 45 |
:manpage:`noncanonical mode <termios(3)#Canonical_and_noncanonical_mode>`. |
| 46 |
In particular, this means that line editing shortcuts such as |
| 47 |
:kbd:`Ctrl+U` will not work and may insert unexpected characters into |
| 48 |
the input. |
| 49 |
|
| 50 |
.. versionchanged:: 3.14 |
| 51 |
Added the *echo_char* parameter for keyboard feedback. |
| 52 |
|
| 53 |
.. exception:: GetPassWarning |
| 54 |
|
| 55 |
A :exc:`UserWarning` subclass issued when password input may be echoed. |
| 56 |
|
| 57 |
|
| 58 |
.. function:: getuser() |
| 59 |
|
| 60 |
Return the "login name" of the user. |
| 61 |
|
| 62 |
This function checks the environment variables :envvar:`LOGNAME`, |
| 63 |
:envvar:`USER`, :envvar:`!LNAME` and :envvar:`USERNAME`, in order, and |
| 64 |
returns the value of the first one which is set to a non-empty string. If |
| 65 |
none are set, the login name from the password database is returned on |
| 66 |
systems which support the :mod:`pwd` module, otherwise, an :exc:`OSError` |
| 67 |
is raised. |
| 68 |
|
| 69 |
In general, this function should be preferred over :func:`os.getlogin`. |
| 70 |
|
| 71 |
.. versionchanged:: 3.13 |
| 72 |
Previously, various exceptions beyond just :exc:`OSError` were raised. |