[tor-commits] [stem/master] [PATCH] Adds a parse_bytes() function to load descriptors

[atagar at torproject.org]

commit 74d7eeef9f478c29531f9cf3b12f54b7c298ce99
Author: Iain R. Learmonth <irl at fsfe.org>
Date:   Tue Nov 20 10:44:31 2018 -0800

    [PATCH] Adds a parse_bytes() function to load descriptors
    
    A warning message suggests wrapping bytes in BytesIO and then calling
    parse_file(), but this is a simple step that could be included as a
    convenience function.
    
    In my particular use case, I'm loading from a file but I'd like to
    perform the read asynchronously using asyncio.
    
      https://trac.torproject.org/projects/tor/ticket/28450
---
 stem/descriptor/__init__.py | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py
index 25b99ead..aa424fad 100644
--- a/stem/descriptor/__init__.py
+++ b/stem/descriptor/__init__.py
@@ -8,6 +8,7 @@ Package for parsing and processing descriptor data.
 
 ::
 
+  parse_bytes - Parses the descriptors in a :class:`bytes`.
   parse_file - Parses the descriptors in a file.
   create - Creates a new custom descriptor.
   create_signing_key - Cretes a signing key that can be used for creating descriptors.
@@ -87,6 +88,7 @@ import base64
 import codecs
 import collections
 import copy
+import io
 import os
 import random
 import re
@@ -115,15 +117,16 @@ __all__ = [
   'networkstatus',
   'router_status_entry',
   'tordnsel',
+  'parse_bytes',
   'parse_file',
   'Descriptor',
 ]
 
 UNSEEKABLE_MSG = """\
-File object isn't seekable. Try wrapping it with a BytesIO instead...
+File object isn't seekable. Try using parse_bytes() instead:
 
   content = my_file.read()
-  parsed_descriptors = stem.descriptor.parse_file(io.BytesIO(content))
+  parsed_descriptors = stem.descriptor.parse_bytes(content)
 """
 
 KEYWORD_CHAR = 'a-zA-Z0-9-'
@@ -192,6 +195,24 @@ class SigningKey(collections.namedtuple('SigningKey', ['private', 'public', 'pub
   """
 
 
+def parse_bytes(descriptor_bytes, **kwargs):
+  """
+  Read the descriptor contents from a :class:`bytes`, providing an iterator
+  for its :class:`~stem.descriptor.__init__.Descriptor` contents.
+
+  :param bytes descriptor_bytes: Raw descriptor
+  :param dict kwargs: Keyword arguments as used for :func:`parse_file`.
+
+  :returns: iterator for :class:`~stem.descriptor.__init__.Descriptor` instances in the file
+
+  :raises:
+    * **ValueError** if the contents is malformed and validate is True
+    * **TypeError** if we can't match the contents of the file to a descriptor type
+    * **IOError** if unable to read from the descriptor_file
+  """
+  return parse_file(io.BytesIO(descriptor_bytes))
+
+
 def parse_file(descriptor_file, descriptor_type = None, validate = False, document_handler = DocumentHandler.ENTRIES, normalize_newlines = None, **kwargs):
   """
   Simple function to read the descriptor contents from a file, providing an