[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Utils for human readable time and size metrics



commit 70227efa08d77f65b1eea069ae93bd0ba0bf1993
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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))
+



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits