[tor-commits] [stem/master] Add encoding() method to stem.util.term

[atagar at torproject.org]

commit 50d884e9c9a732210825bd9079c8303ef65d10aa
Author: Damian Johnson <atagar at torproject.org>
Date:   Sun Jul 24 09:22:25 2016 -0700

    Add encoding() method to stem.util.term
    
    Breaking up our format() method a little by adding a helper to get ANSI escape
    sequences. This is something I need for nyx right now anyway...
    
    Oddly our stem.util.term module didn't have any direct test coverage. It was
    tested tangentially by our testing harness and interpreter tests but strange I
    missed unit test coverage for this one. It's an easy module to include.
    
    Oh well - threw in some basic tests.
---
 docs/change_log.rst    |  1 +
 stem/util/term.py      | 57 +++++++++++++++++++++++++++++++++-----------------
 test/settings.cfg      |  1 +
 test/unit/util/term.py | 30 ++++++++++++++++++++++++++
 4 files changed, 70 insertions(+), 19 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index 98dc18c..839c7c9 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -94,6 +94,7 @@ The following are only available within Stem's `git repository
   * Added an **is_ipv6** value to :class:`~stem.util.connection.Connection` instances
   * Added :func:`~stem.util.system.pids_by_user`
   * Added :func:`~stem.util.connection.address_to_int`
+  * Added :func:`~stem.util.term.encoding`
   * Added :func:`~stem.util.__init__.datetime_to_unix`
 
  * **Interpreter**
diff --git a/stem/util/term.py b/stem/util/term.py
index 3287bb1..a32fe93 100644
--- a/stem/util/term.py
+++ b/stem/util/term.py
@@ -8,6 +8,7 @@ Utilities for working with the terminal.
 
 ::
 
+  encoding - provides the ANSI escape sequence for a terminal attribute
   format - wrap text with ANSI for the given colors or attributes
 
 .. data:: Color (enum)
@@ -65,6 +66,41 @@ CSI = '\x1B[%sm'
 RESET = CSI % '0'
 
 
+def encoding(*attrs):
+  """
+  Provides the ANSI escape sequence for these terminal color or attributes.
+
+  .. versionadded:: 1.5.0
+
+  :param list attr: :data:`~stem.util.terminal.Color`,
+    :data:`~stem.util.terminal.BgColor`, or :data:`~stem.util.terminal.Attr` to
+    provide an ecoding for
+
+  :return: **str** of the ANSI escape sequence, **None** no attributes are
+    recognized
+  """
+
+  term_encodings = []
+
+  for attr in attrs:
+    # TODO: Account for an earlier misspelled attribute. This should be dropped
+    # in Stem. 2.0.x.
+
+    if attr == 'HILIGHT':
+      attr = 'HIGHLIGHT'
+
+    attr = stem.util.str_tools._to_camel_case(attr)
+    term_encoding = FG_ENCODING.get(attr, None)
+    term_encoding = BG_ENCODING.get(attr, term_encoding)
+    term_encoding = ATTR_ENCODING.get(attr, term_encoding)
+
+    if term_encoding:
+      term_encodings.append(term_encoding)
+
+  if term_encodings:
+    return CSI % ';'.join(term_encodings)
+
+
 def format(msg, *attr):
   """
   Simple terminal text formatting using `ANSI escape sequences
@@ -93,26 +129,9 @@ def format(msg, *attr):
   if RESET in msg:
     return ''.join([format(comp, *attr) for comp in msg.split(RESET)])
 
-  encodings = []
-
-  for text_attr in attr:
-    # TODO: Account for an earlier misspelled attribute. This should be dropped
-    # in Stem. 2.0.x.
-
-    if text_attr == 'HILIGHT':
-      text_attr = 'HIGHLIGHT'
-
-    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)
-
-    if encoding:
-      encodings.append(encoding)
-
-  if encodings:
-    prefix, suffix = CSI % ';'.join(encodings), RESET
+  prefix, suffix = encoding(*attr), RESET
 
+  if prefix:
     if Attr.READLINE_ESCAPE in attr:
       prefix = '\001%s\002' % prefix
       suffix = '\001%s\002' % suffix
diff --git a/test/settings.cfg b/test/settings.cfg
index fd199e1..10e2ccf 100644
--- a/test/settings.cfg
+++ b/test/settings.cfg
@@ -167,6 +167,7 @@ test.unit_tests
 |test.unit.util.proc.TestProc
 |test.unit.util.str_tools.TestStrTools
 |test.unit.util.system.TestSystem
+|test.unit.util.term.TestTerminal
 |test.unit.util.tor_tools.TestTorTools
 |test.unit.util.__init__.TestBaseUtil
 |test.unit.descriptor.export.TestExport
diff --git a/test/unit/util/term.py b/test/unit/util/term.py
new file mode 100644
index 0000000..758db22
--- /dev/null
+++ b/test/unit/util/term.py
@@ -0,0 +1,30 @@
+"""
+Unit tests for the stem.util.term functions.
+"""
+
+import unittest
+
+import stem.util.term
+
+from stem.util.term import Color, Attr
+
+
+class TestTerminal(unittest.TestCase):
+  def test_encoding(self):
+    """
+    Exercises our encoding function.
+    """
+
+    self.assertEqual(None, stem.util.term.encoding())
+    self.assertEqual('\x1b[31m', stem.util.term.encoding(Color.RED))
+    self.assertEqual('\x1b[31;1m', stem.util.term.encoding(Color.RED, Attr.BOLD))
+
+  def test_format(self):
+    """
+    Exercises our format function.
+    """
+
+    self.assertEqual('hi!', stem.util.term.format('hi!'))
+    self.assertEqual('\x1b[31mhi!\x1b[0m', stem.util.term.format('hi!', Color.RED))
+    self.assertEqual('\x1b[31;1mhi!\x1b[0m', stem.util.term.format('hi!', Color.RED, Attr.BOLD))
+    self.assertEqual('\001\x1b[31m\002hi!\001\x1b[0m\002', stem.util.term.format('hi!', Color.RED, Attr.READLINE_ESCAPE))