[tor-commits] [stem/master] Adding stem.manual.database function

[atagar at torproject.org]

commit 7ad11311916b47099862db3a8fd40c547e11e1c8
Author: Damian Johnson <atagar at torproject.org>
Date:   Fri Aug 25 13:16:48 2017 -0700

    Adding stem.manual.database function
    
    Function for getting a database cursor for our cache. This will allow retrieval
    of selective manual information rather than a full Manual instance.
---
 docs/change_log.rst |  2 ++
 stem/manual.py      | 27 ++++++++++++++++++++++++---
 test/unit/manual.py |  5 +++++
 3 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst
index 204d5718..5a581ff3 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -55,6 +55,8 @@ The following are only available within Stem's `git repository
   * Tor change caused :func:`~stem.control.Controller.list_ephemeral_hidden_services` to provide empty strings if unset (:trac:`21329`)
   * Better error message when :func:`~stem.control.Controller.set_conf` fails due to an option being immutable
   * :func:`~stem.control.Controller.is_geoip_unavailable` now determines if database is available right away
+  * Caching manual information as sqlite rather than stem.util.conf, making :func:`stem.manual.Manual.from_cache` about ~8x faster
+  * Added :func:`~stem.manual.database` to get a cursor for the manual cache
   * Failed to parse torrcs without a port on ipv6 exit policy entries
   * Resilient to 'Tor' prefix in 'GETINFO version' result (:spec:`c5ff1b1`)
   * More succinct trace level logging
diff --git a/stem/manual.py b/stem/manual.py
index b724de25..b2f31a9e 100644
--- a/stem/manual.py
+++ b/stem/manual.py
@@ -47,6 +47,7 @@ us what our torrc options do...
 .. versionadded:: 1.5.0
 """
 
+import contextlib
 import os
 import shutil
 import sqlite3
@@ -94,6 +95,28 @@ CATEGORY_SECTIONS = OrderedDict((
 ))
 
 
+ at contextlib.contextmanager
+def database(path = None):
+  """
+  Provides a database cursor for a sqlite cache.
+
+  .. versionadded:: 1.6.0
+
+  :param str path: cached manual content to read, if not provided this uses
+    the bundled manual information
+
+  :returns: :class:`sqlite3.Cursor` for the database cache
+
+  :raises: **IOError** if a **path** was provided and we were unable to read it
+  """
+
+  if path is None:
+    path = CACHE_PATH
+
+  with sqlite3.connect(path) as conn:
+    yield conn.cursor()
+
+
 class ConfigOption(object):
   """
   Tor configuration attribute found in its torrc.
@@ -337,9 +360,7 @@ class Manual(object):
 
   @staticmethod
   def _from_sqlite_cache(path):
-    with sqlite3.connect(path) as conn:
-      cursor = conn.cursor()
-
+    with database(path) as cursor:
       cursor.execute('SELECT name, synopsis, description, man_commit, stem_commit FROM metadata')
       name, synopsis, description, man_commit, stem_commit = cursor.fetchone()
 
diff --git a/test/unit/manual.py b/test/unit/manual.py
index f025c1a1..eab9bdfc 100644
--- a/test/unit/manual.py
+++ b/test/unit/manual.py
@@ -102,6 +102,11 @@ def _cached_manual():
 
 
 class TestManual(unittest.TestCase):
+  def test_database(self):
+    with stem.manual.database() as cursor:
+      cursor.execute('SELECT description FROM torrc WHERE name="CookieAuthFile"')
+      self.assertEqual("If set, this option overrides the default location and file name for Tor's cookie file. (See CookieAuthentication above.)", cursor.fetchone()[0])
+
   def test_has_all_summaries(self):
     """
     Check that we have brief, human readable summaries for all of tor's