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)[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 selectionReturn 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 inputReturn 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) > 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
,tags
) wherecode
- str display exit codetags
- list of selected tagsReturn 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 selectionReturn 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 inputReturn 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) > 0 - kwargs (dict) – absorbs default_status arg
Returns: tuple of (
code
,tags
) wherecode
- str display exit codetags
- list of selected tagsReturn 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)[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 domainsReturns: the domain list summary Return type: str