pyproto: deprecate py_methods

[davidhewitt]

I've been thinking about #[pyproto] ergonomics for a while, prompted by questions like #1205, #1206, #1546 (comment), and confusion I often see by users on Gitter.

There are a few methods like __bytes__ which have no technical reason to be in #[pyproto], and in fact can already be implemented in #[pymethods]. (See #1205 (comment).) I think that #[pymethods] is much easier to understand and use than #[pyproto], so to make "one way" for users I propose in this PR to deprecate these #[pyproto] methods.

[kngwyu]

Thanks, good intermediate changes if we are going to refactor protocols.

[davidhewitt]

Thanks @kngwyu for the feedback. I've made some changes to the documentation based on your suggestions, it looks much better now!

[ravenexp]

I'd like to bring to your attention that the __bool__() method is currently included in the PyObjectProtocol trait, but the corresponding C API slot nb_bool is a part of the PyNumberMethods struct, which roughly corresponds to the PyNumberProtocol trait. I don't know why it is done this way, but you may also consider deprecating __bool__() from PyObjectProtocol and reintroducing it into PyNumberProtocol for consistency.

[davidhewitt]

Given that the current design decision in #1206 is that we might try completely replacing #[pyproto] with #[pymethods] for 0.15, I'm not going to bother moving __bool__ for now.

If we can't make that change work I agree there's a couple of methods like this which should be shuffled around.

[kngwyu]

I don't know why it is done this way,

https://docs.python.org/3/reference/datamodel.html#object.bool

Though I don't like this inconsistency, maybe this is the reason.

[ravenexp]

Given that the current design decision in #1206 is that we might try completely replacing #[pyproto] with #[pymethods] for 0.15 ...

That would be sweet. I'm really looking forward to it.