Add an IBodyProducer which produces bytes from a file-like object

[exarkun]

#886 introduces an HTTP client API along with a new interface, IBodyProducer, for providing request bodies in a streaming manner. This interface isn't quite the same as IProducer, so existing producers don't quite work with it.

For convenience, we should provide an implementation of this interface based on file-like objects (along the lines of twisted.protocols.basic.FileSender). This will be useful both for the obvious reason (sending files as request bodies), as well as as an example of how to implement these, and will also be usable with StringIO instances to send data constructed in memory (eg simple form posts).

[exarkun]

(In [32067]) Branching to 'filebodyproducer-4017'

[exarkun]

I took a crack at this because I thought it would be quick and easy. Oh well, I've certainly done worse than none out of two before.

Please find FileBodyProducer, tests, docs, and an example in the linked branch. Here are the  build results.

[exarkun]

One possible change that should be made to this code is that the producer should take responsibility for closing the file after it finishes reading from it or if stopProducing is called.

[therve]

• Instead of keeping a reference to the the cooperator object, you may only keep one to the cooperate method. It would prevent the need of that comment about the task module.
• I don't have a really strong feeling for closing the file or not, but whatever you choose, it should be mentioned in the documentation (both the docstring and the howto).

Please merge!

[exarkun]

(In [32154]) Address review feedback, plus

• add docstrings to some test helpers
• use the bound cooperate method instead of a Cooperator instance/cooperator module
• close the input file when the FileBodyProducer is done with it (and update docs)

refs #4017

[exarkun]

(In [32155]) Branching to 'filebodyproducer-4017-2'

[exarkun]

(In [32157]) Merge filebodyproducer-4017-2

Author: exarkun Reviewer: therve Fixes: #4017

Add twisted.web.client.FileBodyProducer for use with Agent to specify request bodies based on file-like objects.