[tor-commits] [stem/master] Dropping get_* prefix from string util functions
atagar at torproject.org
atagar at torproject.org
Tue Sep 2 03:55:48 UTC 2014
commit 7fc393595e9ee2e13283886df609402e9ed9bbfa
Author: Damian Johnson <atagar at 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):
"""
More information about the tor-commits
mailing list