Bandwidth Files

Bandwidth files.

class bushel.bandwidth.file.BandwidthFileLineError[source]

Enumeration of forgivable errors that may be encountered during parsing of lines in a bandwidth file.

Name

Description

SHORT_TERMINATOR

A terminator with 4 = instead of 5. https://bugs.torproject.org/28379

NO_TERMINATOR

No terminator present, for pre-1.0.0 compatibility.
class bushel.bandwidth.file.BandwidthFileLiner(allowed_errors=None)[source]

Parses BandwidthFileToken s into BandwidthFileTimestamp, BandwidthFileHeaderLine s and BandwidthFileRelayLine. By default this is a strict implementation of the Tor Bandwidth File Specification version 1.4.0 [bandwidth-file-spec], but this can be relaxed to account for parsing older versions, or for known bugs in Tor implementations.

Lines are produced by processing tokens according to a state machine:

digraph g { start [label="START"]; timestamp [label="TIMESTAMP"]; header_line [label="HEADER-LINE"]; header_line_kv [label="HEADER-LINE-KV"]; relay_line [label="RELAY-LINE"]; relay_line_sp [label="RELAY-LINE-SP"]; relay_line_kv [label="RELAY-LINE-KV"]; done [label="DONE"]; start -> timestamp [label="TIMESTAMP"]; timestamp -> header_line [label="NL"]; header_line -> header_line_kv [label="KEYVALUE"]; header_line_kv -> header_line [label="NL"]; header_line -> relay_line [label="TERMINATOR"]; header_line -> relay_line [label="SHORT_TERMINATOR", color="red"]; header_line_kv -> relay_line_sp [label="SP", color="red"]; relay_line -> relay_line_kv [label="KEYVALUE"]; relay_line_kv -> relay_line [label="NL"]; relay_line_kv -> relay_line_sp [label="SP"]; relay_line_sp -> relay_line_kv [label="KEYVALUE"]; relay_line -> done [label="EOF"]; }

State transitions shown in red would ideally not be needed as they are protocol violations, but implementations of the protocol exist that produce documents requiring these transitions and we need to be bug compatible.

Parameters

allowed_errors (list(BandwidthFileLineError)) – A list of errors that will be considered non-fatal during itemization.

class bushel.bandwidth.file.BandwidthFileToken[source]
Variables

  • kind (str) – the kind of token

  • value (bytes) – kind-dependent value

  • line (int) – line number

  • column (int) – column number