improve signature of ffi::PyIter_Send & add PyIterator::send

[bschoenmaeckers]

Added the missing return value of ffi::PyIter_Send and made a safe wrapper in PyIterator for convenience,

closes #4727

[davidhewitt]

Thanks very much for this! I think this looks good to me, with just a thought on documentation.

[davidhewitt]

I think it might be helpful to link users to more documentation about how this works, and/or write something like "equivalent to self.send(value). Similarly I guess PySendResult, while pretty clear from the names, might be worth having comments like "the generator yielded another value" or "the generator returned".

I say generator above... I guess this function only makes sense for generators? (As far as I know, send is always paired with the yield keyword in Python? I wonder, is there a way we can replicate the yield in Rust?)

[bschoenmaeckers]

I say generator above... I guess this function only makes sense for generators? (As far as I know, send is always paired with the yield keyword in Python? I wonder, is there a way we can replicate the yield in Rust?)

We cannot distinguish between normal python iterators and generators (because they are the same). A normal iterator just ignores the value being send.

[davidhewitt]

Also needs both fixed and added newsfragments, please.