"certbot.cli"
*************

Certbot command line argument & config processing.

certbot.cli.report_config_interaction(modified, modifiers)

   Registers config option interaction to be checked by set_by_cli.

   This function can be called by during the __init__ or
   add_parser_arguments methods of plugins to register interactions
   between config options.

   Parameters:
      * **modified** (*iterable** or **str** (**string_types**)*) –
        config options that can be modified by modifiers

      * **modifiers** (*iterable** or **str** (**string_types**)*) –
        config options that modify modified

certbot.cli.possible_deprecation_warning(config)

   A deprecation warning for users with the old, not-self-upgrading
   letsencrypt-auto.

class certbot.cli._Default

   Bases: "object"

   A class to use as a default to detect if a value is set by a user

certbot.cli.set_by_cli(var)

   Return True if a particular config variable has been set by the
   user (CLI or config file) including if the user explicitly set it
   to the default.  Returns False if the variable was assigned a
   default value.

certbot.cli.has_default_value(option, value)

   Does option have the default value?

   If the default value of option is not known, False is returned.

   Parameters:
      * **option** (*str*) – configuration variable being considered

      * **value** – value of the configuration variable named option

   Returns:
      True if option has the default value, otherwise, False

   Return type:
      bool

certbot.cli.option_was_set(option, value)

   Was option set by the user or does it differ from the default?

   Parameters:
      * **option** (*str*) – configuration variable being considered

      * **value** – value of the configuration variable named option

   Returns:
      True if the option was set, otherwise, False

   Return type:
      bool

certbot.cli.argparse_type(variable)

   Return our argparse type function for a config variable (default:
   str)

certbot.cli.read_file(filename, mode='rb')

   Returns the given file’s contents.

   Parameters:
      * **filename** (*str*) – path to file

      * **mode** (*str*) – open mode (see "open")

   Returns:
      absolute path of filename and its contents

   Return type:
      tuple

   Raises:
      **argparse.ArgumentTypeError** – File does not exist or is not
      readable.

certbot.cli.flag_default(name)

   Default value for CLI flag.

certbot.cli.config_help(name, hidden=False)

   Extract the help message for an "IConfig" attribute.

class certbot.cli.HelpfulArgumentGroup(helpful_arg_parser, topic)

   Bases: "object"

   Emulates an argparse group for use with HelpfulArgumentParser.

   This class is used in the add_group method of
   HelpfulArgumentParser. Command line arguments can be added to the
   group, but help suppression and default detection is applied by
   HelpfulArgumentParser when necessary.

   add_argument(*args, **kwargs)

      Add a new command line argument to the argument group.

class certbot.cli.CustomHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

   Bases: "argparse.HelpFormatter"

   This is a clone of ArgumentDefaultsHelpFormatter, with bugfixes.

   In particular we fix https://bugs.python.org/issue28742

class certbot.cli.HelpfulArgumentParser(args, plugins, detect_defaults=False)

   Bases: "object"

   Argparse Wrapper.

   This class wraps argparse, adding the ability to make –help less
   verbose, and request help on specific subcategories at a time, eg
   ‘certbot –help security’ for security options.

   _usage_string(plugins, help_arg)

      Make usage strings late so that plugins can be initialised late

      Parameters:
         * **plugins** – all discovered plugins

         * **help_arg** – False for none; True for –help; “TOPIC”
           for –help TOPIC

      Return type:
         str

      Returns:
         a short usage string for the top of –help TOPIC)

   remove_config_file_domains_for_renewal(parsed_args)

      Make “certbot renew” safe if domains are set in cli.ini.

   parse_args()

      Parses command line arguments and returns the result.

      Returns:
         parsed command line arguments

      Return type:
         argparse.Namespace

   set_test_server(parsed_args)

      We have –staging/–dry-run; perform sanity check and set
      config.server

   handle_csr(parsed_args)

      Process a –csr flag.

   determine_verb()

      Determines the verb/subcommand provided by the user.

      This function works around some of the limitations of argparse.

   prescan_for_flag(flag, possible_arguments)

      Checks cli input for flags.

      Check for a flag, which accepts a fixed set of possible
      arguments, in the command line; we will use this information to
      configure argparse’s help correctly.  Return the flag’s
      argument, if it has one that matches the sequence
      @possible_arguments; otherwise return whether the flag is
      present.

   add(topics, *args, **kwargs)

      Add a new command line argument.

      Parameters:
         * **topics** – str or [str] help topic(s) this should be
           listed under, or None for “always documented”. The first
           entry determines where the flag lives in the “–help all”
           output (None -> “optional arguments”).

         * ***args** (*list*) –

           the names of this argument flag

         * ****kwargs** (*dict*) –

           various argparse settings for this argument

   modify_kwargs_for_default_detection(**kwargs)

      Modify an arg so we can check if it was set by the user.

      Changes the parameters given to argparse when adding an argument
      so we can properly detect if the value was set by the user.

      Parameters:
         **kwargs** (*dict*) – various argparse settings for this
         argument

      Returns:
         a modified versions of kwargs

      Return type:
         dict

   add_deprecated_argument(argument_name, num_args)

      Adds a deprecated argument with the name argument_name.

      Deprecated arguments are not shown in the help. If they are used
      on the command line, a warning is shown stating that the
      argument is deprecated and no other action is taken.

      Parameters:
         * **argument_name** (*str*) – Name of deprecated argument.

         * **nargs** (*int*) – Number of arguments the option takes.

   add_group(topic, verbs=(), **kwargs)

      Create a new argument group.

      This method must be called once for every topic, however, calls
      to this function are left next to the argument definitions for
      clarity.

      Parameters:
         * **topic** (*str*) – Name of the new argument group.

         * **verbs** (*str*) – List of subcommands that should be
           documented as part of this help group / topic

      Returns:
         The new argument group.

      Return type:
         "HelpfulArgumentGroup"

   add_plugin_args(plugins)

      Let each of the plugins add its own command line arguments,
      which may or may not be displayed as help topics.

   determine_help_topics(chosen_topic)

      The user may have requested help on a topic, return a dict of
      which topics to display. @chosen_topic has prescan_for_flag’s
      return type

      Returns:
         dict

certbot.cli.prepare_and_parse_args(plugins, args, detect_defaults=False)

   Returns parsed command line arguments.

   Parameters:
      * **plugins** (*PluginsRegistry*) – available plugins

      * **args** (*list*) – command line arguments with the program
        name removed

   Returns:
      parsed command line arguments

   Return type:
      argparse.Namespace

class certbot.cli.CaseInsensitiveList

   Bases: "list"

   A list that will ignore case when searching.

   This class is passed to the "choices" argument of
   "argparse.add_arguments" through the "helpful" wrapper. It is
   necessary due to special handling of command line arguments by
   "set_by_cli" in which the "type_func" is not applied.

class certbot.cli._EncodeReasonAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

   Bases: "argparse.Action"

   Action class for parsing revocation reason.

class certbot.cli._DomainsAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

   Bases: "argparse.Action"

   Action class for parsing domains.

certbot.cli.add_domains(args_or_config, domains)

   Registers new domains to be used during the current client run.

   Domains are not added to the list of requested domains if they have
   already been registered.

   Parameters:
      * **args_or_config** (*argparse.Namespace** or
        **configuration.NamespaceConfig*) – parsed command line
        arguments

      * **domain** (*str*) – one or more comma separated domains

   Returns:
      domains after they have been normalized and validated

   Return type:
      "list" of "str"

class certbot.cli._PrefChallAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

   Bases: "argparse.Action"

   Action class for parsing preferred challenges.

certbot.cli.parse_preferred_challenges(pref_challs)

   Translate and validate preferred challenges.

   Parameters:
      **pref_challs** ("list" of "str") – list of preferred challenge
      types

   Returns:
      validated list of preferred challenge types

   Return type:
      "list" of "str"

   Raises:
      **errors.Error** – if pref_challs is invalid

class certbot.cli._DeployHookAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

   Bases: "argparse.Action"

   Action class for parsing deploy hooks.

class certbot.cli._RenewHookAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

   Bases: "argparse.Action"

   Action class for parsing renew hooks.

certbot.cli.nonnegative_int(value)

   Converts value to an int and checks that it is not negative.

   This function should used as the type parameter for argparse
   arguments.

   Parameters:
      **value** (*str*) – value provided on the command line

   Returns:
      integer representation of value

   Return type:
      int

   Raises:
      **argparse.ArgumentTypeError** – if value isn’t a non-negative
      integer
