"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
