Add py::nullptr_default_arg (intended for PyObject * arguments)

[rwgk]

Description

Enables distinguishing None and "no argument passed" / "default argument" for PyObject * arguments.

Example usage:

    m.def(
        "pyobject_nullptr_default_arg_example",
        [](PyObject *ptr) {
            if (ptr == nullptr) {
                return py::str("ptr == nullptr");
            }
            return py::repr(ptr);
        },
        py::arg("ptr") = py::nullptr_default_arg());

Notes:

• In contrast to the above, py::arg("ptr") = nullptr is equivalent to passing None.

• For any T* other than PyObject*, the equivalence of None and nullptr is fine. It's only for PyObject* that the distinction matters.

In manually written code the py::nullptr_default_arg behavior could also be achieved with overloads, but the approach as shown in the example is an easier target for a code generator (PyCLIF), and scales better in general.

Suggested changelog entry:

[rainwoodman]

Should this be made to a std::optional rather than adding a boolean? Using an optional would enforce that no value is hold when value_is_nullptr is True.

[rwgk]

I agree, but

• that would be a much more intrusive change,
• especially also because we still care (***) about C++11 compatibility. std::optional requires C++17.

(***) Because I'm still keeping pywrapcc very closely aligned with upstream pybind11 master.

Net change:

I added a comment to explain why value_is_nullptr exists (safety).

[rainwoodman]

not very clear at first glance how this handle_nullptr logic is used with the rest of the change. Could you elaborate a bit more on this? Also surprising to me is that if a py::handle can already hold a nullptr, then why do we need to add another value_is_nullptr member to the arg struct, which already hold a py::handle member?

[rwgk]

Ah, yes, the information you're looking for was only in a commit message before (pybind11 master PR used to start this work, but closed already):

pybind/pybind11@a3fd84d

I added a comment to explain.

The core idea is to cleanly exercise a critical sub-feature in isolation. It did not need production code changes, but I don't think it is explicitly exercised anywhere else already.

[rainwoodman]

Thanks!

[rainwoodman]

Which of the case does True correspond to?

[rwgk]

Good point, thanks. I made the comment more precise.

[rwgk]

Note for completeness: I meant to squash-merge but forgot to change the Merge button before clicking on it.