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()¶

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.