add #[pyo3(signature = (...))] attribute

[davidhewitt]

This is an implementation of the proposal in #2193 to add a new #[pyo3(signature = (...))] attribute to specify function arguments.

This PR also deprecates the old way of setting function argument signatures.

Compared to #[pyfunction(...)] / #[args(...)]:

• It is more consistent: always signature = (...) compared to different forms for #[pyfunction] and #[pymethods].
• It is more strictly validated: all arguments must appear in the signature in the correct order.
• It has more Pythonic syntax, e.g.:
  • *args instead of args = "*".
  • Default arguments don't need additional string quoting - signature(name = "David") instead of args(name = "\"David\"")

The possible argument I can see which could be made against this is the increased verbosity from requiring all arguments to appear. I argue this is a plus to ensure correctness. It would be easy to relax this in future if feedback frequently requested it.

Future extensions:

• I'd like this to also generate a text_signature automatically
• I'd like this to eventually support Python type annotation syntax e.g. signature = (a: int = 5, b: str = "hello"), although the mechanism how the type annotations would be exposed is still unclear.

To review this, I suggest looking at the guide and tests, and if you're satisfied with that give the implementation a scan.

[adamreichold]

The issue number of the news fragments (2302) does not match the PR issue number (2702) which is why that CI job fails.

[davidhewitt]

Thanks for the review - addressed both comments.

[birkenfeld]

Perfect, the new syntax is so much nicer!