# `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 at 0x9e3040>, 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 at 0x9e3040>, 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 <Logger certbot.util (WARNING)>>)

  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