pology.report

Package pology :: Module report |

# Module report

Report info, warning and error messages.

Functions for Pology tools to issue reports to the user at runtime. May colorize some output.

Author: Chusslove Illich (Часлав Илић) <caslav.ilic@gmx.net>

License: GPLv3

Functions
encwrite(file, text) Write unicode text to file using best encoding guess. |
report(text, showcmd=False, subsrc=None, file=sys.stdout, newline=True) Generic report. |
warning(text, showcmd=True, subsrc=None, file=sys.stdout) Generic warning. |
error(text, code=1, showcmd=True, subsrc=None, file=sys.stdout) Generic error (aborts the execution). |
(file_path, last_time, time_interval) -> new_last_time |
init_file_progress(fpaths, timeint=1.0, stream=sys.stdout, addfmt=None) Create a function to output progress bar while processing files. |
string |
list_options(optparser, short=False, both=False) Simple list of all option names found in the option parser. |
string |
format_item_list(items, incmp=False, quoted=False) Format inline item list, for insertion into text. |

Variables
| __package__ = ``'``pology``'``

Function Details

### encwrite(file, text) |
Write unicode text to file using best encoding guess. If the file has been opened with explicit encoding, that encoding is used. Otherwise a guess is made based on the environment locale. Parameters: `file` (`file`) - file to write to `text` (string or unicode) - text to write

### report(text, showcmd=False, subsrc=None, file=sys.stdout, newline=True) |
Generic report. Text is output to the file descriptor, with one newline appended by default. Parameters: `text` (string) - text to report `showcmd` (bool) - whether to show the command name `subsrc` (`None` or string) - more detailed source of the text `file` (`file`) - send output to this file descriptor `newline` (bool) - whether to append newline to output

### warning(text, showcmd=True, subsrc=None, file=sys.stdout) |
Generic warning. Parameters: `text` (string) - text to report `showcmd` (bool) - whether to show the command name `subsrc` (`None` or string) - more detailed source of the text `file` (`file`) - send output to this file descriptor

### error(text, code=1, showcmd=True, subsrc=None, file=sys.stdout) |
Generic error (aborts the execution). Exits with the given code. Parameters: `text` (string) - text to report `code` (int) - the exit code `showcmd` (bool) - whether to show the command name `file` (`file`) - send output to this file descriptor

### init_file_progress(fpaths, timeint=1.0, stream=sys.stdout, addfmt=None) |
Create a function to output progress bar while processing files. When a collection of files is about to be processed, this function can be used to construct a progress update function, which shows and updates the progress bar in the terminal. The progress update function can be called as frequently as desired during processing of a particular file, with file path as argument. For example:
       update_progress == init_file_progress(file_paths)
       for file_path in file_paths:
           for line in open(file_path).readlines():
               update_progress(file_path)
               # ...
               # Processing.
               # ...
       update_progress() # clears last progress line
Parameter `timeint` determines the frequency of update, in seconds. It should be chosen such that the progress updates themselves (formatting, writing out to shell) are only a small fraction of total processing time. The output stream for the progress bar can be specified by the `stream` parameter. Additional formatting for the progress bar may be supplied by the `addfmt` parameter. It can be one of: a function taking one string parameter (the basic progress bar) and returning a string, a delayed translation (TextTrans) with single named formatting directive `%(file)s`, or a plain string with same formatting directive. Parameters: `fpaths` (list of strings) - collection of file paths `timeint` (float) - update interval in seconds `stream` (file) - the stream to output progress to `addfmt` ((text) -> text or TextTrans or string) - additional format for the progress line Returns: (file_path, last_time, time_interval) -> new_last_time progress updating function

### list_options(optparser, short=False, both=False) |
Simple list of all option names found in the option parser. The list is composed of option names delimited by newlines. If an option is having both short and long name, the behavior is determined by parameters `short` and `both`. If neither is `True`, only the long name is added to list. If only `short` is `True`, only the short name is added to list. If `both` is `True` both names are added to the list, in the order determined by `short` -- if `True`, short name is listed first. The list is sorted by long option names where available, with short name listed before or after the long name, depending on `short` (`True` for before). Parameters: `optparser` (OptionParser) - option parser `short` (bool) - whether to prefer short names `both` (bool) - whether to show both long and short name of an option Returns: string formated list of option names

### format_item_list(items, incmp=False, quoted=False) |
Format inline item list, for insertion into text. Parameters: `items` (sequence of elements convertible to string by unicode()) - items to list `incmp` (bool) - whether some items are omitted from the list `quoted` (bool) - whether each item should be quoted Returns: string inline formatted list of items