From 80648d4710f8c78002480c1e0ab950dbb8594b37 Mon Sep 17 00:00:00 2001 From: Christian Herdtweck Date: Mon, 5 Nov 2018 11:30:40 +0100 Subject: [PATCH] Fix doc strings for text_helpers (except color stuff) Thanks to Plamen for hint in review --- src/text_helpers.py | 57 ++++++++++++++++++++++++++++++++++---------------- 1 files changed, 39 insertions(+), 18 deletions(-) diff --git a/src/text_helpers.py b/src/text_helpers.py index 89f60a7..d60f165 100644 --- a/src/text_helpers.py +++ b/src/text_helpers.py @@ -19,10 +19,25 @@ # Copyright (c) 2016-2018 Intra2net AG """ -Functions for printing colored text using ANSI escape sequences -Not sure whether to save this as text_helpers.py or a shell_helpers.py or some -other. Let's see what else could be added to any of those. +SUMMARY +------------------------------------------------------ +Functions for improving textual output. + +Copyright: 2015 Intra2net AG + + +CONTENTS +------------------------------------------------------ +This module has two parts. Part 1 includes: + +- head_and_tail: shows the first few and last few elements of an iterable that + could potentially be pretty long +- size_str: textual representation of data size + +Part2 contains functions for coloring text, a poor-man's version of other +modules like :py:mod:`colorclass` (which is now also available on Intra2net +systems) Functions might cause trouble when combined, e.g.:: @@ -31,16 +46,13 @@ Functions might cause trouble when combined, e.g.:: will show the text "and green" not in bold. May have to try using specific end-of-color or end-of-style escape sequences instead of 0 (reset-everything). -See also: python package colorclass, a more professional version of this. -Color unrelated functions: -- head_and_tail: shows the first few and last few elements of an iterable that - could potentially be pretty long -- size_str: textual representation of data size +.. seealso:: http://stackoverflow.com/questions/287871/print-in-terminal-with-colors-using-python +.. seealso:: https://en.wikipedia.org/wiki/ANSI_escape_code -References: -* http://stackoverflow.com/questions/287871/print-in-terminal-with-colors-using-python -* https://en.wikipedia.org/wiki/ANSI_escape_code + +INTERFACE +------------------------------------------------------ """ try: @@ -57,16 +69,18 @@ from sys import stdout def head_and_tail(iterable, n_head=20, n_tail=20, n_elems=None, skip_elem="...(skipping {n_skipped} elements)..."): - """ convenient way to shorten a possibly very long iterable before printing + """ + Convenient way to shorten a possibly very long iterable before printing. Will not modify short iterables, but for longer lists/tuples/... will only yield first few, then a message how many were skipped and the last few The iterable does not even have to have a `len(..)` method if argument `n_elems` is given. Only needs a `next(..)` method. However, for very long - iterables this will be faster if radnom element access is provided via [] + iterables this will be faster if random element access is provided via [] :param iterable: an iterable + :type iterable: anything that can be iterated over :param int n_head: number of starting elements to yield (optional) :param int n_tail: number of ending elements to yield (optional) :param int n_elems: number of elements in iterable; give this to avoid a @@ -75,10 +89,12 @@ def head_and_tail(iterable, n_head=20, n_tail=20, n_elems=None, once at most; None to not yield a skip replacement; if str then it will be formatted; optional, defaults to string with number of skipped elems + :type skip_elem: anything you like + :yields: `n_head+n_tail` elements from iterable plus the `skip_elem` (or + less if iterable is shorter than this). - ..seealso: :py:func:`slice`, py:func:`itertools.islice` + .. seealso:: :py:func:`slice`, :py:func:`itertools.islice` """ - if n_elems is None: n_elems = len(iterable) @@ -115,12 +131,17 @@ def head_and_tail(iterable, n_head=20, n_tail=20, n_elems=None, def size_str(byte_number, is_diff=False): - """ round byte_number to something easily human-readable like '1.5 GB' + """ + Create a human-readable text representation of a file size. - :param bool is_diff: set to True to include a '+' or '-' in output; + Rounds and shortens size to something easily human-readable like '1.5 GB'. + + :param int byte_number: Number of bytes to express as text + :param bool is_diff: Set to True to include a '+' or '-' in output; default: False + :returns: textual representation of data + :rtype: str """ - # constants units = '', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y' factor = 1024 -- 1.7.1