Parsing descriptor files and annotations

Completely untested change to finish the implementation of server descriptors.
This parses a cached descriptor file into individual descriptors and
annotations.

Next comes unit and integ tests to start exercising it in an automated way.
Pylint corrections for server descriptor

Corrections from running pylint over the untested server descriptor class (all
basic problems that would keep it from running).
Using server descriptor when parsing

Parsing server descriptors via the new server descriptor class. This breaks the
tests and will need quite a bit of work. :)
Merging descriptor.py with module init

The syntax for using the descriptor module was stupid ("import
stem.descriptor.descriptor"). Using the json module as an example for using
__init__.py for base functions. Common ones will live in 'stem.descritor' but
the contents, like 'stem.descriptor.reader', are also accessable.

This is similar to how the os module works, though in that case they're using a
lot more python magic to also support multiple operating systems.
Cleaning up minor import issues
Resolving circular dependency with server_descriptor

... damn this was a pita to debug. A long explanation of the issue is:
http://stackoverflow.com/questions/8991520/python-conditional-module-object-has-no-attribute-error- with-personal-package

Short story is that the stem.descriptor module imported server_descriptor prior
to being fully initialized which caused a server_descriptor use of
stem.descriptor.Descriptor to fail.

The confusing was that it was actually reporting failure in using
"stem.descriptor" (the module itself) which made no sense because it was listed
within sys.modules. It turns out that the python importer uses module
attributes rather than sys.modules mappings to resolve statements (ie, it was
doing getattr(stem, "descriptor")). However, a module's added as an attribute
of its parent when its *finished* importing.

This fixes the unit tests, but integ tests are still getting stuck when they
use the new server_descriptor parsing.
Server descriptor parsing fixes

Resolving the variety of issues that were breaking the integ tests. We still
don't have any tests to actually verify the server descriptor parsing, but
at least we're now exercising it on some real data... and not dieing in a fire!
Progress!
Cleaning up prior descriptor implementations

Adding header pydocs and made a variety of small fixes and naming improvements.
Integration test for reading non-descriptor files

Integ test for reading non-descriptor plaintext and binary data.
Server descriptor test for metrics content

Test for parsing a single server descriptor and checking its content. This
includes a few fixes and improvements for the ServerDescriptorV2 class, the
most intersting of which is that declaring instance variables prior to init
makes a single reference. Hence all server descriptors were using the same exit
policy. Oops. :)
Allowing for extra args on lines with multiple

Well, crap. I've been developing against the version 2 spec on the assumption
that was both the majority use case and what my test instance was running.
However, that's evidently pretty ancient and I've been running against version
3 all along.

First change I'm spotting in the spec is that lines with multiple arguments
should ignore extras so doing that.
Missing version 3 attributes

Adding the server descriptor attributes that are new as of version 3. The only
attributes that I'm still excluding are eventdns (because it's dead) and
read/write-history (since they're extra-info now).
Dropping attribute for block types

We already have enough attributes, and parsing out the armor type is redundant
since it's within the armor itself. Besides, it's not likely to change and I
doubt callers will ever care about it.
Integ test to validate our cached descriptor file

Parsing all of the descriptors in our cached descriptors file to see if it has
anything that'll make us choke (and by extension indicate either a tor or stem
bug).

This is an important yet lengthy test, taking around four second. Targets do
not effect this test so only running it once for the test run.
Including deprecated server descriptor attributes

I have mixed feelings about cluttering the server descriptor with dead fields,
but since we're already this close to being perfectly spec conformant we might
as well include this last bit. Adding the fields but logging an info level
warning if we see it, and checking in our cached descriptor that they do not
exist.
Skipping integ test on cached descriptors if not available

The first time we run our integration tests our data directory is not yet fully
populated. This causes our test that runs over the cached descriptor file to
fail. Adding a check that the cached descriptors exist before running it.
Miswired 'ONLINE' and 'RELATIVE' targets

The test runner still used the 'test.' prefixed configuration keys rather than
'integ.'. This caused the 'ONLINE' and 'RELATIVE' testing targets to be
ignored.
Skipping auth message check when cookie missing

When we first run our tests we don't have an authentication cookie unless we've
run with the RUN_COOKIE target. We have special handling for this, but it did
not account for running with an open connection (the default) in which case
we'd encounter a second exception while trying to check the failure message.
Unit tests for server descriptor parsing

Borrowing heavily from Karsten's metrics-lib unit tests [1], plus a few of our
own. This doesn't include everything, some are covered by util tests and others
are effectively covered by parsing metrics and cached-descriptor files. That
said, I wouldn't be against including more - my fingers are just getting
numb...

While looking through those tests I discovered these deltas...

* When parsing the descriptor he validated that we had the correct first and
  last entry but we didn't. This was a bug, now fixed.

* He checks that the 'protocols' line only contains numberic protocols but we
  accept any space separated content. The spec doesn't specifify what the
  protocols can be so I'm leaving this alone.

* He had checks that a 'published' line with a year of '3012' or '1912' would
  fail. I can understand having a sanity check but the spec does not say that
  those dates are invalid so again leaving it as-is.

* Metrics lib has validation for the exit policy but we don't. This is because
  we haven't yet implemented an ExitPolicy class - gsathya is currently working
  on that in...

  https://trac.torproject.org/projects/tor/ticket/5454

* Karsten is parsing and validating read/write-history lines. We, on the other
  hand, log an INFO level warning when these appear and assert in the integ
  tests that they (along with 'eventdns') do not exist in our cached-descriptor
  file. My understanding is that these are deprecated entries and should not
  appear outside of the extra-info descriptors. Maybe I'm misunderstanding
  something here...

On everything else we either match or are maybe slightly more strict about only
allowing content conforming to the spec.

[1] https://gitweb.torproject.org/metrics-lib.git/blob/HEAD:/test/org/torproject/descriptor/impl/ServerDescriptorImplTest.java
Fixing reader's pydoc example