# `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. (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.``_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=None, cancel_label=None, help_label=None, 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=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 – 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_values`(values, question=None)

  Display screen to let user pick one or multiple values from the provided list.

  Parameters: | values (list) – Values to select from
  Returns: | List of selected values
  Return type: | list

`certbot.display.ops.``choose_names`(installer, question=None)

  Display screen to select domains to validate.

  Parameters:

  - installer (`certbot.interfaces.IInstaller`) – An installer object
  - question (str) – Overriding dialog question to ask the user if asked to choose from domain names.

  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, override_question=None)

  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