Add PyAnyMethods.try_iter and deprecate .iter

[LilyFoote]

Fixes #4550.

[davidhewitt]

Thanks, sounds like try_iter is the preferred choice. While we're here, perhaps let's add some detail to the documentation to make it more clear that you need to handle the result before trying to iterate? (An example might be nice.)

[LilyFoote]

I've added an example, but I'm open to a better one.

[mejrs]

I've added an example, but I'm open to a better one.

I nominate:

fn does_it_have_the_answer(obj: &Bound<'_, PyAny>) -> bool {
    if obj.extract() == Some(42_u8) {
        true
    } else if obj.extract() == Some("42") {
        true
    } else if let Ok(iter) = obj.try_iter() {
        for item in iter {
            if let Ok(item) = item {
                if does_it_have_the_answer(item) {
                    return true;
                }
            }
        }
    }
    false
}

(maybe add some comments to explain what we're doing)

[Icxolu]

For my taste that does have a bit too much complexity that is not really relevant for the fallibility of the iterator. I would prefer something a bit simpler, but I don't have a good suggestion in mind right now... At least I think the try_iter call should be at the start of the example and introducing recursion does not feel particularly necessary.

[davidhewitt]

I think as we're a bit stuck of ideas for the perfect example, let's just proceed to merge. I'd prefer see this get into 0.23 with a slightly subpar example and refine another time. Thanks all!