# Stem Docs

## 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