"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

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