def test_annotations(self):
    """
    Checks that content before a descriptor are parsed as annotations.
    """

    desc_text = b'@pepperjack very tasty\[email protected] not so much\n'
    desc_text += get_relay_server_descriptor(content = True)
    desc_text += b'\ntrailing text that should be invalid, ho hum'

    # running _parse_file should provide an iterator with a single descriptor
    desc_iter = stem.descriptor.server_descriptor._parse_file(io.BytesIO(desc_text), validate = True)
    self.assertRaises(ValueError, list, desc_iter)

    desc_text = b'@pepperjack very tasty\[email protected] not so much\n'
    desc_text += get_relay_server_descriptor(content = True)
    desc_iter = stem.descriptor.server_descriptor._parse_file(io.BytesIO(desc_text))

    desc_entries = list(desc_iter)
    self.assertEqual(1, len(desc_entries))
    desc = desc_entries[0]

    self.assertEqual('caerSidi', desc.nickname)
    self.assertEqual(b'@pepperjack very tasty', desc.get_annotation_lines()[0])
    self.assertEqual(b'@mushrooms not so much', desc.get_annotation_lines()[1])
    self.assertEqual({b'@pepperjack': b'very tasty', b'@mushrooms': b'not so much'}, desc.get_annotations())
    self.assertEqual([], desc.get_unrecognized_lines())

  def test_outdated_relays(self, downloader_mock, stdout_mock):
    def tutorial_example():
      from stem.descriptor.remote import DescriptorDownloader
      from stem.version import Version

      downloader = DescriptorDownloader()
      count, with_contact = 0, 0

      print('Checking for outdated relays...\n')

      for desc in downloader.get_server_descriptors():
        if desc.tor_version < Version('0.2.3.0'):
          count += 1

          if desc.contact:
            print('  %-15s %s' % (desc.tor_version, desc.contact.decode('utf-8', 'replace')))
            with_contact += 1

      print('\n%i outdated relays found, %i had contact information' % (count, with_contact))

    downloader_mock().get_server_descriptors.return_value = [
      get_relay_server_descriptor({'platform': 'node-Tor 0.2.3.0 on Linux x86_64'}),
      get_relay_server_descriptor({'platform': 'node-Tor 0.1.0 on Linux x86_64'}),
      get_relay_server_descriptor({'opt': 'contact Random Person [email protected]', 'platform': 'node-Tor 0.2.3.0 on Linux x86_64'}),
      get_relay_server_descriptor({'opt': 'contact Sambuddha Basu', 'platform': 'node-Tor 0.1.0 on Linux x86_64'}),
    ]

    tutorial_example()

    self.assert_equal_unordered(OUTDATED_RELAYS_OUTPUT, stdout_mock.getvalue())

  def test_mirror_mirror_on_the_wall_4(self):
    def tutorial_example():
      from stem.control import Controller
      from stem.util import str_tools

      # provides a mapping of observed bandwidth to the relay nicknames
      def get_bw_to_relay():
        bw_to_relay = {}

        with Controller.from_port(control_port = 9051) as controller:
          controller.authenticate()

          for desc in controller.get_server_descriptors():
            if desc.exit_policy.is_exiting_allowed():
              bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)

        return bw_to_relay

      # prints the top fifteen relays

      bw_to_relay = get_bw_to_relay()
      count = 1

      for bw_value in sorted(bw_to_relay.keys(), reverse = True):
        for nickname in bw_to_relay[bw_value]:
          print "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2))
          count += 1

          if count > 15:
            return

    exit_descriptor = mocking.get_relay_server_descriptor({
      'router': 'speedyexit 149.255.97.109 9001 0 0'
    }, content = True).replace(b'reject *:*', b'accept *:*')

    exit_descriptor = mocking.sign_descriptor_content(exit_descriptor)
    exit_descriptor = RelayDescriptor(exit_descriptor)

    controller = mocking.get_object(Controller, {
      'authenticate': mocking.no_op(),
      'close': mocking.no_op(),
      'get_server_descriptors': mocking.return_value([
        exit_descriptor,
        mocking.get_relay_server_descriptor(),  # non-exit
        exit_descriptor,
        exit_descriptor,
      ])
    })

    mocking.mock(
      Controller.from_port, mocking.return_value(controller),
      target_module = Controller,
      is_static = True,
    )

    tutorial_example()
    self.assertEqual(MIRROR_MIRROR_OUTPUT, self.stdout.getvalue())

  def test_outdated_relays(self, downloader_mock, stdout_mock):
    downloader_mock().get_server_descriptors.return_value = [
      get_relay_server_descriptor({'platform': 'node-Tor 0.2.3.0 on Linux x86_64'}),
      get_relay_server_descriptor({'platform': 'node-Tor 0.1.0 on Linux x86_64'}),
      get_relay_server_descriptor({'opt': 'contact Random Person [email protected]', 'platform': 'node-Tor 0.2.3.0 on Linux x86_64'}),
      get_relay_server_descriptor({'opt': 'contact Sambuddha Basu', 'platform': 'node-Tor 0.1.0 on Linux x86_64'}),
    ]

    exec_documentation_example('outdated_relays.py')

    self.assert_equal_unordered(OUTDATED_RELAYS_OUTPUT, stdout_mock.getvalue())

  def test_published_leap_year(self):
    """
    Constructs with a published entry for a leap year, and when the date is
    invalid.
    """

    desc_text = get_relay_server_descriptor({'published': '2011-02-29 04:03:19'}, content = True)
    self._expect_invalid_attr(desc_text, 'published')

    desc_text = get_relay_server_descriptor({'published': '2012-02-29 04:03:19'}, content = True)
    expected_published = datetime.datetime(2012, 2, 29, 4, 3, 19)
    self.assertEqual(expected_published, RelayDescriptor(desc_text).published)

  def test_mirror_mirror_on_the_wall(self):
    from stem.descriptor.server_descriptor import RelayDescriptor
    from stem.descriptor.reader import DescriptorReader
    from stem.util import str_tools

    exit_descriptor = mocking.get_relay_server_descriptor({
     'router': 'speedyexit 149.255.97.109 9001 0 0'
    }, content = True).replace('reject *:*', 'accept *:*')
    exit_descriptor = mocking.sign_descriptor_content(exit_descriptor)
    exit_descriptor = RelayDescriptor(exit_descriptor)

    reader_wrapper = mocking.get_object(DescriptorReader, {
      '__enter__': lambda x: x,
      '__exit__': mocking.no_op(),
      '__iter__': mocking.return_value(iter((
        exit_descriptor,
        mocking.get_relay_server_descriptor(),  # non-exit
        exit_descriptor,
        exit_descriptor,
      )))
    })

    # provides a mapping of observed bandwidth to the relay nicknames
    def get_bw_to_relay():
      bw_to_relay = {}

      with reader_wrapper as reader:
        for desc in reader:
          if desc.exit_policy.is_exiting_allowed():
            bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)

      return bw_to_relay

    # prints the top fifteen relays

    bw_to_relay = get_bw_to_relay()
    count = 1

    for bw_value in sorted(bw_to_relay.keys(), reverse = True):
      for nickname in bw_to_relay[bw_value]:
        expected_line = "%i. speedyexit (102.13 KB/s)" % count
        printed_line = "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2))
        self.assertEqual(expected_line, printed_line)

        count += 1

        if count > 15:
          return

    self.assertEqual(4, count)

  def test_mirror_mirror_on_the_wall_5(self, downloader_mock, stdout_mock):
    def tutorial_example():
      from stem.descriptor.remote import DescriptorDownloader
      from stem.util import str_tools

      # provides a mapping of observed bandwidth to the relay nicknames
      def get_bw_to_relay():
        bw_to_relay = {}

        downloader = DescriptorDownloader()

        try:
          for desc in downloader.get_server_descriptors().run():
            if desc.exit_policy.is_exiting_allowed():
              bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
        except Exception as exc:
          print('Unable to retrieve the server descriptors: %s' % exc)

        return bw_to_relay

      # prints the top fifteen relays

      bw_to_relay = get_bw_to_relay()
      count = 1

      for bw_value in sorted(bw_to_relay.keys(), reverse = True):
        for nickname in bw_to_relay[bw_value]:
          print('%i. %s (%s/s)' % (count, nickname, str_tools.size_label(bw_value, 2)))
          count += 1

          if count > 15:
            return

    exit_descriptor = mocking.get_relay_server_descriptor({
      'router': 'speedyexit 149.255.97.109 9001 0 0'
    }, content = True).replace(b'reject *:*', b'accept *:*')

    exit_descriptor = mocking.sign_descriptor_content(exit_descriptor)
    exit_descriptor = RelayDescriptor(exit_descriptor)

    downloader_mock().get_server_descriptors().run.return_value = [
      exit_descriptor,
      mocking.get_relay_server_descriptor(),  # non-exit
      exit_descriptor,
      exit_descriptor,
    ]

    tutorial_example()
    self.assertEqual(MIRROR_MIRROR_OUTPUT, stdout_mock.getvalue())

 def test_published_no_time(self):
   """
   Constructs with a published entry without a time component.
   """
   
   desc_text = get_relay_server_descriptor({"published": "2012-01-01"}, content = True)
   self._expect_invalid_attr(desc_text, "published")

 def test_protocols_no_circuit_versions(self):
   """
   Constructs with a protocols line without circuit versions.
   """
   
   desc_text = get_relay_server_descriptor({"opt": "protocols Link 1 2"}, content = True)
   self._expect_invalid_attr(desc_text, "circuit_protocols")

 def test_port_newline(self):
   """
   Constructs with a newline replacing the ORPort.
   """
   
   desc_text = get_relay_server_descriptor({"router": "caerSidi 71.35.133.197 \n 0 0"}, content = True)
   self._expect_invalid_attr(desc_text, "or_port")

 def test_port_malformed(self):
   """
   Constructs with an ORPort that isn't numeric.
   """
   
   desc_text = get_relay_server_descriptor({"router": "caerSidi 71.35.133.197 900a1 0 0"}, content = True)
   self._expect_invalid_attr(desc_text, "or_port")

  def test_ntor_onion_key(self):
    """
    Checks a 'ntor-onion-key' line.
    """

    desc = get_relay_server_descriptor({'ntor-onion-key': 'Od2Sj3UXFyDjwESLXk6fhatqW9z/oBL/vAKJ+tbDqUU='})
    self.assertEqual('Od2Sj3UXFyDjwESLXk6fhatqW9z/oBL/vAKJ+tbDqUU=', desc.ntor_onion_key)

  def test_with_opt(self):
    """
    Includes an 'opt <keyword> <value>' entry.
    """

    desc = get_relay_server_descriptor({'opt': 'contact www.atagar.com/contact/'})
    self.assertEqual(b'www.atagar.com/contact/', desc.contact)

 def test_with_opt(self):
   """
   Includes an 'opt <keyword> <value>' entry.
   """
   
   desc = get_relay_server_descriptor({"opt": "contact www.atagar.com/contact/"})
   self.assertEquals("www.atagar.com/contact/", desc.contact)

  def test_unrecognized_line(self):
    """
    Includes unrecognized content in the descriptor.
    """

    desc = get_relay_server_descriptor({'pepperjack': 'is oh so tasty!'})
    self.assertEqual(['pepperjack is oh so tasty!'], desc.get_unrecognized_lines())

 def test_address_malformed(self):
   """
   Constructs with an invalid ip address.
   """
   
   desc_text = get_relay_server_descriptor({"router": "caerSidi 371.35.133.197 9001 0 0"}, content = True)
   self._expect_invalid_attr(desc_text, "address", "371.35.133.197")

 def test_invalid_attributes(self):
   """
   Attempts to make a csv with attributes that don't exist.
   """
   
   desc = get_relay_server_descriptor()
   self.assertRaises(ValueError, export_csv, desc, ('nickname', 'blarg!'))

 def test_port_too_high(self):
   """
   Constructs with an ORPort that is too large.
   """
   
   desc_text = get_relay_server_descriptor({"router": "caerSidi 71.35.133.197 900001 0 0"}, content = True)
   self._expect_invalid_attr(desc_text, "or_port", 900001)

 def test_nickname_too_long(self):
   """
   Constructs with a nickname that is an invalid length.
   """
   
   desc_text = get_relay_server_descriptor({"router": "saberrider2008ReallyLongNickname 71.35.133.197 9001 0 0"}, content = True)
   self._expect_invalid_attr(desc_text, "nickname", "saberrider2008ReallyLongNickname")

 def test_nickname_invalid_char(self):
   """
   Constructs with an invalid relay nickname.
   """
   
   desc_text = get_relay_server_descriptor({"router": "$aberrider2008 71.35.133.197 9001 0 0"}, content = True)
   self._expect_invalid_attr(desc_text, "nickname", "$aberrider2008")