
"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._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 certbot.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

   directory_select(message, **unused_kwargs)

      Display a directory selection screen.

      Parameters:
         **message** (*str*) -- prompt to give the user

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

class certbot.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

   directory_select(message, **unused_kwargs)

      Display a directory selection screen.

      Parameters:
         **message** (*str*) -- prompt to give the user

      Returns:
         tuple of the form ("code", "string") where "code" - int
         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

class certbot.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

   directory_select(message, default=None, cli_flag=None)

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

   Manually input names for those without an installer.

certbot.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

certbot.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"

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