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

   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

   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)

   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)

      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': [],
         })
