fix: Render py::function as Callable

[sizmailov]

Description

Render py::function as Callable

Suggested changelog entry:

Render ``py::function`` as ``Callable`` in docstring

I'm not sure I've put the test into right place. pre-commit forced the reformatting of other lines.

[henryiii]

Seems fine. Technically it's Callable[..., Any], but we don't do the others that way, so this is better.

[rwgk]

Thanks!
Interesting oversight.
I'll go ahead merge this, but question for completeness: did you look systematically if there are other similar oversights? (Maybe not so easy?)

[sizmailov]

Here is what I already have in pybind11-stubgen that is not yet fixed here (omitting typing. prefix)

py::object-> Any
py::handle -> Any
py::sequence -> Sequence
py::buffer -> Buffer

I'll take another look at pybind source and get back to you if I find anything else.

[sizmailov]

@rwgk I ran through the sources one more time. The above four are the only ones missing casters.

IMO there are no downsides in capitalizing py::sequence and py::buffer implying the correspondence to typing.* types like in other places across the library.

The decision on py::object is a tricky one.
In the context of pybind we usually mean Any when we write py::object argument/return type. We don't mean to return exactly instances of python's object. So my personal preference would be to change py::object render to Any to better reflect the semantics of binding code. Here is a mypy's take on the "Any vs object":
https://mypy.readthedocs.io/en/stable/dynamic_typing.html#any-vs-object

py::handle usually should not appear in the docstrings, but sometimes it does:

pybind11/include/pybind11/pybind11.h

Line 2013 in db412e6

[](handle arg) -> str {

At least py::handle should be rendered the same way as py::object.

I've submitted a PR for 3/4 of the above, except for py::object. I think it deserves a separate issue for discussion.

[rwgk]

I might not get to this for a couple days, just quick, on Any: Originally PyCLIF was mapping PyObject to object, but it really didn't do any good for anything, so we changed it to map to Any and everyone has been happily living ever after. (We are using pytype a lot at Google.) So from my end we don't need to discuss, Any is the way to go.

…

On Thu, Aug 31, 2023 at 17:56 Sergei Izmailov ***@***.***> wrote: @rwgk <https://github.com/rwgk> I ran through the sources one more time. The above four are the only ones missing casters. IMO there are no downsides in capitalizing py::sequence and py::buffer implying the correspondence to typing.* types like in other places across the library. The decision on py::object is a tricky one. In the context of pybind we usually mean Any when we write py::object argument/return type. We don't mean to return exactly instances of python's object. So my personal preference would be to change py::object render to Any to better reflect the semantics of binding code. Here is a mypy's take on the "Any vs object": https://mypy.readthedocs.io/en/stable/dynamic_typing.html#any-vs-object py::handle usually should not appear in the docstrings, but sometimes it does: https://github.com/pybind/pybind11/blob/db412e6e8648a5687d73ef4cf28738d1e7f0e53f/include/pybind11/pybind11.h#L2013 At least py::handle should be rendered the same way as py::object. I've submitted a PR for 3/4 of the above, except for py::object. I think it deserves a separate issue for discussion. — Reply to this email directly, view it on GitHub <#4829 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFUZAHITHPFXDGC7R5BQVDXYEXD7ANCNFSM6AAAAAA4FIT3VU> . You are receiving this because you were mentioned.Message ID: ***@***.***>