[tor-commits] [stem/master] Better document the DocumentHandler's behavior

[atagar at torproject.org]

commit 37a95c652cb9ec961bff9fd0cfa1b0b518d072f0
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Dec 23 17:05:02 2017 -0800

    Better document the DocumentHandler's behavior
    
    Good point by Tim on...
    
      https://trac.torproject.org/projects/tor/ticket/24705
---
 stem/descriptor/__init__.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py
index 1fb2bb2c..158f1a4f 100644
--- a/stem/descriptor/__init__.py
+++ b/stem/descriptor/__init__.py
@@ -29,6 +29,23 @@ Package for parsing and processing descriptor data.
   and upfront runtime. However, if read time and memory aren't a concern then
   **DOCUMENT** can provide you with a fully populated document.
 
+  This handler doesn't change the fact that provide descriptors return an
+  iterator. In the case of **DOCUMENT** and **BARE_DOCUMENT** that iterator
+  would have just a single item - the document itself.
+
+  Simple way to handle this is to call **next()** to get the iterator's one and
+  only value...
+
+  ::
+
+    import stem.descriptor.remote
+    from stem.descriptor import DocumentHandler
+
+    consensus = next(stem.descriptor.remote.get_consensus(
+      document_handler = DocumentHandler.BARE_DOCUMENT,
+    )
+
+
   =================== ===========
   DocumentHandler     Description
   =================== ===========