[tor-commits] [stem/master] Add stem.util.term to tutorials

[atagar at torproject.org]

commit a774bdbf151b24b9d87188d27d3733bdf5b66383
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Dec 11 12:58:45 2017 -0800

    Add stem.util.term to tutorials
    
    Long ago I made a utilities tutorial with the plan for it to have a myriad of
    tools, but year later it still just has our connection module. Long overdue we
    add something. :P
---
 docs/_static/example/words_with.py |  40 +++++++++++++++++++++++++++++++++++++
 docs/_static/words_with.png        | Bin 0 -> 46697 bytes
 docs/api.rst                       |   1 +
 docs/tutorials/east_of_the_sun.rst |  24 +++++++++++++++++++++-
 4 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/docs/_static/example/words_with.py b/docs/_static/example/words_with.py
new file mode 100644
index 00000000..b7956cb2
--- /dev/null
+++ b/docs/_static/example/words_with.py
@@ -0,0 +1,40 @@
+import itertools
+import re
+
+from stem.util import term
+from stem.util.term import Attr, Color
+
+
+def get_words_with(target, attr):
+  """
+  Provides words with the given substring highlighted within it.
+
+  :param str target: substring to match against
+  :param tuple attr: terminal formatting to highlight the match with
+
+  :returns: **iterable** with words containing that substring
+  """
+
+  matches = []
+  word_matcher = re.compile('(.*)(%s)(.*)' % target, re.I)
+
+  with open('/etc/dictionaries-common/words') as dictionary_file:
+    for word in dictionary_file:
+      match = word_matcher.match(word)
+
+      if match:
+        yield ''.join((
+          match.group(1),
+          term.format(match.group(2), *attr),
+          match.group(3),
+        ))
+
+
+if __name__ == '__main__':
+  target = raw_input("What substring would you like to look for? We'll get words containing it: ")
+  attr = (Attr.BOLD, Color.YELLOW)
+
+  print("Words with '%s' include...\n" % term.format(target, *attr))
+
+  for words in itertools.izip_longest(*(get_words_with(target, attr),) * 4):
+    print('%-30s%-30s%-30s%-30s' % tuple([w if w else '' for w in words]))
diff --git a/docs/_static/words_with.png b/docs/_static/words_with.png
new file mode 100644
index 00000000..6e0b0b48
Binary files /dev/null and b/docs/_static/words_with.png differ
diff --git a/docs/api.rst b/docs/api.rst
index 9fd56c65..307184dc 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -49,6 +49,7 @@ Utilities
 * `stem.util.conf <api/util/conf.html>`_ - Configuration file handling.
 * `stem.util.connection <api/util/connection.html>`_ - Connection and IP related utilities.
 * `stem.util.enum <api/util/enum.html>`_ - Enumeration class.
+* `stem.util.proc <api/util/proc.html>`_ - Resource and connection usage via proc contents.
 * `stem.util.str_tools <api/util/str_tools.html>`_ - String utilities.
 * `stem.util.system <api/util/system.html>`_ - Tools related to the local system.
 * `stem.util.term <api/util/term.html>`_ - Tools for interacting with the terminal.
diff --git a/docs/tutorials/east_of_the_sun.rst b/docs/tutorials/east_of_the_sun.rst
index d74c347f..845cbf4a 100644
--- a/docs/tutorials/east_of_the_sun.rst
+++ b/docs/tutorials/east_of_the_sun.rst
@@ -3,8 +3,31 @@ East of the Sun & West of the Moon
 
 The following is an overview of some of the utilities Stem provides.
 
+* :ref:`terminal-styling`
 * :ref:`connection-resolution`
 
+.. _terminal-styling:
+
+Terminal Styling
+----------------
+
+Know what's better than text? Pretty text!
+
+OSX, Linux, BSD... really, everything except Windows supports terminal
+formatting through `ANSI escape sequences
+<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes>`_. Doing this
+yourself is easy, but we also provide a module to make it `even easier
+<../api/util/term.html>`_.
+
+|
+
+.. image:: /_static/words_with.png
+
+|
+
+.. literalinclude:: /_static/example/words_with.py
+   :language: python
+
 .. _connection-resolution:
 
 Connection Resolution
@@ -46,4 +69,3 @@ simple script that dumps Tor's present connections.
 
     192.168.0.1:59014 => 38.229.79.2:443
     192.168.0.1:58822 => 68.169.35.102:443
-