Bandwidth File¶

Parsing for Bandwidth Authority metrics as described in Tor's bandwidth-file-spec.

Module Overview:

BandwidthFile - Tor bandwidth authority measurements.

New in version 1.8.0.

class stem.descriptor.bandwidth_file.RecentStats[source]¶

Bases: object

Statistical information collected over the last 'data_period' (by default five days).

Variables:

consensus_count (int) -- number of consensuses published during this period prioritized_relays (int) -- number of relays prioritized to be measured prioritized_relay_lists (int) -- number of times a set of relays were prioritized to be measured measurement_attempts (int) -- number of relay measurements we attempted measurement_failures (int) -- number of measurement attempts that failed relay_failures (RelayFailures) -- number of relays we failed to measure

class stem.descriptor.bandwidth_file.RelayFailures[source]¶

Bases: object

Summary of the number of relays we were unable to measure.

Variables:

no_measurement (int) -- number of relays that did not have any successful measurements insuffient_period (int) -- number of relays whos measurements were collected over a period that was too small (1 day by default) insufficient_measurements (int) -- number of relays we did not collect enough measurements for (2 by default) stale (int) -- number of relays whos latest measurement is too old (5 days by default)

class stem.descriptor.bandwidth_file.BandwidthFile(raw_content, validate=False)[source]¶

Bases: stem.descriptor.Descriptor

Tor bandwidth authority measurements.

Variables:

measurements (dict) -- * mapping of relay fingerprints to their bandwidth measurement metadata header (dict) -- * header metadata timestamp (datetime) -- * time when these metrics were published version (str) -- * document format version software (str) -- application that generated these metrics software_version (str) -- version of the application that generated these metrics earliest_bandwidth (datetime) -- time of the first sampling latest_bandwidth (datetime) -- time of the last sampling created_at (datetime) -- time when this file was created generated_at (datetime) -- time when collection of these metrics started consensus_size (int) -- number of relays in the consensus eligible_count (int) -- relays with enough measurements to be included eligible_percent (int) -- percentage of consensus with enough measurements min_count (int) -- minimum eligible relays for results to be provided min_percent (int) -- minimum measured percentage of the consensus scanner_country (str) -- country code where this scan took place destinations_countries (list) -- all country codes that were scanned time_to_report_half_network (int) -- estimated number of seconds required to measure half the network, given recent measurements recent_stats (RecentStats) -- statistical information collected over the last 'data_period' (by default five days)

* attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined

TYPE_ANNOTATION_NAME = 'bandwidth-file'¶

classmethod content(attr=None, exclude=(), sign=False)[source]¶

Creates descriptor content with the given attributes. This descriptor type differs somewhat from others and treats our attr/exclude attributes as follows...

• 'timestamp' is a reserved key for our mandatory header unix timestamp.
• 'content' is a reserved key for our bandwidth measurement lines.
• All other keys are treated as header fields.

For example...

BandwidthFile.content({
  'timestamp': '12345',
  'version': '1.2.0',
  'content': [],
})

k = 'latest_bandwidth'¶