On the way to [pybind11-mypy-demo]

[sizmailov]

Pybind demo module

Basics

• Functions
  • :heavy_check_mark: w/o args
  • :heavy_check_mark: anonymous args
  • :heavy_check_mark: named args
  • :heavy_check_mark: defaulted args
  • *args / **kwargs
• Classes
  • :heavy_check_mark: overloaded init
  • :heavy_check_mark: instance property ro/rw
  • :heavy_check_mark: class property ro/rw
  • :heavy_check_mark: instance attribute
  • :heavy_check_mark: class attribute

Stubgen features

Render values:

• defaulted function argument values
• "builtin-valued" attributes as is
• custom type valued attributes as comments
• pybind11-enum-valued attributes/arg default values
• module-valued class attributes

Render class/static members

• class function
• static function
• :heavy_check_mark: class property -> ClassVar

Correct order of module elements

• Sort classes in topo-alpha order (ZBase class would go before ADerived but Cat goes before Dog)

Render docstrings

• Add CLI option
• :question: Add docstring preprocessing hooks
• Strip overloads annotations

Proper imports

• Import modules as underscored aliases

Corner cases

• Skip __hash__ = None for non-hashable types
• don't render __init__ for non-constructable classes
• [conditionally] strip numpy.ndarray shape info
• [conditionally] strip std::array shape info

Robustness to bad docstrings

• [conditionally] Render C++ types in signatures as strings (arguments or/and return type)
• [conditionally] Render Invalid python expression as argument default value as strings
• [conditionally] Produce error/warnings on above

Misc things to test (unordered)

- exclude umbrella `(*args, **kwargs)` overload header from overload list - static/class functions and ro/rw properties - regular ro/rw properties - kw-only function arguments - positional-only function arguments - non-constructable types (with missing `__init__`) - numpy arrays (how to handle shape?) - don't produce import statement for nested classes - (?) exclude `__hash__ = None` line for non-hashable types that have `__eq__` - (?) test nested class argument defined in submodule - import names that not defined in module as underscored aliases - test copy/opaque pybind types (including `pybind11/stl.h` and `pybind11/stl_bind.h`) - test registered exception render - render classes in alpha-topological order (so `ZBase` class would go before `ADerived` but `Cat` goes before `Dog`) - render functions after classes - render module attributes that depend on the following classes with string types annotation (e.g. `x: 'Foo' = ...`) - fix pybind versions (e.g. replace `iterator` with `Iterator`) - skip pybind11-internal attributes - render pybind-overloaded "magic" python methods (e.g. `__add__`) - [optional] render docstrings

[YannickJadoul]

• render pybind-overloaded "magic" python methods (e.g. __add__)

One easy way of getting this is with an enum_ with py::arithmetic.

Another suggestion: something that's stl_bind.h-bound?

It's hard to think of more things out of the blue, though. It might just be worth trying out some libraries, after the basics work? Happy to help out, there :-)

[sizmailov]

Thanks for commenting. I had in mind stl types, but wrote them as "copy/opaque" types in the list, now it's explicit :smile:

[YannickJadoul]

Yeah, I just had a quick look. It's hard to get a good overview, but if some/most of these things are already working and tested, that's already an amazing amount of progress ;-)