pybind / pybind/pybind11

Unkown objects in docstring function signatures

Open
#1,585 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement help wanted
Dominant language
C++
Stars
18k
Forks
2.3k
Avg merge
5d 17h
Merged PRs (30d)
10

Description

I try to rely on mypy's stubgen (with recent improvements) to generate *.pyi files from Python classes generated by pybind11. It's almost perfect, though there are just a few things that needs a bit of polishing:

  • iterator - when creating method with .def("some_func", [](some_type const &a) {return py::make_iterator(a.cbegin<elem_type>(), a.cend<elem_type>());}; then docstring is some_func() -> iterator. Type should be either Iterator (from typing) or even better, if it would be Iterator[elem_type]
  • buffer - when binding method with signature add_buffer(py::buffer const &buf) the docstring is add_buffer(buffer: buffer). Is this buffer in Python2 and bytearray in Python3? Should stubgen alias bytearray as buffer in such cases?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the mypy stubgen behavior described for pybind11-generated Python classes, comparing the iterator return signature and py::buffer parameter examples. No repository file or test is named, so first locate the signature-generation code and its tests. Done means the generated docstrings use appropriate iterator and buffer types, with regression coverage for both cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
api, developer-experience
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.