certbot.display

Certbot display utilities.

certbot.display.util

Certbot display.

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)

Format lines nicely to 80 chars.

Parameters:msg (str) – Original message Returns:Formatted message respecting newlines in message Return type:str

certbot.display.util.input_with_timeout(prompt=None, timeout=36000.0)

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

class certbot.display.util.FileDisplay(outfile, force_interactive)

Bases: object

File-based display.

notification(message, pause=True, wrap=True, force_interactive=False)

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

menu(message, choices, ok_label='', cancel_label='', help_label='', default=None, cli_flag=None, force_interactive=False, **unused_kwargs)

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
• 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) where code - str display exit code index - int index of the user’s selection

Return type:

tuple

input(message, default=None, cli_flag=None, force_interactive=False, **unused_kwargs)

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) where code - str display exit code input - 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)

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_status=True, default=None, cli_flag=None, force_interactive=False, **unused_kwargs)

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
• 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) where code - str display exit code tags - list of selected tags

Return type:

tuple

_return_default(prompt, default, cli_flag, force_interactive)

Should we return the default instead of prompting the user?

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

Returns:

True if we should return the default without prompting

Return type:

bool

_can_interact(force_interactive)

Can we safely interact with the user?

Parameters:force_interactive (bool) – if interactivity is forced by the IDisplay call Returns:True if the display can interact with the user Return type:bool

directory_select(message, default=None, cli_flag=None, force_interactive=False, **unused_kwargs)

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) where code - display exit code string - input entered by the user

_scrub_checklist_input(indices, tags)

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)

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_)

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

certbot.display.util.assert_valid_call(prompt, default, cli_flag, force_interactive)

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)

Bases: object

An iDisplay implementation that never asks for interactive user input

_interaction_fail(message, cli_flag, extra='')

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

notification(message, pause=False, wrap=True, **unused_kwargs)

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

menu(message, choices, ok_label=None, cancel_label=None, help_label=None, default=None, cli_flag=None, **unused_kwargs)

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, **unused_kwargs)

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, **unused_kwargs)

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)

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, **unused_kwargs)

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_)

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)

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)

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)

Choose an account.

Parameters:accounts (list) – Containing at least one Account

certbot.display.ops.choose_names(installer)

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)

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._sort_names(FQDNs)

Sort FQDNs by SLD (and if many, by their subdomains)

Parameters:FQDNs (list) – list of domain names Returns:Sorted list of domain names Return type:list

certbot.display.ops._filter_names(names)

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='')

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)

Display a box confirming the installation of HTTPS.

Parameters:domains (list) – domain names which were enabled

certbot.display.ops.success_renewal(domains)

Display a box confirming the renewal of an existing certificate.

Parameters:domains (list) – domain names which were renewed

certbot.display.ops.success_revocation(cert_path)

Display a box confirming a certificate has been revoked.

Parameters:cert_path (list) – path to certificate which was revoked.

certbot.display.ops._gen_ssl_lab_urls(domains)

Returns a list of urls.

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

certbot.display.ops._gen_https_names(domains)

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.ops.validated_input(validator, *args, **kwargs)

Like input, but with validation.

Parameters:

• validator (callable) – A method which will be called on the supplied input. If the method raises a errors.Error, its text will be displayed and the user will be re-prompted.
• *args (list) – Arguments to be passed to input.
• **kwargs (dict) – Arguments to be passed to input.

Returns:

as input

Return type:

tuple

certbot.display.ops.validated_directory(validator, *args, **kwargs)

Like directory_select, but with validation.

Parameters:

• validator (callable) – A method which will be called on the supplied input. If the method raises a errors.Error, its text will be displayed and the user will be re-prompted.
• *args (list) – Arguments to be passed to directory_select.
• **kwargs (dict) – Arguments to be passed to directory_select.

Returns:

as directory_select

Return type:

tuple

certbot.display.enhancements

Certbot Enhancement Display

certbot.display.enhancements.ask(enhancement)

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()

Determines whether the user would like to redirect to HTTPS.

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