From 5ec19d6ef3fd03c142f5b90cda70a9fb18ecaa43 Mon Sep 17 00:00:00 2001 From: jfhs Date: Mon, 3 Jun 2024 16:56:13 +0200 Subject: [PATCH] Add support for pybind11 enum docstrings --- pybind11_stubgen/parser/mixins/parse.py | 8 ++++++++ pybind11_stubgen/printer.py | 5 ++++- pybind11_stubgen/structs.py | 1 + tests/py-demo/bindings/src/modules/enum.cpp | 10 +++++----- .../demo/_bindings/enum.pyi | 15 +++++++++++++++ .../demo/_bindings/enum.pyi | 15 +++++++++++++++ .../demo/_bindings/enum.pyi | 15 +++++++++++++++ .../demo/_bindings/enum.pyi | 15 +++++++++++++++ .../demo/_bindings/enum.pyi | 15 +++++++++++++++ .../demo/_bindings/enum.pyi | 15 +++++++++++++++ 10 files changed, 108 insertions(+), 6 deletions(-) diff --git a/pybind11_stubgen/parser/mixins/parse.py b/pybind11_stubgen/parser/mixins/parse.py index dbf6f15..f2576de 100644 --- a/pybind11_stubgen/parser/mixins/parse.py +++ b/pybind11_stubgen/parser/mixins/parse.py @@ -171,10 +171,17 @@ def handle_alias(self, path: QualifiedName, origin: Any) -> Alias | None: ) def handle_attribute(self, path: QualifiedName, value: Any) -> Attribute | None: + doc = None + entries = getattr(value, "__entries", None) + + if entries is not None and path[-1] in entries: + doc = self.handle_docstring(path, entries[path[-1]][1]) + return Attribute( name=path[-1], value=self.handle_value(value), annotation=ResolvedType(name=self.handle_type(type(value))), + doc=doc, ) def handle_bases( @@ -195,6 +202,7 @@ def handle_field(self, path: QualifiedName, value: Any) -> Field | None: attribute=Attribute( name=attr.name, value=attr.value, + doc=attr.doc ), modifier="static", ) diff --git a/pybind11_stubgen/printer.py b/pybind11_stubgen/printer.py index 8ef4af2..83532c1 100644 --- a/pybind11_stubgen/printer.py +++ b/pybind11_stubgen/printer.py @@ -51,7 +51,10 @@ def print_attribute(self, attr: Attribute) -> list[str]: if attr.value is not None: parts.append(f" # value = {self.print_value(attr.value)}") - return ["".join(parts)] + result = ["".join(parts)] + if attr.doc is not None: + result.extend(self.print_docstring(attr.doc)) + return result def print_argument(self, arg: Argument) -> str: parts = [] diff --git a/pybind11_stubgen/structs.py b/pybind11_stubgen/structs.py index 74563f2..90c4d14 100644 --- a/pybind11_stubgen/structs.py +++ b/pybind11_stubgen/structs.py @@ -108,6 +108,7 @@ class Attribute: name: Identifier value: Value | None annotation: Annotation | None = field_(default=None) + doc: Docstring | None = field_(default=None) @dataclass diff --git a/tests/py-demo/bindings/src/modules/enum.cpp b/tests/py-demo/bindings/src/modules/enum.cpp index a3532c5..30c9019 100644 --- a/tests/py-demo/bindings/src/modules/enum.cpp +++ b/tests/py-demo/bindings/src/modules/enum.cpp @@ -5,11 +5,11 @@ void bind_enum_module(py::module&&m) { py::enum_(m, "ConsoleForegroundColor") - .value("Green", demo::sublibA::ConsoleForegroundColor::Green) - .value("Yellow", demo::sublibA::ConsoleForegroundColor::Yellow) - .value("Blue", demo::sublibA::ConsoleForegroundColor::Blue) - .value("Magenta", demo::sublibA::ConsoleForegroundColor::Magenta) - .value("None_", demo::sublibA::ConsoleForegroundColor::None_) + .value("Green", demo::sublibA::ConsoleForegroundColor::Green, "Green color") + .value("Yellow", demo::sublibA::ConsoleForegroundColor::Yellow, "Yellow color") + .value("Blue", demo::sublibA::ConsoleForegroundColor::Blue, "Blue color") + .value("Magenta", demo::sublibA::ConsoleForegroundColor::Magenta, "Magenta color") + .value("None_", demo::sublibA::ConsoleForegroundColor::None_, "No color") .export_values(); m.def( diff --git a/tests/stubs/python-3.12/pybind11-master/numpy-array-use-type-var/demo/_bindings/enum.pyi b/tests/stubs/python-3.12/pybind11-master/numpy-array-use-type-var/demo/_bindings/enum.pyi index e3f9e10..d0b7ae7 100644 --- a/tests/stubs/python-3.12/pybind11-master/numpy-array-use-type-var/demo/_bindings/enum.pyi +++ b/tests/stubs/python-3.12/pybind11-master/numpy-array-use-type-var/demo/_bindings/enum.pyi @@ -30,18 +30,33 @@ class ConsoleForegroundColor: Blue: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Blue color + """ Green: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Green color + """ Magenta: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Magenta color + """ None_: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + No color + """ Yellow: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Yellow color + """ __members__: typing.ClassVar[ dict[str, ConsoleForegroundColor] ] # value = {'Green': , 'Yellow': , 'Blue': , 'Magenta': , 'None_': } diff --git a/tests/stubs/python-3.12/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi b/tests/stubs/python-3.12/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi index e3f9e10..d0b7ae7 100644 --- a/tests/stubs/python-3.12/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi +++ b/tests/stubs/python-3.12/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi @@ -30,18 +30,33 @@ class ConsoleForegroundColor: Blue: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Blue color + """ Green: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Green color + """ Magenta: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Magenta color + """ None_: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + No color + """ Yellow: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Yellow color + """ __members__: typing.ClassVar[ dict[str, ConsoleForegroundColor] ] # value = {'Green': , 'Yellow': , 'Blue': , 'Magenta': , 'None_': } diff --git a/tests/stubs/python-3.12/pybind11-v2.11/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi b/tests/stubs/python-3.12/pybind11-v2.11/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi index e3f9e10..d0b7ae7 100644 --- a/tests/stubs/python-3.12/pybind11-v2.11/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi +++ b/tests/stubs/python-3.12/pybind11-v2.11/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi @@ -30,18 +30,33 @@ class ConsoleForegroundColor: Blue: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Blue color + """ Green: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Green color + """ Magenta: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Magenta color + """ None_: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + No color + """ Yellow: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Yellow color + """ __members__: typing.ClassVar[ dict[str, ConsoleForegroundColor] ] # value = {'Green': , 'Yellow': , 'Blue': , 'Magenta': , 'None_': } diff --git a/tests/stubs/python-3.12/pybind11-v2.9/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi b/tests/stubs/python-3.12/pybind11-v2.9/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi index e3f9e10..d0b7ae7 100644 --- a/tests/stubs/python-3.12/pybind11-v2.9/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi +++ b/tests/stubs/python-3.12/pybind11-v2.9/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi @@ -30,18 +30,33 @@ class ConsoleForegroundColor: Blue: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Blue color + """ Green: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Green color + """ Magenta: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Magenta color + """ None_: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + No color + """ Yellow: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Yellow color + """ __members__: typing.ClassVar[ dict[str, ConsoleForegroundColor] ] # value = {'Green': , 'Yellow': , 'Blue': , 'Magenta': , 'None_': } diff --git a/tests/stubs/python-3.7/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi b/tests/stubs/python-3.7/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi index e3f9e10..d0b7ae7 100644 --- a/tests/stubs/python-3.7/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi +++ b/tests/stubs/python-3.7/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi @@ -30,18 +30,33 @@ class ConsoleForegroundColor: Blue: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Blue color + """ Green: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Green color + """ Magenta: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Magenta color + """ None_: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + No color + """ Yellow: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Yellow color + """ __members__: typing.ClassVar[ dict[str, ConsoleForegroundColor] ] # value = {'Green': , 'Yellow': , 'Blue': , 'Magenta': , 'None_': } diff --git a/tests/stubs/python-3.8/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi b/tests/stubs/python-3.8/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi index e3f9e10..d0b7ae7 100644 --- a/tests/stubs/python-3.8/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi +++ b/tests/stubs/python-3.8/pybind11-master/numpy-array-wrap-with-annotated/demo/_bindings/enum.pyi @@ -30,18 +30,33 @@ class ConsoleForegroundColor: Blue: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Blue color + """ Green: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Green color + """ Magenta: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Magenta color + """ None_: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + No color + """ Yellow: typing.ClassVar[ ConsoleForegroundColor ] # value = + """ + Yellow color + """ __members__: typing.ClassVar[ dict[str, ConsoleForegroundColor] ] # value = {'Green': , 'Yellow': , 'Blue': , 'Magenta': , 'None_': }