Network Status Documents
************************

Parsing for Tor network status documents. This supports both the v2
and v3 dir-spec. Documents can be obtained from a few sources…

* The ‘cached-consensus’ file in Tor’s data directory.

* Archived descriptors provided by CollecTor.

* Directory authorities and mirrors via their DirPort.

… and contain the following sections…

* document header

* list of "stem.descriptor.networkstatus.DirectoryAuthority"

* list of "stem.descriptor.router_status_entry.RouterStatusEntry"

* document footer

**For a great graphical overview see** Jordan Wright’s chart
describing the anatomy of the consensus.

Of these, the router status entry section can be quite large (on the
order of hundreds of kilobytes). As such we provide a couple of
methods for reading network status documents through "parse_file()".
For more information see "DocumentHandler()"…

   from stem.descriptor import parse_file, DocumentHandler

   with open('.tor/cached-consensus', 'rb') as consensus_file:
     # Processes the routers as we read them in. The routers refer to a document
     # with an unset 'routers' attribute.

     for router in parse_file(consensus_file, 'network-status-consensus-3 1.0', document_handler = DocumentHandler.ENTRIES):
       print router.nickname

**Module Overview:**

   NetworkStatusDocument - Network status document
     |- NetworkStatusDocumentV2 - Version 2 network status document
     |- NetworkStatusDocumentV3 - Version 3 network status document
     +- BridgeNetworkStatusDocument - Version 3 network status document for bridges

   KeyCertificate - Certificate used to authenticate an authority
   DocumentSignature - Signature of a document by a directory authority
   DetachedSignature - Stand alone signature used when making the consensus
   DirectoryAuthority - Directory authority as defined in a v3 network status document
