-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Compose literals for argument values in docstring #2668
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
123ebfc
to
97f3ad5
Compare
97f3ad5
to
26c9dc7
Compare
Seeking review @henryiii |
It's interesting to see this, but I'm afraid it has practically no chance of getting merged. A few reasons:
Do you have a specification/example/... of what e.g. mypy or Sphinx expect? |
Thank you for the detailed explanation @YannickJadoul!
Perfectly understandable, especially considering I offered no configuration to the modifications I made.
Quoting the docs:
There's an escape hatch in there. The method does not require you to generate a valid Python literal that would evaluate back to the same value. Choosing
I can see why you're suggesting this customization point as an alternative to my blanket solution suppressing user-defined
I admittedly don't. I tried
I would appreciate that. Do you see any way forward for this PR? |
It occurred to me that the only reason this PR is as large as it is, is because I'm somewhat insistent on handling bound enums. If I gave that up, the minimum solution to getting syntactically valid docstrings might be as simple as string-replacing anything in the result of |
@sizmailov Both #2243 and #2244 strike me as necessary additions to any undertakings of generating fully valid docstrings. I've only skimmed #2244, but do you think that the same functionality is implementable at your suggested customization point? |
Sorry, I gave a short glance at your PR without thinking too much and left non-sense (already deleted) comment. I didn't realize that at the moment of docstring construction we deal with python objects which not necessarily have bare C++ counterpart, which disables one from introducing template-based customization point.
namespace pybind11 {
template<>
py::arg_v arg::operator=(int &&value) const {
return {std::move(*this), std::forward<int>(value), "my_custom_int_repr"};
}
}
PYBIND11_EMBEDDED_MODULE(example, m) {
m.def("add", [](int a, int b) { return a + b; }, py::arg("a"), py::arg("b") = 1);
// renders `add(a: int, b: int = my_custom_int_repr) -> int`
} This seems to be enough to customize behavior for bound C++ types and python builtin types (using |
I'm going to close this since the customization point suggested by @sizmailov is suitable for my use case. |
Description
Closes #2667 by addition of a
compose_literal
function that attempts to handle the generation of valid Python literals for default arguments in docstrings. Can handle built-in data structure nesting by recursion. Generates literals for bound enums, replaces non-enum bound class instances with an ellipsis.Suggested changelog entry: