commit 70227efa08d77f65b1eea069ae93bd0ba0bf1993
Author: Damian Johnson <atagar(a)torproject.org>
Date: Fri Oct 19 09:41:34 2012 -0700
Utils for human readable time and size metrics
Snagging the utilities from arm's src/util/uiTools.py for making human readable
labels of time and size metrics. They'll not only be handy for stem's users,
but also our exception messages and something I want to use in our tutorials.
I've simplified these functions a bit and added unit tests for the pydoc
examples. More tests are needed, though...
---
run_tests.py | 2 +
stem/util/enum.py | 24 +----
stem/util/str_tools.py | 244 +++++++++++++++++++++++++++++++++++++++++++
stem/util/term.py | 3 +-
test/unit/util/__init__.py | 1 +
test/unit/util/enum.py | 16 ---
test/unit/util/str_tools.py | 53 +++++++++
7 files changed, 304 insertions(+), 39 deletions(-)
diff --git a/run_tests.py b/run_tests.py
index c891bf6..8cd393c 100755
--- a/run_tests.py
+++ b/run_tests.py
@@ -37,6 +37,7 @@ import test.unit.util.conf
import test.unit.util.connection
import test.unit.util.enum
import test.unit.util.proc
+import test.unit.util.str_tools
import test.unit.util.system
import test.unit.util.tor_tools
import test.unit.exit_policy.policy
@@ -114,6 +115,7 @@ UNIT_TESTS = (
test.unit.util.connection.TestConnection,
test.unit.util.conf.TestConf,
test.unit.util.proc.TestProc,
+ test.unit.util.str_tools.TestStrTools,
test.unit.util.system.TestSystem,
test.unit.util.tor_tools.TestTorTools,
test.unit.descriptor.export.TestExport,
diff --git a/stem/util/enum.py b/stem/util/enum.py
index 50f6728..72c4443 100644
--- a/stem/util/enum.py
+++ b/stem/util/enum.py
@@ -24,7 +24,6 @@ with overwritten string counterparts:
::
- to_camel_case - converts a string to camel case
UppercaseEnum - Provides an enum instance with capitalized values.
Enum - Provides a basic, ordered enumeration.
|- keys - string representation of our enum keys
@@ -35,26 +34,7 @@ with overwritten string counterparts:
+- __iter__ - iterator over our enum keys
"""
-def to_camel_case(label, word_divider = " "):
- """
- Converts the given string to camel case, ie:
-
- ::
-
- >>> to_camel_case("I_LIKE_PEPPERJACK!")
- 'I Like Pepperjack!'
-
- :param str label: input string to be converted
- :param str word_divider: string used to replace underscores
- """
-
- words = []
- for entry in label.split("_"):
- if len(entry) == 0: words.append("")
- elif len(entry) == 1: words.append(entry.upper())
- else: words.append(entry[0].upper() + entry[1:].lower())
-
- return word_divider.join(words)
+import stem.util.str_tools
def UppercaseEnum(*args):
"""
@@ -86,7 +66,7 @@ class Enum(object):
for entry in args:
if isinstance(entry, str):
- key, val = entry, to_camel_case(entry)
+ key, val = entry, stem.util.str_tools.to_camel_case(entry)
elif isinstance(entry, tuple) and len(entry) == 2:
key, val = entry
else: raise ValueError("Unrecognized input: %s" % args)
diff --git a/stem/util/str_tools.py b/stem/util/str_tools.py
new file mode 100644
index 0000000..b874425
--- /dev/null
+++ b/stem/util/str_tools.py
@@ -0,0 +1,244 @@
+"""
+Toolkit for various string activity.
+
+**Module Overview:**
+
+::
+
+ to_camel_case - converts a string to camel case
+ 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
+ parse_short_time_label - seconds represented by a short time label
+"""
+
+# label conversion tuples of the form...
+# (bits / bytes / seconds, short label, long label)
+SIZE_UNITS_BITS = (
+ (140737488355328.0, " Pb", " Petabit"),
+ (137438953472.0, " Tb", " Terabit"),
+ (134217728.0, " Gb", " Gigabit"),
+ (131072.0, " Mb", " Megabit"),
+ (128.0, " Kb", " Kilobit"),
+ (0.125, " b", " Bit"),
+)
+
+SIZE_UNITS_BYTES = (
+ (1125899906842624.0, " PB", " Petabyte"),
+ (1099511627776.0, " TB", " Terabyte"),
+ (1073741824.0, " GB", " Gigabyte"),
+ (1048576.0, " MB", " Megabyte"),
+ (1024.0, " KB", " Kilobyte"),
+ (1.0, " B", " Byte"),
+)
+
+TIME_UNITS = (
+ (86400.0, "d", " day"),
+ (3600.0, "h", " hour"),
+ (60.0, "m", " minute"),
+ (1.0, "s", " second"),
+)
+
+def to_camel_case(label, word_divider = " "):
+ """
+ Converts the given string to camel case, ie:
+
+ ::
+
+ >>> to_camel_case("I_LIKE_PEPPERJACK!")
+ 'I Like Pepperjack!'
+
+ :param str label: input string to be converted
+ :param str word_divider: string used to replace underscores
+ """
+
+ words = []
+ for entry in label.split("_"):
+ if len(entry) == 0: words.append("")
+ elif len(entry) == 1: words.append(entry.upper())
+ else: words.append(entry[0].upper() + entry[1:].lower())
+
+ return word_divider.join(words)
+
+def get_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
+ is_long option is used this expands unit labels to be the properly pluralized
+ full word (for instance 'Kilobytes' rather than 'KB'). Units go up through
+ petabytes.
+
+ ::
+
+ >>> get_size_label(2000000)
+ '1 MB'
+
+ >>> get_size_label(1050, 2)
+ '1.02 KB'
+
+ >>> get_size_label(1050, 3, True)
+ '1.025 Kilobytes'
+
+ :param int byte_count: number of bytes to be converted
+ :param int decimal: number of decimal digits to be included
+ :param bool is_long: expands units label
+ :param bool is_bytes: provides units in bytes if true, bits otherwise
+ """
+
+ if is_bytes: return _get_label(SIZE_UNITS_BYTES, byte_count, decimal, is_long)
+ else: return _get_label(SIZE_UNITS_BITS, byte_count, decimal, is_long)
+
+def get_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.
+
+ This defaults to presenting single character labels, but if the is_long
+ option is used this expands labels to be the full word (space included and
+ properly pluralized). For instance, "4h" would be "4 hours" and "1m" would
+ become "1 minute".
+
+ ::
+
+ >>> get_time_label(10000)
+ '2h'
+
+ >>> get_time_label(61, 1, True)
+ '1.0 minute'
+
+ >>> get_time_label(61, 2, True)
+ '1.01 minutes'
+
+ :param int seconds: number of seconds to be converted
+ :param int decimal: number of decimal digits to be included
+ :param bool is_long: expands units label
+ """
+
+ return _get_label(TIME_UNITS, seconds, decimal, is_long)
+
+def get_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.
+ For example...
+
+ ::
+
+ >>> get_time_labels(400)
+ ['6m', '40s']
+
+ >>> get_time_labels(3640, True)
+ ['1 hour', '40 seconds']
+
+ :param int seconds: number of seconds to be converted
+ :param bool is_long: expands units label
+ """
+
+ time_labels = []
+
+ for count_per_unit, _, _ in TIME_UNITS:
+ if seconds >= count_per_unit:
+ time_labels.append(_get_label(TIME_UNITS, seconds, 0, is_long))
+ seconds %= count_per_unit
+
+ return time_labels
+
+def get_short_time_label(seconds):
+ """
+ Provides a time in the following format:
+ [[dd-]hh:]mm:ss
+
+ :param int seconds: number of seconds to be converted
+ """
+
+ time_comp = {}
+
+ for amount, _, label in TIME_UNITS:
+ count = int(seconds / amount)
+ seconds %= amount
+ time_comp[label.strip()] = count
+
+ label = "%02i:%02i" % (time_comp["minute"], time_comp["second"])
+
+ if time_comp["day"]:
+ label = "%i-%02i:%s" % (time_comp["day"], time_comp["hour"], label)
+ elif time_comp["hour"]:
+ label = "%02i:%s" % (time_comp["hour"], label)
+
+ return label
+
+def parse_short_time_label(label):
+ """
+ Provides the number of seconds corresponding to the formatting used for the
+ cputime and etime fields of ps:
+ [[dd-]hh:]mm:ss or mm:ss.ss
+
+ :param str label: time entry to be parsed
+
+ :raises: ValueError if input is malformed
+ """
+
+ days, hours, minutes, seconds = '0', '0', '0', '0'
+
+ if '-' in label:
+ days, label = label.split('-', 1)
+
+ time_comp = label.split(":")
+
+ if len(time_comp) == 3:
+ hours, minutes, seconds = time_comp
+ elif len(time_comp) == 2:
+ minutes, seconds = time_comp
+ else:
+ raise ValueError("Invalid time format, we expected '[[dd-]hh:]mm:ss' or 'mm:ss.ss': %s" % label)
+
+ try:
+ time_sum = int(float(seconds))
+ time_sum += int(minutes) * 60
+ time_sum += int(hours) * 3600
+ time_sum += int(days) * 86400
+ return time_sum
+ except ValueError:
+ raise ValueError("Non-numeric value in time entry: %s" % label)
+
+def _get_label(units, count, decimal, is_long):
+ """
+ Provides label corresponding to units of the highest significance in the
+ provided set. This rounds down (ie, integer truncation after visible units).
+
+ :param tuple units: type of units to be used for conversion, containing (count_per_unit, short_label, long_label)
+ :param int count: number of base units being converted
+ :param int decimal: decimal precision of label
+ :param bool is_long: uses the long label if true, short label otherwise
+ """
+
+ # formatted string for the requested number of digits
+ label_format = "%%.%if" % decimal
+
+ # for zero or negative values use the smallest units
+ if count < 1:
+ units_label = units[-1][2] + "s" if is_long else units[-1][1]
+ return "%s%s" % (label_format % count, units_label)
+
+ for count_per_unit, short_label, long_label in units:
+ if count >= count_per_unit:
+ # Rounding down with a '%f' is a little clunky. Reducing the count so
+ # it'll divide evenly as the rounded down value.
+
+ count -= count % (count_per_unit / (10 ** decimal))
+ count_label = label_format % (count / count_per_unit)
+
+ if is_long:
+ # Pluralize if any of the visible units make it greater than one. For
+ # instance 1.0003 is plural but 1.000 isn't.
+
+ if decimal > 0:
+ is_plural = count > count_per_unit
+ else:
+ is_plural = count >= count_per_unit * 2
+
+ return count_label + long_label + ("s" if is_plural else "")
+ else:
+ return count_label + short_label
+
diff --git a/stem/util/term.py b/stem/util/term.py
index fd4c22e..556b481 100644
--- a/stem/util/term.py
+++ b/stem/util/term.py
@@ -3,6 +3,7 @@ Utilities for working with the terminal.
"""
import stem.util.enum
+import stem.util.str_tools
TERM_COLORS = ("BLACK", "RED", "GREEN", "YELLOW", "BLUE", "MAGENTA", "CYAN", "WHITE")
@@ -41,7 +42,7 @@ def format(msg, *attr):
encodings = []
for text_attr in attr:
- text_attr, encoding = stem.util.enum.to_camel_case(text_attr), None
+ text_attr, encoding = stem.util.str_tools.to_camel_case(text_attr), None
encoding = FG_ENCODING.get(text_attr, encoding)
encoding = BG_ENCODING.get(text_attr, encoding)
encoding = ATTR_ENCODING.get(text_attr, encoding)
diff --git a/test/unit/util/__init__.py b/test/unit/util/__init__.py
index d0eeda3..33b81d3 100644
--- a/test/unit/util/__init__.py
+++ b/test/unit/util/__init__.py
@@ -7,6 +7,7 @@ __all__ = [
"connection",
"enum",
"proc",
+ "str_tools",
"system",
"tor_tools",
]
diff --git a/test/unit/util/enum.py b/test/unit/util/enum.py
index 5a28f62..88469dd 100644
--- a/test/unit/util/enum.py
+++ b/test/unit/util/enum.py
@@ -6,22 +6,6 @@ import unittest
import stem.util.enum
class TestEnum(unittest.TestCase):
- def test_to_camel_case(self):
- """
- Checks the stem.util.enum.to_camel_case function.
- """
-
- # test the pydoc example
- self.assertEquals("I Like Pepperjack!", stem.util.enum.to_camel_case("I_LIKE_PEPPERJACK!"))
-
- # check a few edge cases
- self.assertEquals("", stem.util.enum.to_camel_case(""))
- self.assertEquals("Hello", stem.util.enum.to_camel_case("hello"))
- self.assertEquals("Hello", stem.util.enum.to_camel_case("HELLO"))
- self.assertEquals("Hello World", stem.util.enum.to_camel_case("hello__world"))
- self.assertEquals("Hello\tworld", stem.util.enum.to_camel_case("hello\tWORLD"))
- self.assertEquals("Hello\t\tWorld", stem.util.enum.to_camel_case("hello__world", "\t"))
-
def test_enum_examples(self):
"""
Checks that the pydoc examples are accurate.
diff --git a/test/unit/util/str_tools.py b/test/unit/util/str_tools.py
new file mode 100644
index 0000000..ce5539f
--- /dev/null
+++ b/test/unit/util/str_tools.py
@@ -0,0 +1,53 @@
+"""
+Unit tests for the stem.util.str_tools functions.
+"""
+
+import unittest
+from stem.util import str_tools
+
+class TestStrTools(unittest.TestCase):
+ def test_to_camel_case(self):
+ """
+ Checks the to_camel_case() function.
+ """
+
+ # test the pydoc example
+ self.assertEquals("I Like Pepperjack!", str_tools.to_camel_case("I_LIKE_PEPPERJACK!"))
+
+ # check a few edge cases
+ self.assertEquals("", str_tools.to_camel_case(""))
+ self.assertEquals("Hello", str_tools.to_camel_case("hello"))
+ self.assertEquals("Hello", str_tools.to_camel_case("HELLO"))
+ self.assertEquals("Hello World", str_tools.to_camel_case("hello__world"))
+ self.assertEquals("Hello\tworld", str_tools.to_camel_case("hello\tWORLD"))
+ self.assertEquals("Hello\t\tWorld", str_tools.to_camel_case("hello__world", "\t"))
+
+ def test_get_size_label(self):
+ """
+ Checks the get_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))
+
+ def test_get_time_label(self):
+ """
+ Checks the get_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))
+
+ def test_get_time_labels(self):
+ """
+ Checks the get_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))
+
