# dupeGuru 4.1.0 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: hscommon.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: hscommon.path.Path, second_path: hscommon.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.