certbot.display

Certbot display utilities.

certbot.display.util

Certbot display.

certbot.display.util.DSELECT_HELP = 'Use the arrow keys or Tab to move between window elements. Space can be used to complete the input path with the selected element in the directory window. Pressing enter will select the currently highlighted button.'

Help text on how to use dialog’s dselect.

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.

certbot.display.util.ESC = 'esc'

Display exit code when the user hits Escape

certbot.display.util._wrap_lines(msg)[source]

Format lines nicely to 80 chars.

Parameters:msg (str) – Original message
Returns:Formatted message respecting newlines in message
Return type:str
certbot.display.util._clean(dialog_result)[source]

Treat sundy python-dialog return codes as CANCEL

Parameters:dialog_result (tuple) – (code, result)
Returns:the argument but with unknown codes set to -1 (Error)
Return type:tuple
class certbot.display.util.NcursesDisplay(width=72, height=20)[source]

Bases: object

Ncurses-based display.

notification(message, height=10, pause=False)[source]

Display a notification to the user and wait for user acceptance.

Todo

It probably makes sense to use one of the transient message types for pause. It isn’t straightforward how best to approach the matter though given the context of our messages. http://pythondialog.sourceforge.net/doc/widgets.html#displaying-transient-messages

Parameters:
  • message (str) – Message to display
  • height (int) – Height of the dialog box
  • pause (bool) – Not applicable to NcursesDisplay
menu(message, choices, ok_label='OK', cancel_label='Cancel', help_label='', **unused_kwargs)[source]

Display a menu.

Parameters:
  • message (str) – title of menu
  • choices (list of tuples (tag, item) tags must be unique or list of items (tags will be enumerated)) – menu lines, len must be > 0
  • ok_label (str) – label of the OK button
  • help_label (str) – label of the help button
  • unused_kwargs (dict) – absorbs default / cli_args
Returns:

tuple of the form (code, index) where code - display exit code int - index of the selected item

Return type:

tuple

input(message, **unused_kwargs)[source]

Display an input box to the user.

Parameters:
  • message (str) – Message to display that asks for input.
  • _kwargs (dict) – absorbs default / cli_args
Returns:

tuple of the form (code, string) where code - display exit code string - input entered by the user

yesno(message, yes_label='Yes', no_label='No', **unused_kwargs)[source]

Display a Yes/No dialog box.

Yes and No label must begin with different letters.

Parameters:
  • message (str) – message to display to user
  • yes_label (str) – label on the “yes” button
  • no_label (str) – label on the “no” button
  • _kwargs (dict) – absorbs default / cli_args
Returns:

if yes_label was selected

Return type:

bool

checklist(message, tags, default_status=True, **unused_kwargs)[source]

Displays a checklist.

Parameters:
  • message – Message to display before choices
  • tags (list) – where each is of type str len(tags) > 0
  • default_status (bool) – If True, items are in a selected state by default.
  • _kwargs (dict) – absorbs default / cli_args
Returns:

tuple of the form (code, list_tags) where code - display exit code list_tags - list of str tags selected by the user

directory_select(message, **unused_kwargs)[source]

Display a directory selection screen.

Parameters:message (str) – prompt to give the user
Returns:tuple of the form (code, string) where code - display exit code string - input entered by the user
class certbot.display.util.FileDisplay(outfile)[source]

Bases: object

File-based display.

notification(message, height=10, pause=True)[source]

Displays a notification and waits for user acceptance.

Parameters:
  • message (str) – Message to display
  • height (int) – No effect for FileDisplay
  • pause (bool) – Whether or not the program should pause for the user’s confirmation
menu(message, choices, ok_label='', cancel_label='', help_label='', **unused_kwargs)[source]

Display a menu.

Todo

This doesn’t enable the help label/button (I wasn’t sold on any interface I came up with for this). It would be a nice feature

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
  • _kwargs (dict) – absorbs default / cli_args
Returns:

tuple of (code, index) where code - str display exit code index - int index of the user’s selection

Return type:

tuple

input(message, **unused_kwargs)[source]

Accept input from the user.

Parameters:
  • message (str) – message to display to the user
  • _kwargs (dict) – absorbs default / cli_args
Returns:

tuple of (code, input) where code - str display exit code input - str of the user’s input

Return type:

tuple

yesno(message, yes_label='Yes', no_label='No', **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
  • _kwargs (dict) – absorbs default / cli_args
Returns:

True for “Yes”, False for “No”

Return type:

bool

checklist(message, tags, default_status=True, **unused_kwargs)[source]

Display a checklist.

Parameters:
  • message (str) – Message to display to user
  • tags (list) – str tags to select, len(tags) > 0
  • default_status (bool) – Not used for FileDisplay
  • _kwargs (dict) – absorbs default / cli_args
Returns:

tuple of (code, tags) where code - str display exit code tags - list of selected tags

Return type:

tuple

directory_select(message, **unused_kwargs)[source]

Display a directory selection screen.

Parameters:message (str) – prompt to give the user
Returns:tuple of the form (code, string) where code - display exit code string - input entered by the user
_scrub_checklist_input(indices, tags)[source]

Validate input and transform indices to appropriate tags.

Parameters:
  • indices (list) – input
  • tags (list) – Original tags of the checklist
Returns:

valid tags the user selected

Return type:

list of str

_print_menu(message, choices)[source]

Print a menu on the screen.

Parameters:
  • message (str) – title of menu
  • choices (list of tuples (tag, item) or list of descriptions (tags will be enumerated)) – Menu lines
_get_valid_int_ans(max_)[source]

Get a numerical selection.

Parameters:max (int) – The maximum entry (len of choices), must be positive
Returns:tuple of the form (code, selection) where code - str display exit code (‘ok’ or cancel’) selection - int user’s selection
Return type:tuple
class certbot.display.util.NoninteractiveDisplay(outfile)[source]

Bases: object

An iDisplay implementation that never asks for interactive user input

_interaction_fail(message, cli_flag, extra='')[source]

Error out in case of an attempt to interact in noninteractive mode

notification(message, height=10, pause=False)[source]

Displays a notification without waiting for user acceptance.

Parameters:
  • message (str) – Message to display to stdout
  • height (int) – No effect for NoninteractiveDisplay
  • pause (bool) – The NoninteractiveDisplay waits for no keyboard
menu(message, choices, ok_label=None, cancel_label=None, help_label=None, default=None, cli_flag=None)[source]

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) where code - str display exit code index - 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)[source]

Accept input from the user.

Parameters:message (str) – message to display to the user
Returns:tuple of (code, input) where code - str display exit code input - 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)[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, **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) where code - str display exit code tags - list of selected tags

Return type:

tuple

directory_select(message, default=None, cli_flag=None)[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 not None, 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) where code - int display exit code string - 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._parens_around_char(label)[source]

Place parens around first character of label.

Parameters:label (str) – Must contain at least one character

certbot.display.ops

Contains UI methods for LE user operations.

certbot.display.ops.get_email(invalid=False, optional=True)[source]

Prompt for valid email address.

Parameters:
  • invalid (bool) – True if an invalid address was provided by the user
  • optional (bool) – True if the user can use –register-unsafely-without-email to avoid providing an e-mail
Returns:

e-mail address

Return type:

str

Raises:

errors.Error – if the user cancels

certbot.display.ops.choose_account(accounts)[source]

Choose an account.

Parameters:accounts (list) – Containing at least one Account
certbot.display.ops.choose_names(installer)[source]

Display screen to select domains to validate.

Parameters:installer (certbot.interfaces.IInstaller) – An installer object
Returns:List of selected names
Return type:list of str
certbot.display.ops.get_valid_domains(domains)[source]
Helper method for choose_names that implements basic checks
on domain names
Parameters:domains (list) – Domain names to validate
Returns:List of valid domains
Return type:list
certbot.display.ops._filter_names(names)[source]

Determine which names the user would like to select from a list.

Parameters:names (list) – domain names
Returns:tuple of the form (code, names) where code - str display exit code names - list of names selected
Return type:tuple
certbot.display.ops._choose_names_manually(prompt_prefix='')[source]

Manually input names for those without an installer.

Parameters:prompt_prefix (str) – string to prepend to prompt for domains
Returns:list of provided names
Return type:list of str
certbot.display.ops.success_installation(domains)[source]

Display a box confirming the installation of HTTPS.

Todo

This should be centered on the screen

Parameters:domains (list) – domain names which were enabled
certbot.display.ops.success_renewal(domains, action)[source]

Display a box confirming the renewal of an existing certificate.

Todo

This should be centered on the screen

Parameters:
  • domains (list) – domain names which were renewed
  • action (str) – can be “reinstall” or “renew”
certbot.display.ops._gen_ssl_lab_urls(domains)[source]

Returns a list of urls.

Parameters:domains (list) – Each domain is a ‘str’
certbot.display.ops._gen_https_names(domains)[source]

Returns a string of the https domains.

Domains are formatted nicely with https:// prepended to each.

Parameters:domains (list) – Each domain is a ‘str’

certbot.display.enhancements

Certbot Enhancement Display

certbot.display.enhancements.ask(enhancement)[source]

Display the enhancement to the user.

Parameters:enhancement (str) – One of the certbot.CONFIG.ENHANCEMENTS enhancements
Returns:True if feature is desired, False otherwise
Return type:bool
Raises:.errors.Error – if the enhancement provided is not supported
certbot.display.enhancements.redirect_by_default()[source]

Determines whether the user would like to redirect to HTTPS.

Returns:True if redirect is desired, False otherwise
Return type:bool