Skeletion for descriptor reader

Initial skeleton for a class to read descriptor data, not including most of the
functional bits. This will be similar to the metrics-lib DescriptorReader
class, but with a slightly different API and the ability to handle tarball
archives.
Revising implementation details for processed files

Like metrics-lib, the DescriptorReader will track the last modified timestamp
for the descriptor files we have processed. Revising the pydocs for it and
adding untested functions to save and load. Next step is to add integ tests.
Adding mocking support for builtin functions

Builtin functions, like open, lack the __dict__ attribute among other things
which prevents the current mocking scheme from working. Adding workarounds so
we can accomidate them.

This also adds a function for supporting the 'with' keyword on mock objects.
Typo in import statement

Basic syntax issue (import typo)
Unit tests for the load_processed_files() function

Unit tests for stem.descriptor.reader's load_processed_files() function. This
mocks the open call to simulate file reads and exercise a variety of good and
malformed contents. This does not yet test for use cases where the file doesn't
exists or fails to be read due to permissions, but those will be integ tests.
Integration tests for load_processed_files()

Basic set of integ tests exercising file reading when successful, non-existant,
or lacking permission.
Integration tests for save_processed_files()

Basic integ tests for the save function, checking that we can load persisted
files and that it has some basic input validation.
Rewriting reader documentation

Moving all of the examples and substantial documentation up into the header,
and minorly revising how I intend for the module to be used. Not all of the
methods in the header have been added yet.
Integ test for basic usage example

The header documentation contains two examples - the equivilant to 'hello
world' with this class and an example of making use of the high water mark the
DescriptorReader tracks. This adds an integ test for the first.

At present this integ test dies in a fiery... well, fire. This is because the
DescriptorReader isn't yet implemented. That's next...
Implementation of DescriptorReader concurrency

After much hair pulling figured out a relatively producer/consumer simple model
for this class. It should be trivial to add stop() later, but making this
re-runable would greatly complicate the class and probably isn't worth it.

This isn't yet working, but this is a decent breaking point.
Finishing basic DescriptorReader implementation

Fixing the minor issue that was preventing the DescriptorReader from working
and making its first integration test do automated verification, rather than
needing a manual check.
Fix and test for DescriptorReader stop() method

Adding an integraion test and some fixes for the stop() method of the
DescriptorReader class.
Inverting the 'finished_reading' flag

Code is more readable when flags say what we're doing rather than what we're
*not* doing.
Tidying up DescriptorReader attributes

Bit of refactoring to limit the scope or improve readability of attributes.
Only provide absolute paths with get_processed_files()

The DescriptorReader's targets can be relative paths, and this is fine.
However, the load and save functions for processed_files expect absolute paths
so making get_processed_files() expand relative paths.

I'm on the fencepost about if we should do this or make the load/save functions
accept relative paths. Going with this until someone produces a use case where
this makes them sad.
Integ test for get_processed_files()

Integration test for the get_processed_files() method of the DescriptorReader
class. This and the test_basic_example tests are intermittendly failing right
now which indicates a concurrency issue - though this test itself has passed
and should be fine.
Running test_basic_example() multiple times

Rerunning the test_basic_example() test fifteen times to make it more sensetive
to concurrency issues. It now fails consistently! (... yay?)
Fixing sinister concurrency issue

Replacing the _is_reading event flag with a 'FINISHED' entry in the
_unreturned_descriptors queue. This is because python's queues stupidly have no
notion of flushing, so there's no method for me to make a reliable check of 'if
the reading thread is finished AND the queue is empty'. I may have called
'put'. I may have a proveably not-empty queue. But can I make that check work?
Nooooo. That is... frustrating. >:(
Integ test for the set_processed_files() method

Testing that the DescriptorReader's set_processed_files() method properly
causes us to skip priorly read files.
Implementing skip listeners and exception hierarchy

Notifying the skip listeners of files that we skip, and adding an exception
hierchy for the reasons why. Also a little minor refactoring to move the file
handlers out of the run() method.