Debian Codegraph @

Doc/library/getpass.rst

raw
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.