pybind/pybind11

Unkown objects in docstring function signatures

Open

#1,585 opened on Nov 1, 2018

View on GitHub
 (3 comments) (0 reactions) (0 assignees)C++ (2,005 forks)batch import
enhancementhelp wanted

Repository metrics

Stars
 (14,677 stars)
PR merge metrics
 (Avg merge 5d 2h) (10 merged PRs in 30d)

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

Research direction
Investigate how pybind11's docstring generation maps C++ types like py::iterator and py::buffer to Python type annotations. Check if stubgen can be improved to output Iterator[ElementType] and bytearray instead of generic names.
Tech stack
cpppython
Domain
backend
Issue type
Bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Pythonpybind11
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75