commit 42f02bf3371f0b45f04ed47001f05a2d4effb7f7 Author: Damian Johnson atagar@torproject.org Date: Wed Sep 17 10:10:34 2014 -0700
Adding join() function to the str_tools module
Function to greatly simplify 'gimme this string joined just up to a given point'. Basic test coverage via its doctests. --- docs/change_log.rst | 1 + stem/util/str_tools.py | 39 +++++++++++++++++++++++++++++++++++++++ test/unit/doctest.py | 1 + 3 files changed, 41 insertions(+)
diff --git a/docs/change_log.rst b/docs/change_log.rst index ff5b60d..c5867e4 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -58,6 +58,7 @@ The following are only available within Stem's `git repository * Added support for directories to :func:`stem.util.conf.Config.load`. * Changed :func:`stem.util.conf.uses_settings` to only provide a 'config' keyword arument if the decorated function would accept it. * Added :func:`stem.util.str_tools.crop` + * Added :func:`stem.util.str_tools.join` * Added :func:`stem.util.proc.file_descriptors_used` * Dropped the 'get_*' prefix from most function names. Old names will still work, but are a deprecated alias.
diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py index 16681d5..d669753 100644 --- a/stem/util/str_tools.py +++ b/stem/util/str_tools.py @@ -13,6 +13,7 @@ Toolkit for various string activity. ::
crop - shortens string to a given length + join - joins a series of strings up to a given length
size_label - human readable label for a number of bytes time_label - human readable label for a number of seconds @@ -257,6 +258,44 @@ def crop(msg, size, min_word_length = 4, min_crop = 0, ending = Ending.ELLIPSE, return (return_msg, remainder) if get_remainder else return_msg
+def join(entries, joiner = ' ', size = None): + """ + Joins a series of strings similar to str.join(), but only up to a given size. + This returns an empty string if none of the entries will fit. For example... + + >>> join(['This', 'is', 'a', 'looooong', 'message'], size = 18) + 'This is a looooong' + + >>> join(['This', 'is', 'a', 'looooong', 'message'], size = 17) + 'This is a' + + >>> join(['This', 'is', 'a', 'looooong', 'message'], size = 2) + '' + + :param list entries: strings to be joined + :param str joiner: strings to join the entries with + :param int size: maximum length the result can be, there's no length + limitation if **None** + + :returns: **str** of the joined entries up to the given length + """ + + if size is None: + return joiner.join(entries) + + result = '' + + for entry in entries: + new_result = joiner.join((result, entry)) if result else entry + + if len(new_result) > size: + break + else: + result = new_result + + return result + + def size_label(byte_count, decimal = 0, is_long = False, is_bytes = True): """ Converts a number of bytes into a human readable label in its most diff --git a/test/unit/doctest.py b/test/unit/doctest.py index e3e53d8..090b273 100644 --- a/test/unit/doctest.py +++ b/test/unit/doctest.py @@ -60,6 +60,7 @@ class TestDocumentation(unittest.TestCase): args['globs'] = { '_to_camel_case': stem.util.str_tools._to_camel_case, 'crop': stem.util.str_tools.crop, + 'join': stem.util.str_tools.join, 'size_label': stem.util.str_tools.size_label, 'time_label': stem.util.str_tools.time_label, 'time_labels': stem.util.str_tools.time_labels,