"certbot.util"
**************

Utilities for all Certbot.

class certbot.util.Key(file, pem)

   Bases: "tuple"

   _asdict()

      Return a new OrderedDict which maps field names to their values

   classmethod _make(iterable, new=<built-in method __new__ of type object>, len=<built-in function len>)

      Make a new Key object from a sequence or iterable

   _replace(**kwds)

      Return a new Key object replacing specified fields with new
      values

   file

      Alias for field number 0

   pem

      Alias for field number 1

class certbot.util.CSR(file, data, form)

   Bases: "tuple"

   _asdict()

      Return a new OrderedDict which maps field names to their values

   classmethod _make(iterable, new=<built-in method __new__ of type object>, len=<built-in function len>)

      Make a new CSR object from a sequence or iterable

   _replace(**kwds)

      Return a new CSR object replacing specified fields with new
      values

   data

      Alias for field number 1

   file

      Alias for field number 0

   form

      Alias for field number 2

certbot.util.run_script(params, log=<bound method Logger.error of <logging.Logger object>>)

   Run the script with the given params.

   Parameters:
      * **params** (*list*) – List of parameters to pass to Popen

      * **log** (*logging.Logger*) – Logger to use for errors

certbot.util.is_exe(path)

   Is path an executable file?

   Parameters:
      **path** (*str*) – path to test

   Returns:
      True iff path is an executable file

   Return type:
      bool

certbot.util.exe_exists(exe)

   Determine whether path/name refers to an executable.

   Parameters:
      **exe** (*str*) – Executable path or name

   Returns:
      If exe is a valid executable

   Return type:
      bool

certbot.util.lock_dir_until_exit(dir_path)

   Lock the directory at dir_path until program exit.

   Parameters:
      **dir_path** (*str*) – path to directory

   Raises:
      **errors.LockError** – if the lock is held by another process

certbot.util.set_up_core_dir(directory, mode, uid, strict)

   Ensure directory exists with proper permissions and is locked.

   Parameters:
      * **directory** (*str*) – Path to a directory.

      * **mode** (*int*) – Directory mode.

      * **uid** (*int*) – Directory owner.

      * **strict** (*bool*) – require directory to be owned by
        current user

   Raises:
      * **errors.LockError** – if the directory cannot be locked

      * **errors.Error** – if the directory cannot be made or
        verified

certbot.util.make_or_verify_dir(directory, mode=493, uid=0, strict=False)

   Make sure directory exists with proper permissions.

   Parameters:
      * **directory** (*str*) – Path to a directory.

      * **mode** (*int*) – Directory mode.

      * **uid** (*int*) – Directory owner.

      * **strict** (*bool*) – require directory to be owned by
        current user

   Raises:
      * **errors.Error** – if a directory already exists, but has
        wrong permissions or owner

      * **OSError** – if invalid or inaccessible file names and
        paths, or other arguments that have the correct type, but are
        not accepted by the operating system.

certbot.util.check_permissions(filepath, mode, uid=0)

   Check file or directory permissions.

   Parameters:
      * **filepath** (*str*) – Path to the tested file (or
        directory).

      * **mode** (*int*) – Expected file mode.

      * **uid** (*int*) – Expected file owner.

   Returns:
      True if "mode" and "uid" match, False otherwise.

   Return type:
      bool

certbot.util.safe_open(path, mode='w', chmod=None, buffering=None)

   Safely open a file.

   Parameters:
      * **path** (*str*) – Path to a file.

      * **mode** (*str*) – Same os "mode" for "open".

      * **chmod** (*int*) – Same as "mode" for "os.open", uses
        Python defaults if "None".

      * **buffering** (*int*) – Same as "bufsize" for "os.fdopen",
        uses Python defaults if "None".

certbot.util.unique_file(path, chmod=511, mode='w')

   Safely finds a unique file.

   Parameters:
      * **path** (*str*) – path/filename.ext

      * **chmod** (*int*) – File mode

      * **mode** (*str*) – Open mode

   Returns:
      tuple of file object and file name

certbot.util.unique_lineage_name(path, filename, chmod=420, mode='w')

   Safely finds a unique file using lineage convention.

   Parameters:
      * **path** (*str*) – directory path

      * **filename** (*str*) – proposed filename

      * **chmod** (*int*) – file mode

      * **mode** (*str*) – open mode

   Returns:
      tuple of file object and file name (which may be modified from
      the requested one by appending digits to ensure uniqueness)

   Raises:
      **OSError** – if writing files fails for an unanticipated
      reason, such as a full disk or a lack of permission to write to
      specified location.

certbot.util.safely_remove(path)

   Remove a file that may not exist.

certbot.util.get_filtered_names(all_names)

   Removes names that aren’t considered valid by Let’s Encrypt.

   Parameters:
      **all_names** (*set*) – all names found in the configuration

   Returns:
      all found names that are considered valid by LE

   Return type:
      set

certbot.util.get_os_info(filepath='/etc/os-release')

   Get OS name and version

   Parameters:
      **filepath** (*str*) – File path of os-release file

   Returns:
      (os_name, os_version)

   Return type:
      "tuple" of "str"

certbot.util.get_os_info_ua(filepath='/etc/os-release')

   Get OS name and version string for User Agent

   Parameters:
      **filepath** (*str*) – File path of os-release file

   Returns:
      os_ua

   Return type:
      "str"

certbot.util.get_systemd_os_info(filepath='/etc/os-release')

   Parse systemd /etc/os-release for distribution information

   Parameters:
      **filepath** (*str*) – File path of os-release file

   Returns:
      (os_name, os_version)

   Return type:
      "tuple" of "str"

certbot.util.get_systemd_os_like(filepath='/etc/os-release')

   Get a list of strings that indicate the distribution likeness to
   other distributions.

   Parameters:
      **filepath** (*str*) – File path of os-release file

   Returns:
      List of distribution acronyms

   Return type:
      "list" of "str"

certbot.util.get_var_from_file(varname, filepath='/etc/os-release')

   Get single value from systemd /etc/os-release

   Parameters:
      * **varname** (*str*) – Name of variable to fetch

      * **filepath** (*str*) – File path of os-release file

   Returns:
      requested value

   Return type:
      "str"

certbot.util._normalize_string(orig)

   Helper function for get_var_from_file() to remove quotes and
   whitespaces

certbot.util.get_python_os_info()

   Get Operating System type/distribution and major version using
   python platform module

   Returns:
      (os_name, os_version)

   Return type:
      "tuple" of "str"

certbot.util.safe_email(email)

   Scrub email address before using it.

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

   Bases: "argparse.Action"

   Action to log a warning when an argument is used.

certbot.util.add_deprecated_argument(add_argument, argument_name, nargs)

   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:
      * **add_argument** (*callable*) – Function that adds arguments
        to an argument parser/group.

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

      * **nargs** – Value for nargs when adding the argument to
        argparse.

certbot.util.enforce_le_validity(domain)

   Checks that Let’s Encrypt will consider domain to be valid.

   Parameters:
      **domain** ("str" or "unicode") – FQDN to check

   Returns:
      The domain cast to "str", with ASCII-only contents

   Return type:
      str

   Raises:
      **ConfigurationError** – for invalid domains and cases where
      Let’s Encrypt currently will not issue certificates

certbot.util.enforce_domain_sanity(domain)

   Method which validates domain value and errors out if the
   requirements are not met.

   Parameters:
      **domain** ("str" or "unicode") – Domain to check

   Raises:
      **ConfigurationError** – for invalid domains and cases where
      Let’s Encrypt currently will not issue certificates

   Returns:
      The domain cast to "str", with ASCII-only contents

   Return type:
      str

certbot.util.is_wildcard_domain(domain)

   “Is domain a wildcard domain?

   Parameters:
      **domain** ("bytes" or "str" or "unicode") – domain to check

   Returns:
      True if domain is a wildcard, otherwise, False

   Return type:
      bool

certbot.util.get_strict_version(normalized)

   Converts a normalized version to a strict version.

   Parameters:
      **normalized** (*str*) – normalized version string

   Returns:
      An equivalent strict version

   Return type:
      distutils.version.StrictVersion

certbot.util.is_staging(srv)

   Determine whether a given ACME server is a known test / staging
   server.

   Parameters:
      **srv** (*str*) – the URI for the ACME server

   Returns:
      True iff srv is a known test / staging server

   Rtype bool:
certbot.util.atexit_register(func, *args, **kwargs)

   Sets func to be called before the program exits.

   Special care is taken to ensure func is only called when the
   process that first imports this module exits rather than any child
   processes.

   Parameters:
      **func** (*function*) – function to be called in case of an
      error
