# `letsencrypt.display`

Let’s Encrypt display utilities.

## `letsencrypt.display.util`

Let’s Encrypt display.

`letsencrypt.display.util.``OK` = 'ok'

  Display exit code indicating user acceptance.

`letsencrypt.display.util.``CANCEL` = 'cancel'

  Display exit code for a user canceling the display.

`letsencrypt.display.util.``HELP` = 'help'

  Display exit code when for when the user requests more help.

`letsencrypt.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

class `letsencrypt.display.util.``NcursesDisplay`(width=72, height=20)

  Bases: `object`

  Ncurses-based display.

  `notification`(message, height=10, pause=False)

    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)

    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` - int display exit code `int` - index of the selected item
    Return type: | tuple

  `input`(message, **unused_kwargs)

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

  `yesno`(message, yes_label='Yes', no_label='No', **unused_kwargs)

    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)

    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` - int display exit code `list_tags` - list of str tags selected by the user

class `letsencrypt.display.util.``FileDisplay`(outfile)

  Bases: `object`

  File-based display.

  `notification`(message, height=10, pause=True)

    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)

    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)

    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)

    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)

    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

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

class `letsencrypt.display.util.``NoninteractiveDisplay`(outfile)

  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, height=10, pause=False)

    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)

    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)

    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)

    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)

    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

`letsencrypt.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

`letsencrypt.display.util.``_parens_around_char`(label)

  Place parens around first character of label.

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

## `letsencrypt.display.ops`

Contains UI methods for LE user operations.

`letsencrypt.display.ops.``choose_plugin`(prepared, question)

  Allow the user to choose their plugin.

  Parameters:

  - prepared (list) – List of `PluginEntryPoint`.
  - question (str) – Question to be presented to the user.

  Returns: | Plugin entry point chosen by the user.
  Return type: | `PluginEntryPoint`

`letsencrypt.display.ops.``pick_plugin`(config, default, plugins, question, ifaces)

  Pick plugin.

  Parameters:

  - letsencrypt.interfaces.IConfig – Configuration
  - default (str) – Plugin name supplied by user or `None`.
  - plugins (letsencrypt.plugins.disco.PluginsRegistry) – All plugins registered as entry points.
  - question (str) – Question to be presented to the user in case multiple candidates are found.
  - ifaces (list) – Interfaces that plugins must provide.

  Returns: | Initialized plugin.
  Return type: | IPlugin

`letsencrypt.display.ops.``pick_authenticator`(config, default, plugins, question="How would you like to authenticate with the Let's Encrypt CA?")

  Pick authentication plugin.

`letsencrypt.display.ops.``pick_installer`(config, default, plugins, question='How would you like to install certificates?')

  Pick installer plugin.

`letsencrypt.display.ops.``pick_configurator`(config, default, plugins, question='How would you like to authenticate and install certificates?')

  Pick configurator plugin.

`letsencrypt.display.ops.``get_email`(more=False, invalid=False)

  Prompt for valid email address.

  Parameters:

  - more (bool) – explain why the email is strongly advisable, but how to skip it
  - invalid (bool) – true if the user just typed something, but it wasn’t a valid-looking email

  Returns: | Email or `None` if cancelled by user.
  Return type: | str

`letsencrypt.display.ops.``choose_account`(accounts)

  Choose an account.

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

`letsencrypt.display.ops.``choose_names`(installer)

  Display screen to select domains to validate.

  Parameters: | installer (`letsencrypt.interfaces.IInstaller`) – An installer object
  Returns: | List of selected names
  Return type: | `list` of `str`

`letsencrypt.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

`letsencrypt.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

`letsencrypt.display.ops.``_choose_names_manually`()

  Manually input names for those without an installer.

`letsencrypt.display.ops.``success_installation`(domains)

  Display a box confirming the installation of HTTPS.

  Todo

  This should be centered on the screen

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

`letsencrypt.display.ops.``success_renewal`(domains, action)

  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”

`letsencrypt.display.ops.``_gen_ssl_lab_urls`(domains)

  Returns a list of urls.

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

`letsencrypt.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’

## `letsencrypt.display.enhancements`

Let’s Encrypt Enhancement Display

`letsencrypt.display.enhancements.``ask`(enhancement)

  Display the enhancement to the user.

  Parameters: | enhancement (str) – One of the `letsencrypt.CONFIG.ENHANCEMENTS` enhancements
  Returns: | True if feature is desired, False otherwise
  Return type: | bool
  Raises: | .errors.Error – if the enhancement provided is not supported

`letsencrypt.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