# dupeGuru 4.3.1 documentation

## hscommon.util

class hscommon.util.FileOrPath(file_or_path: Path | str, mode: str = 'rb')

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

  Example:

      with FileOrPath(infile):
          dostuff()

hscommon.util.allsame(iterable: Iterable[Any]) → bool

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

hscommon.util.dedupe(iterable: Iterable[Any]) → List[Any]

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

  The order of the elements is preserved.

hscommon.util.delete_if_empty(path: Path, files_to_delete: List[str] = []) → bool

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

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

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

hscommon.util.extract(predicate: Callable[[Any], bool], iterable: Iterable[Any]) → Tuple[List[Any], List[Any]]

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

hscommon.util.first(iterable: Iterable[Any])

  Returns the first item of `iterable`.

hscommon.util.flatten(iterables: Iterable[Iterable], start_with: Iterable[Any] = None) → List[Any]

  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: int, decimal: int = 0, forcepower: int = -1, showdesc: bool = True) → str

  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: int, with_hours: bool = True) → str

  Transforms seconds in a hh:mm:ss string.

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

hscommon.util.format_time_decimal(seconds: int) → str

  Transforms seconds in a strings like ‘3.4 minutes’.

hscommon.util.get_file_ext(filename: str) → str

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

hscommon.util.iterconsume(seq: List[Any], reverse: bool = True) → Generator[Any, None, None]

  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.multi_replace(s: str, replace_from: str | List[str], replace_to: str | List[str] = '') → str

  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: Any, replace_value: Any) → Any

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

hscommon.util.open_if_filename(infile: Path | str | IO, mode: str = 'rb') → Tuple[IO, bool]

  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: str, decimals: int = 0, plural_word: str | None = None) → str

  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: str) → str

  Returns the filename without extension.

hscommon.util.tryint(value: Any, default: int = 0) → int

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