"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(_self, **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(_self, **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.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.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_systemd_os_release_var(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_systemd_os_release_var() 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.

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