Skipping non-regular files when the reader crawls

When the reader encounters block devices it can get stuck, causing the integ
test for stop() to fail. Caught by nickm.
Correcting incorrect variable in logging

Issue caught by Karsten.
Targeting reader test at /usr rather than root dir

I've been running the reader's test_stop() integ test by running over the root
direcctory because I simply needed something 'big' to keep the test occupied
for a second or two. This turned out to inadvertantly fuzz the reader which is
sorta a good thing since it discovered that block devices and encrypted
partitions can be slow to read, causing stop() to block for a bit.

However, we don't want to run over people's private stuff, and slow reads on
encrypted partitions probably isn't a problem that we want to solve anyway, so
running over '/usr' instead.
Descriptor typo corrections

Fixes by Karsten
Implement Safecookie support in Stem
Expanding capabilites of tor version comparison

Requirements were simple tor versions which was fine for simple 'greater than'
comparisons, but broke down for slightly more complicated requirements such
as 'at least version X in the 0.2.2 series or version Y in the 0.2.3'.

Introducing a 'meets_requirements' that will allow us to compare with arbitrary
rules. For now we're just comparing with Versions or VersionRequirements, but
could be expanded later if we need to.
Revisions to change for SAFECOOKIE support

The SAFECOOKIE change is pretty big so, unsurprisingly, it has needed quite a
few changes. Many are stylistic nitpicks, though this also includes several
more substantial changes including...

* The SAFECOOKIE AuthMethod was added, but the ProtocolInfoResponse's
  _parse_message didn't recognize it causing it to still be listed as an
  unknown authentication method. Also, we called send/recv on the controller in
  authenticate_safecookie() at one point rather than using _msg, causing it to
  break when called with a Controller. I'm a tad puzzled by these... were the
  integ tests ever ran with the RUN_ALL target?

* Slightly reducing the exhaustiveness of the authentication unit test in the
  name of runtime. The test exercises each combination of exceptions for each
  exception type which led to a combination explosion when we added SAFECOOKIE
  to the mix (raising the unit testing runtime from around two to twelve
  seconds). Made some minor tweaks to bring the runtime back down without
  really impacting what we test much.

* Changing the CookieAuthFailed attribute that indicates if it arose from
  SAFECOOKIE or COOKIE auth to be a boolean. Providing the AuthMethod would
  only make sense if we added even more variants of cookie authentication
  (possible, but not anywhere on the radar).

* Added AUTH_SAFECOOKIE to 'stem.version.Requirement'. This turned out to need
  some fairly big changes to how we check for version requirements (see prior
  commit).

* Few issues with the integ tests, including calling 'remove' on a tuple and a
  bug where it would accidently remove all auth methods from the protocolinfo
  response before calling authenticate().

* We only removed AuthMethod.COOKIE form a protocolinfo response's auth_methods
  when the cookie file was missing.

* Few unused imports and lots 'o whitespace issues. I should probably improve
  the whitespace checker a bit.

* Toned down the 'warning, we're under attack!' errors. The whole point of
  safecookie auth is simply to avoid providing the raw cookie contents to the
  thing we think is tor. Nothing about this handshake should be consitered to
  be an 'attack', nonce mismatches are more likely to just indicate some sort
  of bug.

* No tor reply can be empty (if it was empty then we... well, wouldn't have
  read anything from the socket). Hence the ControlMessage can't be empty.
  It'll be a pita to check for this in every reply, so checking that as part of
  the ControlMessage constructor.

* Added helper function to check if a value is hex digits. We do this a lot, so
  no need to repeat the regex everywhere.

* Looks like we could misidentify IncorrectCookieValue verses
  CookieAuthRejected exceptions when we had both cookie and password auth.

* I was a bit confused about what the AUTHCHALLENGE unit tests for an invalid
  response were attempting to exercise, so replaced with a shorter and simpler
  test for missing components.
Separating relay and bridge extra-info descriptors

Creating separate classes for relay and bridge extra-info descriptors. At
present they're identical to their common parent (ExtraInfoDescriptor), adding
their differences next.
Making relay-signature field only apply to relay extra-info

Parsing and handling the relay-signature field as only an attribute of
extra-info descriptors for relays.
Integ test with bridge extra-info content

Adding a bridge extra-info descriptor from metrics. I'm currently being a bit
lazy and only parsing some of the mapping fields. The rest should be covered
by unit tests, so I'll only add the rest if this ends up bitting us.
Adding extra-info digest() method

Adding digest() methods for extra-info descriptors. I'm also swapping the
server descriptor counterparts to provide a hex encoded digest as per Karsten's
suggestion.
Converting test.* contents to reStructuredText

The test contents aren't currently included in the stem documentation, since
they aren't generally of interest to users. However, might as well do its
documentation as reStructuredText for consistency's sake.

I'll probably include just the framework utilities with our documenntation
later to help people hacking on stem.
Adding future 'with' import and checking for it

Stem aims for python 2.5 compatability, but in that version the 'with' keyword
wasn't available by default and would only function with a 'future' import.
This has the possability of being a continuing pain in our ass so adding this
as a check to the check_whitespace module. Admittedly this isn't a whitespace
issue, but that module is just so damn conveninent for lintian style issues
too...

While doing this I discovered that we aren't running the checker over the stem
module (just the tests, it seems), so something else to fix...
Whitespace checker wasn't checking non-tests

The whitespace checker was being ran with its default target, which is the
directory of that file (in this case, test). Explicitely running over
everything else, and fixing the issues that it found.
Added convenient methods in BaseController and Controller.
Move all convenience functions to Controller class, and minor changes on them
Added convenient methods in BaseController and Controller.
Move all convenience functions to Controller class, and minor changes on them
Added integ tests for convenience methods.
Fixed indentation errors.