commit 7fc393595e9ee2e13283886df609402e9ed9bbfa Author: Damian Johnson atagar@torproject.org Date: Mon Sep 1 20:33:30 2014 -0700

Dropping get_* prefix from string util functions --- docs/tutorials/mirror_mirror_on_the_wall.rst | 2 +- docs/tutorials/tortoise_and_the_hare.rst | 4 +- stem/util/str_tools.py | 48 +++++++++------ test/unit/doctest.py | 8 +-- test/unit/tutorial.py | 2 +- test/unit/util/str_tools.py | 82 +++++++++++++------------- 6 files changed, 79 insertions(+), 67 deletions(-)

diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst index 0db54c3..8fc196b 100644 --- a/docs/tutorials/mirror_mirror_on_the_wall.rst +++ b/docs/tutorials/mirror_mirror_on_the_wall.rst @@ -186,7 +186,7 @@ could use any of the methods above, but for this example we'll use

for bw_value in sorted(bw_to_relay.keys(), reverse = True): for nickname in bw_to_relay[bw_value]: - print "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2)) + print "%i. %s (%s/s)" % (count, nickname, str_tools.size_label(bw_value, 2)) count += 1

if count > 15: diff --git a/docs/tutorials/tortoise_and_the_hare.rst b/docs/tutorials/tortoise_and_the_hare.rst index a458e0d..d3f759e 100644 --- a/docs/tutorials/tortoise_and_the_hare.rst +++ b/docs/tutorials/tortoise_and_the_hare.rst @@ -107,10 +107,10 @@ uploaded.

# show the latest values at the top

- label = "Downloaded (%s/s):" % str_tools.get_size_label(download_rates[0], 1) + label = "Downloaded (%s/s):" % str_tools.size_label(download_rates[0], 1) window.addstr(0, 1, label, DOWNLOAD_COLOR, curses.A_BOLD)

- label = "Uploaded (%s/s):" % str_tools.get_size_label(upload_rates[0], 1) + label = "Uploaded (%s/s):" % str_tools.size_label(upload_rates[0], 1) window.addstr(0, GRAPH_WIDTH + 7, label, UPLOAD_COLOR, curses.A_BOLD)

# draw the graph bounds in KB diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py index e166a4c..4bba8e3 100644 --- a/stem/util/str_tools.py +++ b/stem/util/str_tools.py @@ -4,16 +4,19 @@ """ Toolkit for various string activity.

+**Note:** Many functions were previously named with a get_* prefix. Those names +are now aliases, and will be dropped in Stem version 2.0.0. + **Module Overview:**

::

crop - shortens string to a given length

- get_size_label - human readable label for a number of bytes - get_time_label - human readable label for a number of seconds - get_time_labels - human readable labels for each time unit - get_short_time_label - condensed time label output + size_label - human readable label for a number of bytes + time_label - human readable label for a number of seconds + time_labels - human readable labels for each time unit + short_time_label - condensed time label output parse_short_time_label - seconds represented by a short time label """

@@ -251,7 +254,7 @@ 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 get_size_label(byte_count, decimal = 0, is_long = False, is_bytes = True): +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 significant units. For instance, 7500 bytes would return "7 KB". If the @@ -261,13 +264,13 @@ def get_size_label(byte_count, decimal = 0, is_long = False, is_bytes = True):

::

- >>> get_size_label(2000000) + >>> size_label(2000000) '1 MB'

- >>> get_size_label(1050, 2) + >>> size_label(1050, 2) '1.02 KB'

- >>> get_size_label(1050, 3, True) + >>> size_label(1050, 3, True) '1.025 Kilobytes'

:param int byte_count: number of bytes to be converted @@ -284,7 +287,7 @@ def get_size_label(byte_count, decimal = 0, is_long = False, is_bytes = True): return _get_label(SIZE_UNITS_BITS, byte_count, decimal, is_long)

-def get_time_label(seconds, decimal = 0, is_long = False): +def time_label(seconds, decimal = 0, is_long = False): """ Converts seconds into a time label truncated to its most significant units. For instance, 7500 seconds would return "2h". Units go up through days. @@ -296,13 +299,13 @@ def get_time_label(seconds, decimal = 0, is_long = False):

::

- >>> get_time_label(10000) + >>> time_label(10000) '2h'

- >>> get_time_label(61, 1, True) + >>> time_label(61, 1, True) '1.0 minute'

- >>> get_time_label(61, 2, True) + >>> time_label(61, 2, True) '1.01 minutes'

:param int seconds: number of seconds to be converted @@ -315,7 +318,7 @@ def get_time_label(seconds, decimal = 0, is_long = False): return _get_label(TIME_UNITS, seconds, decimal, is_long)

-def get_time_labels(seconds, is_long = False): +def time_labels(seconds, is_long = False): """ Provides a list of label conversions for each time unit, starting with its most significant units on down. Any counts that evaluate to zero are omitted. @@ -323,10 +326,10 @@ def get_time_labels(seconds, is_long = False):

::

- >>> get_time_labels(400) + >>> time_labels(400) ['6m', '40s']

- >>> get_time_labels(3640, True) + >>> time_labels(3640, True) ['1 hour', '40 seconds']

:param int seconds: number of seconds to be converted @@ -345,17 +348,17 @@ def get_time_labels(seconds, is_long = False): return time_labels

-def get_short_time_label(seconds): +def short_time_label(seconds): """ Provides a time in the following format: [[dd-]hh:]mm:ss

::

- >>> get_short_time_label(111) + >>> short_time_label(111) '01:51'

- >>> get_short_time_label(544100) + >>> short_time_label(544100) '6-07:08:20'

:param int seconds: number of seconds to be converted @@ -505,3 +508,12 @@ def _get_label(units, count, decimal, is_long): return count_label + long_label + ('s' if is_plural else '') else: return count_label + short_label + +# TODO: drop with stem 2.x +# We renamed our methods to drop a redundant 'get_*' prefix, so alias the old +# names for backward compatability. + +get_size_label = size_label +get_time_label = time_label +get_time_labels = time_labels +get_short_time_label = short_time_label diff --git a/test/unit/doctest.py b/test/unit/doctest.py index 1c7c415..e3e53d8 100644 --- a/test/unit/doctest.py +++ b/test/unit/doctest.py @@ -60,10 +60,10 @@ class TestDocumentation(unittest.TestCase): args['globs'] = { '_to_camel_case': stem.util.str_tools._to_camel_case, 'crop': stem.util.str_tools.crop, - 'get_size_label': stem.util.str_tools.get_size_label, - 'get_time_label': stem.util.str_tools.get_time_label, - 'get_time_labels': stem.util.str_tools.get_time_labels, - 'get_short_time_label': stem.util.str_tools.get_short_time_label, + 'size_label': stem.util.str_tools.size_label, + 'time_label': stem.util.str_tools.time_label, + 'time_labels': stem.util.str_tools.time_labels, + 'short_time_label': stem.util.str_tools.short_time_label, 'parse_short_time_label': stem.util.str_tools.parse_short_time_label, }

diff --git a/test/unit/tutorial.py b/test/unit/tutorial.py index 1c853c0..1ee6396 100644 --- a/test/unit/tutorial.py +++ b/test/unit/tutorial.py @@ -151,7 +151,7 @@ class TestTutorial(unittest.TestCase):

for bw_value in sorted(bw_to_relay.keys(), reverse = True): for nickname in bw_to_relay[bw_value]: - print '%i. %s (%s/s)' % (count, nickname, str_tools.get_size_label(bw_value, 2)) + print '%i. %s (%s/s)' % (count, nickname, str_tools.size_label(bw_value, 2)) count += 1

if count > 15: diff --git a/test/unit/util/str_tools.py b/test/unit/util/str_tools.py index 7abdedf..f874be6 100644 --- a/test/unit/util/str_tools.py +++ b/test/unit/util/str_tools.py @@ -31,76 +31,76 @@ class TestStrTools(unittest.TestCase): self.assertEquals('This is a...', str_tools.crop('This is a looooong message', 12)) self.assertEquals('', str_tools.crop('This is a looooong message', 3))

- def test_get_size_label(self): + def test_size_label(self): """ - Checks the get_size_label() function. + Checks the size_label() function. """

# test the pydoc examples - self.assertEquals('1 MB', str_tools.get_size_label(2000000)) - self.assertEquals('1.02 KB', str_tools.get_size_label(1050, 2)) - self.assertEquals('1.025 Kilobytes', str_tools.get_size_label(1050, 3, True)) + self.assertEquals('1 MB', str_tools.size_label(2000000)) + self.assertEquals('1.02 KB', str_tools.size_label(1050, 2)) + self.assertEquals('1.025 Kilobytes', str_tools.size_label(1050, 3, True))

- self.assertEquals('0 B', str_tools.get_size_label(0)) - self.assertEquals('0 Bytes', str_tools.get_size_label(0, is_long = True)) - self.assertEquals('0.00 B', str_tools.get_size_label(0, 2)) - self.assertEquals('-10 B', str_tools.get_size_label(-10)) - self.assertEquals('80 b', str_tools.get_size_label(10, is_bytes = False)) - self.assertEquals('-1 MB', str_tools.get_size_label(-2000000)) + self.assertEquals('0 B', str_tools.size_label(0)) + self.assertEquals('0 Bytes', str_tools.size_label(0, is_long = True)) + self.assertEquals('0.00 B', str_tools.size_label(0, 2)) + self.assertEquals('-10 B', str_tools.size_label(-10)) + self.assertEquals('80 b', str_tools.size_label(10, is_bytes = False)) + self.assertEquals('-1 MB', str_tools.size_label(-2000000))

# checking that we round down - self.assertEquals('23.43 Kb', str_tools.get_size_label(3000, 2, is_bytes = False)) + self.assertEquals('23.43 Kb', str_tools.size_label(3000, 2, is_bytes = False))

- self.assertRaises(TypeError, str_tools.get_size_label, None) - self.assertRaises(TypeError, str_tools.get_size_label, 'hello world') + self.assertRaises(TypeError, str_tools.size_label, None) + self.assertRaises(TypeError, str_tools.size_label, 'hello world')

- def test_get_time_label(self): + def test_time_label(self): """ - Checks the get_time_label() function. + Checks the time_label() function. """

# test the pydoc examples - self.assertEquals('2h', str_tools.get_time_label(10000)) - self.assertEquals('1.0 minute', str_tools.get_time_label(61, 1, True)) - self.assertEquals('1.01 minutes', str_tools.get_time_label(61, 2, True)) + self.assertEquals('2h', str_tools.time_label(10000)) + self.assertEquals('1.0 minute', str_tools.time_label(61, 1, True)) + self.assertEquals('1.01 minutes', str_tools.time_label(61, 2, True))

- self.assertEquals('0s', str_tools.get_time_label(0)) - self.assertEquals('0 seconds', str_tools.get_time_label(0, is_long = True)) - self.assertEquals('0.00s', str_tools.get_time_label(0, 2)) - self.assertEquals('-10s', str_tools.get_time_label(-10)) + self.assertEquals('0s', str_tools.time_label(0)) + self.assertEquals('0 seconds', str_tools.time_label(0, is_long = True)) + self.assertEquals('0.00s', str_tools.time_label(0, 2)) + self.assertEquals('-10s', str_tools.time_label(-10))

- self.assertRaises(TypeError, str_tools.get_time_label, None) - self.assertRaises(TypeError, str_tools.get_time_label, 'hello world') + self.assertRaises(TypeError, str_tools.time_label, None) + self.assertRaises(TypeError, str_tools.time_label, 'hello world')

- def test_get_time_labels(self): + def test_time_labels(self): """ - Checks the get_time_labels() function. + Checks the time_labels() function. """

# test the pydoc examples - self.assertEquals(['6m', '40s'], str_tools.get_time_labels(400)) - self.assertEquals(['1 hour', '40 seconds'], str_tools.get_time_labels(3640, True)) + self.assertEquals(['6m', '40s'], str_tools.time_labels(400)) + self.assertEquals(['1 hour', '40 seconds'], str_tools.time_labels(3640, True))

- self.assertEquals([], str_tools.get_time_labels(0)) - self.assertEquals(['-10s'], str_tools.get_time_labels(-10)) + self.assertEquals([], str_tools.time_labels(0)) + self.assertEquals(['-10s'], str_tools.time_labels(-10))

- self.assertRaises(TypeError, str_tools.get_time_labels, None) - self.assertRaises(TypeError, str_tools.get_time_labels, 'hello world') + self.assertRaises(TypeError, str_tools.time_labels, None) + self.assertRaises(TypeError, str_tools.time_labels, 'hello world')

- def test_get_short_time_label(self): + def test_short_time_label(self): """ - Checks the get_short_time_label() function. + Checks the short_time_label() function. """

# test the pydoc examples - self.assertEquals('01:51', str_tools.get_short_time_label(111)) - self.assertEquals('6-07:08:20', str_tools.get_short_time_label(544100)) + self.assertEquals('01:51', str_tools.short_time_label(111)) + self.assertEquals('6-07:08:20', str_tools.short_time_label(544100))

- self.assertEquals('00:00', str_tools.get_short_time_label(0)) + self.assertEquals('00:00', str_tools.short_time_label(0))

- self.assertRaises(TypeError, str_tools.get_short_time_label, None) - self.assertRaises(TypeError, str_tools.get_short_time_label, 'hello world') - self.assertRaises(ValueError, str_tools.get_short_time_label, -5) + self.assertRaises(TypeError, str_tools.short_time_label, None) + self.assertRaises(TypeError, str_tools.short_time_label, 'hello world') + self.assertRaises(ValueError, str_tools.short_time_label, -5)

def test_parse_short_time_label(self): """