Add py::object casting example to embedding docs

[kohr-h]

Some examples for auto-casting from py::object to subtypes. These were the simplest I could come up with; happy to take suggestions.

Closes: #1310

[bstaletic]

Calling py::module::import returns a py::module.

[kohr-h]

That's why I wrote "typically" 😉
But maybe that's not true either. Is it?

[EricCousineau-TRI]

It is true, at least from my reading:

pybind11/include/pybind11/pybind11.h

Line 914 in 37f845a

static module import(const char *name) {

I think the "typically" can be dropped, because in C++, it is py::module (the C++ type itself).

[YannickJadoul]

Note: #2349 will probably turn this into an error if it's nót the type you say it is (but doing that now is already wrong and potentially dangerous). But maybe we should make this more clear?

Also, I'm not sure this should be added to the embedding-specific part. This can also be useful for extension modules, so I'd suggest adding it to https://pybind11.readthedocs.io/en/stable/advanced/pycpp/object.html ? (Not sure if that's the perfect place either, though.)

[kohr-h]

Note: #2349 will probably turn this into an error if it's nót the type you say it is (but doing that now is already wrong and potentially dangerous). But maybe we should make this more clear?

What do you mean by "this" (... into an error)? The code in the examples?
What's your suggestion for this PR, adding a note on using the correct type on the LHS, or auto if we don't care?

Also, I'm not sure this should be added to the embedding-specific part. This can also be useful for extension modules, so I'd suggest adding it to https://pybind11.readthedocs.io/en/stable/advanced/pycpp/object.html ? (Not sure if that's the perfect place either, though.)

Okay sure, would that be under "Casting back and forth", as implicit cast without calling obj.cast()?

[YannickJadoul]

What do you mean by "this" (... into an error)? The code in the examples?
What's your suggestion for this PR, adding a note on using the correct type on the LHS, or auto if we don't care?

No, those should be fine, actually. But this kind of approach will fail if the type is not the expected type (i.e., if an attribute is a list and you're assigning it to a dict). Currently, it might not fail immediately but maybe later (e.g. when setting with d[...] = ...;), but after #2349, it should fail immediately (if it gets merged, ofc).

For this PR, we might want to make clear that for e.g. py::str curdir_abs = path.attr("abspath")(path.attr("curdir"));, you need to be sure that curdir_abs is a str? Or do you think that's implicit?

Okay sure, would that be under "Casting back and forth", as implicit cast without calling obj.cast()?

Hmmm, maybe, but it would make that (now very succinct) section very long. What do you think about adding another section to the bottom?
I'm also fine with putting it somewhere else, if you can find something better. But I think this is more widely applicable than just for embedding :-)

[kohr-h]

What do you mean by "this" (... into an error)? The code in the examples?
What's your suggestion for this PR, adding a note on using the correct type on the LHS, or auto if we don't care?

No, those should be fine, actually. But this kind of approach will fail if the type is not the expected type (i.e., if an attribute is a list and you're assigning it to a dict). Currently, it might not fail immediately but maybe later (e.g. when setting with d[...] = ...;), but after #2349, it should fail immediately (if it gets merged, ofc).

For this PR, we might want to make clear that for e.g. py::str curdir_abs = path.attr("abspath")(path.attr("curdir"));, you need to be sure that curdir_abs is a str? Or do you think that's implicit?

Alright, got ya. I was actually assuming that the cast would fail early, but if that's not the case at the moment, a warning makes sense. If PR #2349 is likely to land, I will add a note that casting to the wrong type will lead to downstream errors, and later on to immediate cast errors.

Hmmm, maybe, but it would make that (now very succinct) section very long. What do you think about adding another section to the bottom?

Okay, maybe "Implicit casting" or something? I would put it right below the "Casting back and forth".

I'm also fine with putting it somewhere else, if you can find something better. But I think this is more widely applicable than just for embedding :-)

Yes I agree, embedding is only where I stumbled on it :-). I'll see where it fits best, but I suspect it will be somewhere under "Python types".

[kohr-h]

I've moved the stuff over to object.rst. Please see if the formulations make sense, I'm not too firm with C++ terminology.

Also a question: how should I use things like py::object in the documentation to make sure that a link to the API doc is created? I went for :class:`object` now, but it would be nicer to write something like `py::object` where the link is correctly generated nonetheless. Any ideas?
In other places of the doc, this isn't handled consistently either. Some links are dead, some are just code snippets (double backtick).

[YannickJadoul]

Starts looking good to me! :-)

Also a question: how should I use things like py::object in the documentation to make sure that a link to the API doc is created? I went for :class:object now, but it would be nicer to write something like py::object where the link is correctly generated nonetheless. Any ideas?
In other places of the doc, this isn't handled consistently either. Some links are dead, some are just code snippets (double backtick).

As you say: it's not handled consistently. But it's nice to have this link there, so whichever works best with respect to that; :class:`object` then, probably? (Just `object` doesn't work?)

Also, you could report an issue on this, if there's broken links. It won't be at the top of the list of things to do, but it's useful to know!

[kohr-h]

As you say: it's not handled consistently. But it's nice to have this link there, so whichever works best with respect to that; :class:object then, probably? (Just object doesn't work?)

I suppose it would. Sphinx would probably do a best guess, starting from the primary cpp domain. May depend on whether :any: domain is activated in the config, though.

Also, you could report an issue on this, if there's broken links. It won't be at the top of the list of things to do, but it's useful to know!

It seems like only a few links actually work, so an issue would cover the majority of documentation 😅

[YannickJadoul]

Great, thanks! :-)

[YannickJadoul]

Thanks a lot, @kohr-h! Looks good to me :-)

[YannickJadoul]

@bstaletic, @henryiii, @EricCousineau-TRI: I think you might all be interested in this? If so, a quick look would be appreciated, and then this could go in soon :-)

[EricCousineau-TRI]

Looks great!

FWIW I typically try to minimize how much Python logic I write using pybind11s interface API.

If I find myself writing more than a few if statements, more than say 15 lines, or with more complex semantics, I try to pass it directly to Python code.

Example from our codebase:
https://github.com/RobotLocomotion/drake/blob/8581223802b7790504529b9d66f1f1aab6eaaee9/bindings/pydrake/pydrake_pybind.h#L134-L139

[henryiii]

Thanks!