# dupeGuru 4.0.4 documentation

## hscommon.util

class hscommon.util.FileOrPath(file_or_path, mode='rb')

  Does the same as `open_if_filename()`, but it can be used with a `with` statement.

  Example:

      with FileOrPath(infile):
          dostuff()

hscommon.util.RE_INVALID_XML_SUB(repl, string, count=0)

  Return the string obtained by replacing the leftmost non-overlapping occurrences of pattern in string by the replacement repl.

hscommon.util.allsame(iterable)

  Returns whether all elements of ‘iterable’ are the same.

hscommon.util.dedupe(iterable)

  Returns a list of elements in `iterable` with all dupes removed.

  The order of the elements is preserved.

hscommon.util.delete_files_with_pattern(folder_path, pattern, recursive=True)

  Delete all files (or folders) in folder_path that match the glob pattern.

hscommon.util.delete_if_empty(path: Path, files_to_delete=[])

  Deletes the directory at ‘path’ if it is empty or if it only contains files_to_delete.

hscommon.util.ensure_file(path)

  Create path as an empty file if it doesn’t exist.

hscommon.util.ensure_folder(path)

  Create path as a folder if it doesn’t exist.

hscommon.util.escape(s, to_escape, escape_with='\\')

  Returns `s` with characters in `to_escape` all prepended with `escape_with`.

hscommon.util.extract(predicate, iterable)

  Separates the wheat from the shaft (predicate defines what’s the wheat), and returns both.

hscommon.util.find_in_path(name, paths=None)

  Search for name in all directories of paths and return the absolute path of the first occurrence. If paths is None, $PATH is used.

hscommon.util.first(iterable)

  Returns the first item of `iterable`.

hscommon.util.flatten(iterables, start_with=None)

  Takes a list of lists `iterables` and returns a list containing elements of every list.

  If `start_with` is not `None`, the result will start with `start_with` items, exactly as if `start_with` would be the first item of lists.

hscommon.util.format_size(size, decimal=0, forcepower=-1, showdesc=True)

  Transform a byte count in a formatted string (KB, MB etc..).

  `size` is the number of bytes to format. `decimal` is the number digits after the dot. `forcepower` is the desired suffix. 0 is B, 1 is KB, 2 is MB etc.. if kept at -1, the suffix will be automatically chosen (so the resulting number is always below 1024). if `showdesc` is `True`, the suffix will be shown after the number. Usage example:

      >>> format_size(1234, decimal=2, showdesc=True)
      '1.21 KB'

hscommon.util.format_time(seconds, with_hours=True)

  Transforms seconds in a hh:mm:ss string.

  If `with_hours` if false, the format is mm:ss.

hscommon.util.format_time_decimal(seconds)

  Transforms seconds in a strings like ‘3.4 minutes’.

hscommon.util.get_file_ext(filename)

  Returns the lowercase extension part of filename, without the dot.

hscommon.util.iterconsume(seq, reverse=True)

  Iterate over `seq` and pops yielded objects.

  Because we use the `pop()` method, we reverse `seq` before proceeding. If you don’t need to do that, set `reverse` to `False`.

  This is useful in tight memory situation where you are looping over a sequence of objects that are going to be discarded afterwards. If you’re creating other objects during that iteration you might want to use this to avoid `MemoryError`.

hscommon.util.iterdaterange(start, end)

  Yields every day between `start` and `end`.

hscommon.util.minmax(value, min_value, max_value)

  Returns value or one of the min/max bounds if value is not between them.

hscommon.util.modified_after(first_path: Path, second_path: Path)

  Returns `True` if first_path’s mtime is higher than second_path’s mtime.

  If one of the files doesn’t exist or is `None`, it is considered “never modified”.

hscommon.util.multi_replace(s, replace_from, replace_to='')

  A function like str.replace() with multiple replacements.

  `replace_from` is a list of things you want to replace. Ex: [‘a’,’bc’,’d’] `replace_to` is a list of what you want to replace to. If `replace_to` is a list and has the same length as `replace_from`, `replace_from` items will be translated to corresponding `replace_to`. A `replace_to` list must have the same length as `replace_from` If `replace_to` is a string, all `replace_from` occurence will be replaced by that string. `replace_from` can also be a str. If it is, every char in it will be translated as if `replace_from` would be a list of chars. If `replace_to` is a str and has the same length as `replace_from`, it will be transformed into a list.

hscommon.util.nonone(value, replace_value)

  Returns `value` if `value` is not `None`. Returns `replace_value` otherwise.

hscommon.util.open_if_filename(infile, mode='rb')

  If `infile` is a string, it opens and returns it. If it’s already a file object, it simply returns it.

  This function returns `(file, should_close_flag)`. The should_close_flag is True is a file has effectively been opened (if we already pass a file object, we assume that the responsibility for closing the file has already been taken). Example usage:

      fp, shouldclose = open_if_filename(infile)
      dostuff()
      if shouldclose:
          fp.close()

hscommon.util.pluralize(number, word, decimals=0, plural_word=None)

  Returns a pluralized string with `number` in front of `word`.

  Adds a ‘s’ to s if `number` > 1. `number`: The number to go in front of s `word`: The word to go after number `decimals`: The number of digits after the dot `plural_word`: If the plural rule for word is more complex than adding a ‘s’, specify a plural

hscommon.util.rem_file_ext(filename)

  Returns the filename without extension.

hscommon.util.stripfalse(seq)

  Returns a sequence with all false elements stripped out of seq.

hscommon.util.trailiter(iterable, skipfirst=False)

  Yields (prev_element, element), starting with (None, first_element).

  If skipfirst is True, there will be no (None, item1) element and we’ll start directly with (item1, item2).

hscommon.util.tryint(value, default=0)

  Tries to convert `value` to in `int` and returns `default` if it fails.