Skip to content

Commit fe9f906

Browse files
jfhsjfhs
committed
Add support for pybind11 enum docstrings
1 parent cf58aa6 commit fe9f906

File tree

11 files changed

+132
-6
lines changed
  • pybind11_stubgen
  • stubs/kit-stubs
  • tests
    • py-demo/bindings/src/modules
    • stubs
      • python-3.12
        • pybind11-master
          • numpy-array-use-type-var/demo/_bindings
          • numpy-array-wrap-with-annotated/demo/_bindings
        • pybind11-v2.11/numpy-array-wrap-with-annotated/demo/_bindings
        • pybind11-v2.9/numpy-array-wrap-with-annotated/demo/_bindings
      • python-3.7/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings
      • python-3.8/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings

11 files changed

+132
-6
lines changed

‎pybind11_stubgen/parser/mixins/parse.py

+8
Original file line numberDiff line numberDiff line change
@@ -171,10 +171,17 @@ def handle_alias(self, path: QualifiedName, origin: Any) -> Alias | None:
171171
)
172172

173173
def handle_attribute(self, path: QualifiedName, value: Any) -> Attribute | None:
174+
doc = None
175+
entries = getattr(value, "__entries", None)
176+
177+
if entries is not None and path[-1] in entries:
178+
doc = self.handle_docstring(path, entries[path[-1]][1])
179+
174180
return Attribute(
175181
name=path[-1],
176182
value=self.handle_value(value),
177183
annotation=ResolvedType(name=self.handle_type(type(value))),
184+
doc=doc,
178185
)
179186

180187
def handle_bases(
@@ -195,6 +202,7 @@ def handle_field(self, path: QualifiedName, value: Any) -> Field | None:
195202
attribute=Attribute(
196203
name=attr.name,
197204
value=attr.value,
205+
doc=attr.doc
198206
),
199207
modifier="static",
200208
)

‎pybind11_stubgen/printer.py

+4-1
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,10 @@ def print_attribute(self, attr: Attribute) -> list[str]:
5151
if attr.value is not None:
5252
parts.append(f" # value = {self.print_value(attr.value)}")
5353

54-
return ["".join(parts)]
54+
result = ["".join(parts)]
55+
if attr.doc is not None:
56+
result.extend(self.print_docstring(attr.doc))
57+
return result
5558

5659
def print_argument(self, arg: Argument) -> str:
5760
parts = []

‎pybind11_stubgen/structs.py

+1
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ class Attribute:
108108
name: Identifier
109109
value: Value | None
110110
annotation: Annotation | None = field_(default=None)
111+
doc: Docstring | None = field_(default=None)
111112

112113

113114
@dataclass

‎stubs/kit-stubs/setup.py

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
from setuptools import setup
2+
import os
3+
4+
5+
def find_stubs(package):
6+
stubs = []
7+
for root, dirs, files in os.walk(package):
8+
for file in files:
9+
path = os.path.join(root, file).replace(package + os.sep, '', 1)
10+
stubs.append(path)
11+
return dict(package=stubs)
12+
13+
14+
setup(
15+
name='kit-stubs',
16+
maintainer="kit Developers",
17+
maintainer_email="[email protected]",
18+
description="PEP 561 type stubs for kit",
19+
version='1.0',
20+
packages=['kit-stubs'],
21+
# PEP 561 requires these
22+
install_requires=['kit'],
23+
package_data=find_stubs('kit-stubs'),
24+
)

‎tests/py-demo/bindings/src/modules/enum.cpp

+5-5
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@
55
void bind_enum_module(py::module&&m) {
66

77
py::enum_<demo::sublibA::ConsoleForegroundColor>(m, "ConsoleForegroundColor")
8-
.value("Green", demo::sublibA::ConsoleForegroundColor::Green)
9-
.value("Yellow", demo::sublibA::ConsoleForegroundColor::Yellow)
10-
.value("Blue", demo::sublibA::ConsoleForegroundColor::Blue)
11-
.value("Magenta", demo::sublibA::ConsoleForegroundColor::Magenta)
12-
.value("None_", demo::sublibA::ConsoleForegroundColor::None_)
8+
.value("Green", demo::sublibA::ConsoleForegroundColor::Green, "Green color")
9+
.value("Yellow", demo::sublibA::ConsoleForegroundColor::Yellow, "Yellow color")
10+
.value("Blue", demo::sublibA::ConsoleForegroundColor::Blue, "Blue color")
11+
.value("Magenta", demo::sublibA::ConsoleForegroundColor::Magenta, "Magenta color")
12+
.value("None_", demo::sublibA::ConsoleForegroundColor::None_, "No color")
1313
.export_values();
1414

1515
m.def(

‎tests/stubs/python-3.12/pybind11-master/numpy-array-use-type-var/demo/_bindings/enum.pyi

+15
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,33 @@ class ConsoleForegroundColor:
3030
Blue: typing.ClassVar[
3131
ConsoleForegroundColor
3232
] # value = <ConsoleForegroundColor.Blue: 34>
33+
"""
34+
Blue color
35+
"""
3336
Green: typing.ClassVar[
3437
ConsoleForegroundColor
3538
] # value = <ConsoleForegroundColor.Green: 32>
39+
"""
40+
Green color
41+
"""
3642
Magenta: typing.ClassVar[
3743
ConsoleForegroundColor
3844
] # value = <ConsoleForegroundColor.Magenta: 35>
45+
"""
46+
Magenta color
47+
"""
3948
None_: typing.ClassVar[
4049
ConsoleForegroundColor
4150
] # value = <ConsoleForegroundColor.None_: -1>
51+
"""
52+
No color
53+
"""
4254
Yellow: typing.ClassVar[
4355
ConsoleForegroundColor
4456
] # value = <ConsoleForegroundColor.Yellow: 33>
57+
"""
58+
Yellow color
59+
"""
4560
__members__: typing.ClassVar[
4661
dict[str, ConsoleForegroundColor]
4762
] # value = {'Green': <ConsoleForegroundColor.Green: 32>, 'Yellow': <ConsoleForegroundColor.Yellow: 33>, 'Blue': <ConsoleForegroundColor.Blue: 34>, 'Magenta': <ConsoleForegroundColor.Magenta: 35>, 'None_': <ConsoleForegroundColor.None_: -1>}

‎tests/stubs/python-3.12/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi

+15
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,33 @@ class ConsoleForegroundColor:
3030
Blue: typing.ClassVar[
3131
ConsoleForegroundColor
3232
] # value = <ConsoleForegroundColor.Blue: 34>
33+
"""
34+
Blue color
35+
"""
3336
Green: typing.ClassVar[
3437
ConsoleForegroundColor
3538
] # value = <ConsoleForegroundColor.Green: 32>
39+
"""
40+
Green color
41+
"""
3642
Magenta: typing.ClassVar[
3743
ConsoleForegroundColor
3844
] # value = <ConsoleForegroundColor.Magenta: 35>
45+
"""
46+
Magenta color
47+
"""
3948
None_: typing.ClassVar[
4049
ConsoleForegroundColor
4150
] # value = <ConsoleForegroundColor.None_: -1>
51+
"""
52+
No color
53+
"""
4254
Yellow: typing.ClassVar[
4355
ConsoleForegroundColor
4456
] # value = <ConsoleForegroundColor.Yellow: 33>
57+
"""
58+
Yellow color
59+
"""
4560
__members__: typing.ClassVar[
4661
dict[str, ConsoleForegroundColor]
4762
] # value = {'Green': <ConsoleForegroundColor.Green: 32>, 'Yellow': <ConsoleForegroundColor.Yellow: 33>, 'Blue': <ConsoleForegroundColor.Blue: 34>, 'Magenta': <ConsoleForegroundColor.Magenta: 35>, 'None_': <ConsoleForegroundColor.None_: -1>}

‎tests/stubs/python-3.12/pybind11-v2.11/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi

+15
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,33 @@ class ConsoleForegroundColor:
3030
Blue: typing.ClassVar[
3131
ConsoleForegroundColor
3232
] # value = <ConsoleForegroundColor.Blue: 34>
33+
"""
34+
Blue color
35+
"""
3336
Green: typing.ClassVar[
3437
ConsoleForegroundColor
3538
] # value = <ConsoleForegroundColor.Green: 32>
39+
"""
40+
Green color
41+
"""
3642
Magenta: typing.ClassVar[
3743
ConsoleForegroundColor
3844
] # value = <ConsoleForegroundColor.Magenta: 35>
45+
"""
46+
Magenta color
47+
"""
3948
None_: typing.ClassVar[
4049
ConsoleForegroundColor
4150
] # value = <ConsoleForegroundColor.None_: -1>
51+
"""
52+
No color
53+
"""
4254
Yellow: typing.ClassVar[
4355
ConsoleForegroundColor
4456
] # value = <ConsoleForegroundColor.Yellow: 33>
57+
"""
58+
Yellow color
59+
"""
4560
__members__: typing.ClassVar[
4661
dict[str, ConsoleForegroundColor]
4762
] # value = {'Green': <ConsoleForegroundColor.Green: 32>, 'Yellow': <ConsoleForegroundColor.Yellow: 33>, 'Blue': <ConsoleForegroundColor.Blue: 34>, 'Magenta': <ConsoleForegroundColor.Magenta: 35>, 'None_': <ConsoleForegroundColor.None_: -1>}

‎tests/stubs/python-3.12/pybind11-v2.9/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi

+15
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,33 @@ class ConsoleForegroundColor:
3030
Blue: typing.ClassVar[
3131
ConsoleForegroundColor
3232
] # value = <ConsoleForegroundColor.Blue: 34>
33+
"""
34+
Blue color
35+
"""
3336
Green: typing.ClassVar[
3437
ConsoleForegroundColor
3538
] # value = <ConsoleForegroundColor.Green: 32>
39+
"""
40+
Green color
41+
"""
3642
Magenta: typing.ClassVar[
3743
ConsoleForegroundColor
3844
] # value = <ConsoleForegroundColor.Magenta: 35>
45+
"""
46+
Magenta color
47+
"""
3948
None_: typing.ClassVar[
4049
ConsoleForegroundColor
4150
] # value = <ConsoleForegroundColor.None_: -1>
51+
"""
52+
No color
53+
"""
4254
Yellow: typing.ClassVar[
4355
ConsoleForegroundColor
4456
] # value = <ConsoleForegroundColor.Yellow: 33>
57+
"""
58+
Yellow color
59+
"""
4560
__members__: typing.ClassVar[
4661
dict[str, ConsoleForegroundColor]
4762
] # value = {'Green': <ConsoleForegroundColor.Green: 32>, 'Yellow': <ConsoleForegroundColor.Yellow: 33>, 'Blue': <ConsoleForegroundColor.Blue: 34>, 'Magenta': <ConsoleForegroundColor.Magenta: 35>, 'None_': <ConsoleForegroundColor.None_: -1>}

‎tests/stubs/python-3.7/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi

+15
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,33 @@ class ConsoleForegroundColor:
3030
Blue: typing.ClassVar[
3131
ConsoleForegroundColor
3232
] # value = <ConsoleForegroundColor.Blue: 34>
33+
"""
34+
Blue color
35+
"""
3336
Green: typing.ClassVar[
3437
ConsoleForegroundColor
3538
] # value = <ConsoleForegroundColor.Green: 32>
39+
"""
40+
Green color
41+
"""
3642
Magenta: typing.ClassVar[
3743
ConsoleForegroundColor
3844
] # value = <ConsoleForegroundColor.Magenta: 35>
45+
"""
46+
Magenta color
47+
"""
3948
None_: typing.ClassVar[
4049
ConsoleForegroundColor
4150
] # value = <ConsoleForegroundColor.None_: -1>
51+
"""
52+
No color
53+
"""
4254
Yellow: typing.ClassVar[
4355
ConsoleForegroundColor
4456
] # value = <ConsoleForegroundColor.Yellow: 33>
57+
"""
58+
Yellow color
59+
"""
4560
__members__: typing.ClassVar[
4661
dict[str, ConsoleForegroundColor]
4762
] # value = {'Green': <ConsoleForegroundColor.Green: 32>, 'Yellow': <ConsoleForegroundColor.Yellow: 33>, 'Blue': <ConsoleForegroundColor.Blue: 34>, 'Magenta': <ConsoleForegroundColor.Magenta: 35>, 'None_': <ConsoleForegroundColor.None_: -1>}

‎tests/stubs/python-3.8/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi

+15
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,33 @@ class ConsoleForegroundColor:
3030
Blue: typing.ClassVar[
3131
ConsoleForegroundColor
3232
] # value = <ConsoleForegroundColor.Blue: 34>
33+
"""
34+
Blue color
35+
"""
3336
Green: typing.ClassVar[
3437
ConsoleForegroundColor
3538
] # value = <ConsoleForegroundColor.Green: 32>
39+
"""
40+
Green color
41+
"""
3642
Magenta: typing.ClassVar[
3743
ConsoleForegroundColor
3844
] # value = <ConsoleForegroundColor.Magenta: 35>
45+
"""
46+
Magenta color
47+
"""
3948
None_: typing.ClassVar[
4049
ConsoleForegroundColor
4150
] # value = <ConsoleForegroundColor.None_: -1>
51+
"""
52+
No color
53+
"""
4254
Yellow: typing.ClassVar[
4355
ConsoleForegroundColor
4456
] # value = <ConsoleForegroundColor.Yellow: 33>
57+
"""
58+
Yellow color
59+
"""
4560
__members__: typing.ClassVar[
4661
dict[str, ConsoleForegroundColor]
4762
] # value = {'Green': <ConsoleForegroundColor.Green: 32>, 'Yellow': <ConsoleForegroundColor.Yellow: 33>, 'Blue': <ConsoleForegroundColor.Blue: 34>, 'Magenta': <ConsoleForegroundColor.Magenta: 35>, 'None_': <ConsoleForegroundColor.None_: -1>}

0 commit comments

Comments
 (0)