certbot.display.util module¶
Certbot display.
This module (certbot.display.util
) or its companion certbot.display.ops
should be used whenever:
Displaying status information to the user on the terminal
Collecting information from the user via prompts
Other messages can use the logging
module. See log.py
.
-
certbot.display.util.
OK
= 'ok'¶ Display exit code indicating user acceptance.
-
certbot.display.util.
CANCEL
= 'cancel'¶ Display exit code for a user canceling the display.
-
certbot.display.util.
HELP
= 'help'¶ Display exit code when for when the user requests more help. (UNUSED)
-
certbot.display.util.
ESC
= 'esc'¶ Display exit code when the user hits Escape (UNUSED)
-
certbot.display.util.
SIDE_FRAME
= '- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -'¶ Display boundary (alternates spaces, so when copy-pasted, markdown doesn’t interpret it as a heading)
-
certbot.display.util.
input_with_timeout
(prompt=None, timeout=36000.0)[source]¶ Get user input with a timeout.
Behaves the same as six.moves.input, however, an error is raised if a user doesn’t answer after timeout seconds. The default timeout value was chosen to place it just under 12 hours for users following our advice and running Certbot twice a day.
- Parameters
prompt (str) – prompt to provide for input
timeout (float) – maximum number of seconds to wait for input
- Returns
user response
- Return type
str
:raises errors.Error if no answer is given before the timeout
-
certbot.display.util.
notify
(msg: str) → None[source]¶ Display a basic status message.
- Parameters
msg (str) – message to display
-
class
certbot.display.util.
FileDisplay
(outfile, force_interactive)[source]¶ Bases:
object
File-based display.
-
notification
(message, pause=True, wrap=True, force_interactive=False, decorate=True)[source]¶ Displays a notification and waits for user acceptance.
- Parameters
message (str) – Message to display
pause (bool) – Whether or not the program should pause for the user’s confirmation
wrap (bool) – Whether or not the application should wrap text
force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions
decorate (bool) – Whether to surround the message with a decorated frame
Display a menu.
- Parameters
message (str) – title of menu
choices (list of tuples (tag, item) or list of descriptions (tags will be enumerated)) – Menu lines, len must be > 0
default – default value to return (if one exists)
cli_flag (str) – option used to set this value with the CLI
force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions
- Returns
tuple of (
code
,index
) wherecode
- str display exit codeindex
- int index of the user’s selection- Return type
tuple
-
input
(message, default=None, cli_flag=None, force_interactive=False, **unused_kwargs)[source]¶ Accept input from the user.
- Parameters
message (str) – message to display to the user
default – default value to return (if one exists)
cli_flag (str) – option used to set this value with the CLI
force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions
- Returns
tuple of (
code
,input
) wherecode
- str display exit codeinput
- str of the user’s input- Return type
tuple
-
yesno
(message, yes_label='Yes', no_label='No', default=None, cli_flag=None, force_interactive=False, **unused_kwargs)[source]¶ Query the user with a yes/no question.
Yes and No label must begin with different letters, and must contain at least one letter each.
- Parameters
message (str) – question for the user
yes_label (str) – Label of the “Yes” parameter
no_label (str) – Label of the “No” parameter
default – default value to return (if one exists)
cli_flag (str) – option used to set this value with the CLI
force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions
- Returns
True for “Yes”, False for “No”
- Return type
bool
-
checklist
(message, tags, default=None, cli_flag=None, force_interactive=False, **unused_kwargs)[source]¶ Display a checklist.
- Parameters
message (str) – Message to display to user
tags (list) –
str
tags to select, len(tags) > 0default – default value to return (if one exists)
cli_flag (str) – option used to set this value with the CLI
force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions
- Returns
tuple of (
code
,tags
) wherecode
- str display exit codetags
- list of selected tags- Return type
tuple
-
directory_select
(message, default=None, cli_flag=None, force_interactive=False, **unused_kwargs)[source]¶ Display a directory selection screen.
- Parameters
message (str) – prompt to give the user
default – default value to return (if one exists)
cli_flag (str) – option used to set this value with the CLI
force_interactive (bool) – True if it’s safe to prompt the user because it won’t cause any workflow regressions
- Returns
tuple of the form (
code
,string
) wherecode
- display exit codestring
- input entered by the user
-
-
certbot.display.util.
assert_valid_call
(prompt, default, cli_flag, force_interactive)[source]¶ Verify that provided arguments is a valid IDisplay call.
- Parameters
prompt (str) – prompt for the user
default – default answer to prompt
cli_flag (str) – command line option for setting an answer to this question
force_interactive (bool) – if interactivity is forced by the IDisplay call
-
class
certbot.display.util.
NoninteractiveDisplay
(outfile, *unused_args, **unused_kwargs)[source]¶ Bases:
object
An iDisplay implementation that never asks for interactive user input
-
notification
(message, pause=False, wrap=True, decorate=True, **unused_kwargs)[source]¶ Displays a notification without waiting for user acceptance.
- Parameters
message (str) – Message to display to stdout
pause (bool) – The NoninteractiveDisplay waits for no keyboard
wrap (bool) – Whether or not the application should wrap text
decorate (bool) – Whether to apply a decorated frame to the message
Avoid displaying a menu.
- Parameters
message (str) – title of menu
choices (list of tuples (tag, item) or list of descriptions (tags will be enumerated)) – Menu lines, len must be > 0
default (int) – the default choice
kwargs (dict) – absorbs various irrelevant labelling arguments
- Returns
tuple of (
code
,index
) wherecode
- str display exit codeindex
- int index of the user’s selection- Return type
tuple
- Raises
errors.MissingCommandlineFlag – if there was no default
-
input
(message, default=None, cli_flag=None, **unused_kwargs)[source]¶ Accept input from the user.
- Parameters
message (str) – message to display to the user
- Returns
tuple of (
code
,input
) wherecode
- str display exit codeinput
- str of the user’s input- Return type
tuple
- Raises
errors.MissingCommandlineFlag – if there was no default
-
yesno
(message, yes_label=None, no_label=None, default=None, cli_flag=None, **unused_kwargs)[source]¶ Decide Yes or No, without asking anybody
- Parameters
message (str) – question for the user
kwargs (dict) – absorbs yes_label, no_label
- Raises
errors.MissingCommandlineFlag – if there was no default
- Returns
True for “Yes”, False for “No”
- Return type
bool
-
checklist
(message, tags, default=None, cli_flag=None, **unused_kwargs)[source]¶ Display a checklist.
- Parameters
message (str) – Message to display to user
tags (list) –
str
tags to select, len(tags) > 0kwargs (dict) – absorbs default_status arg
- Returns
tuple of (
code
,tags
) wherecode
- str display exit codetags
- list of selected tags- Return type
tuple
-
directory_select
(message, default=None, cli_flag=None, **unused_kwargs)[source]¶ Simulate prompting the user for a directory.
This function returns default if it is not
None
, otherwise, an exception is raised explaining the problem. If cli_flag is notNone
, the error message will include the flag that can be used to set this value with the CLI.- Parameters
message (str) – prompt to give the user
default – default value to return (if one exists)
cli_flag (str) – option used to set this value with the CLI
- Returns
tuple of the form (
code
,string
) wherecode
- int display exit codestring
- input entered by the user
-
-
certbot.display.util.
separate_list_input
(input_)[source]¶ Separate a comma or space separated list.
- Parameters
input (str) – input from the user
- Returns
strings
- Return type
list
-
certbot.display.util.
summarize_domain_list
(domains: List[str]) → str[source]¶ - Summarizes a list of domains in the format of:
example.com.com and N more domains
- or if there is are only two domains:
example.com and www.example.com
- or if there is only one domain:
example.com
- Parameters
domains (list) –
str
list of domains- Returns
the domain list summary
- Return type
str