RFC: deprecate or document the automatic `Some`-wrapping of default function arguments

[davidhewitt]

PyO3 currently allows this code:

#[pyfunction(signature = (x=1))]
fn foo(x: Option<i32>) { }

The default 1 for x is automatically wrapped in Some inside PyO3's argument parsing machinery.

(This default will be used if x is not passed a value at all from Python; if explicit None is passed, the Rust function will be called with None for x accordingly.)

This functionality is not documented in the guide. It's cute, but requiring users to write Some(1) instead of 1 is not that burdensome. I am somewhat tempted to deprecate this instead of document.

A counter-argument is that we could consider generalising this special case to instead apply to all types, perhaps by allowing an Into coercion. This would allow, for example, &str defaults to be automatically cast as String:

// Not currently accepted, but maybe it could be?
#[pyfunction(signature = (x="bar"))]
fn foo(x: String) { }

... I think despite this possibility, I would still prefer requiring the default value in the signature to exactly match the target argument type. This would allow us to simplify the macros and applies no implicit casting; feels like more idomatic Rust.

[Icxolu]

I'd be in favor of deprecating this and require the type in the signature to match the argument type. I tend to think that this is too magical and makes it harder to reason about what's going on.

[davidhewitt]

One possible counterpoint is that at the moment the default value 1 is rendered properly in the __text_signature__, but Some(1) is not (will be rendered as x=...).

The solution there (which we probably want eventually anyway) is to have some kind of way to format Python repr (at compile time), maybe inspired by const_format.