refactorings in utils.py, now autodocumented