Improve input/output consistency of encoders & decoders

[charlie-dufort]

• ChunkedEncoder takes either a Collection or an Iterator of frames, and returns a Collection of bytes.
• ChunkedDecoder can only take a Collection of bytes, and returns a Collection of frames.
• IterativeDecoder can only take a Collection of bytes, and returns a Iterator of frames.

I suggest we add a little more consistency between the type of inputs and outputs:

• ChunkedEncoder would take either a Collection or an Iterator of frames, and would return either a Collection or an Iterator of bytes, depending on the input type.
• ChunkedDecoder would take either a Collection or an Iterator of bytes, and would return either a Collection or an Iterator of frames, depending on the input type.
• IterativeDecoder would take either a Collection or an Iterator bytes, and would return either an Iterator of frames, or an Iterator of iterators of frames, depending on the input type.

Implementation and documentation update should take about 4 hrs

[thorwhalen]

As far as consistency, for sure. To make it easier to analyze, @charlie-dufort, could you copy paste the signatures of the objects in question, and perhaps a link to their code?

I would usually suggest a decorator to do this input and output job, separating that concern. Yet theses codecs will usually know a lot of performance pressure (for example, encoding or decoding live multi-channel streams), so efficiency counts, and probably better in this case we do it in-line.

[charlie-dufort]

@thorwhalen Here's the link to the module at the top of which you can find the types and signatures of the objects used in recode. They are not 100% accurate though..

I made a pull request in which I made the (in-line) modifications I mentioned in my first message. Please review, and if the changes are ok with you, I'll update the tests and documentation before merging.

There are still a few things that could be made more consistent. I even considered changing the conceptual design a bit and rewriting the module completely without classes. But I eventually refrained :)

Here are the types and signature I propose in the PR:

• Decoded data

Sample = Union[int, float]
Frame = Union[Sample, Collection[Sample]]
Frames = Union[Sequence[Frame], Iterator[Frame]]

• Encoded data

Chunk = ByteString
Chunks = Union[ByteString, Iterator[ByteString]]

• Low-level, internal codec

FrameToChunk = Callable[[Frame], Chunk]
ChunkToFrame = Callable[[Chunk], Frame]
IterChunkToFrame = Callable[[Chunk], Iterator[Frame]]

• High-level, user-facing codec

Encoder = Callable[[Frames], Chunks]
Decoder = Callable[[Chunks], Frames]