Skip to content

fix: add class doc string to py::native_enum #5617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Apr 15, 2025
Merged

fix: add class doc string to py::native_enum #5617

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2d06ad7
add class doc string to native_enum
dyollb Apr 14, 2025
a952009
adapt doc argument name
dyollb Apr 14, 2025
d998809
fix test, make class enum doc None by default
dyollb Apr 14, 2025
4b0e68c
fix other python versions?
dyollb Apr 14, 2025
eda2be7
make clang-tidy happy
dyollb Apr 14, 2025
f53f182
rename 'enum_doc' to 'class_doc'
dyollb Apr 15, 2025
a8bdaeb
update documentation
dyollb Apr 15, 2025
0346498
[skip ci] Polish changed documentation (mostly done by ChatGPT).
rwgk Apr 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion include/pybind11/detail/native_enum_data.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,12 @@ class native_enum_data {
native_enum_data(const object &parent_scope,
const char *enum_name,
const char *native_type_name,
const char *enum_doc,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're using "class doc" in the PR title and the added test: I think it's a much better name than enum_doc here, because then it is crystal clear that it does not apply to the enum members. Could you please use class_doc here (and in native_enum.h), too?

const std::type_index &enum_type_index)
: enum_name_encoded{enum_name}, native_type_name_encoded{native_type_name},
enum_type_index{enum_type_index}, parent_scope(parent_scope), enum_name{enum_name},
native_type_name{native_type_name}, export_values_flag{false}, finalize_needed{false} {}
native_type_name{native_type_name}, enum_doc(enum_doc), export_values_flag{false},
finalize_needed{false} {}

void finalize();

Expand Down Expand Up @@ -70,6 +72,7 @@ class native_enum_data {
object parent_scope;
str enum_name;
str native_type_name;
str enum_doc;

protected:
list members;
Expand Down Expand Up @@ -191,6 +194,7 @@ inline void native_enum_data::finalize() {
parent_scope.attr(member_name) = py_enum[member_name];
}
}
py_enum.attr("__doc__") = enum_doc;
for (auto doc : docs) {
py_enum[doc[int_(0)]].attr("__doc__") = doc[int_(1)];
}
Expand Down
5 changes: 3 additions & 2 deletions include/pybind11/native_enum.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,10 @@ class native_enum : public detail::native_enum_data {

native_enum(const object &parent_scope,
const char *name,
const char *native_type_name = "enum.Enum")
const char *native_type_name,
const char *doc = "")
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drive-by comment: Could you please use the same (longer) name consistently here and in native_enum_data.h?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

: detail::native_enum_data(
parent_scope, name, native_type_name, std::type_index(typeid(EnumType))) {
parent_scope, name, native_type_name, doc, std::type_index(typeid(EnumType))) {
if (detail::get_local_type_info(typeid(EnumType)) != nullptr
|| detail::get_global_type_info(typeid(EnumType)) != nullptr) {
pybind11_fail(
Expand Down
6 changes: 3 additions & 3 deletions tests/test_native_enum.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
TEST_SUBMODULE(native_enum, m) {
using namespace test_native_enum;

py::native_enum<smallenum>(m, "smallenum", "enum.IntEnum")
py::native_enum<smallenum>(m, "smallenum", "enum.IntEnum", "doc smallenum")
.value("a", smallenum::a)
.value("b", smallenum::b)
.value("c", smallenum::c)
Expand All @@ -89,7 +89,7 @@ TEST_SUBMODULE(native_enum, m) {
.value("blue", color::blue)
.finalize();

py::native_enum<altitude>(m, "altitude")
py::native_enum<altitude>(m, "altitude", "enum.Enum")
.value("high", altitude::high)
.value("low", altitude::low)
.finalize();
Expand Down Expand Up @@ -189,7 +189,7 @@ TEST_SUBMODULE(native_enum, m) {
py::native_enum<fake>(m, "fake_double_registration_native_enum", "enum.IntEnum")
.value("x", fake::x)
.finalize();
py::native_enum<fake>(m, "fake_double_registration_native_enum");
py::native_enum<fake>(m, "fake_double_registration_native_enum", "enum.Enum");
});

m.def("native_enum_name_clash", [](py::module_ &m) {
Expand Down
4 changes: 4 additions & 0 deletions tests/test_native_enum.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,10 +108,14 @@
assert m.exv1 is m.export_values.exv1


def test_class_doc():
assert m.smallenum.__doc__ == "doc smallenum"


def test_member_doc():
pure_native = enum.IntEnum("pure_native", (("mem", 0),))
assert m.member_doc.mem0.__doc__ == "docA"
assert m.member_doc.mem1.__doc__ == pure_native.mem.__doc__

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 pypy-3.11 • ubuntu-22.04 • x64 

test_member_doc

AssertionError: assert '' == None
 +  where '' = <member_doc.mem1: 1>.__doc__
 +    where <member_doc.mem1: 1> = <enum 'member_doc'>.mem1
 +      where <enum 'member_doc'> = m.member_doc
 +  and   None = <pure_native.mem: 0>.__doc__
 +    where <pure_native.mem: 0> = <enum 'pure_native'>.mem

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 3.13 • ubuntu-22.04 • x64 

test_member_doc

AssertionError: assert '' == None
 +  where '' = <member_doc.mem1: 1>.__doc__
 +    where <member_doc.mem1: 1> = <enum 'member_doc'>.mem1
 +      where <enum 'member_doc'> = m.member_doc
 +  and   None = <pure_native.mem: 0>.__doc__
 +    where <pure_native.mem: 0> = <enum 'pure_native'>.mem

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 pypy-3.10 • ubuntu-22.04 • x64 

test_member_doc

AssertionError: assert '' == 'An enumeration.'
  
  - An enumeration.

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 3.8 • ubuntu-22.04 • x64 -DPYBIND11_FINDPYTHON=OFF -DCMAKE_CXX_FLAGS="-D_=1" -DPYBIND11_NUMPY_1_ONLY=ON 

test_member_doc

AssertionError: assert '' == 'An enumeration.'
  
  - An enumeration.

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 graalpy-24.2 • ubuntu-22.04 • x64 

test_member_doc

AssertionError: assert '' == None
 +  where '' = <member_doc.mem1: 1>.__doc__
 +    where <member_doc.mem1: 1> = <enum 'member_doc'>.mem1
 +      where <enum 'member_doc'> = m.member_doc
 +  and   None = <pure_native.mem: 0>.__doc__
 +    where <pure_native.mem: 0> = <enum 'pure_native'>.mem

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 3.12 • ubuntu-latest • x64 -DCMAKE_CXX_FLAGS="-DPYBIND11_RUN_TESTING_WITH_SMART_HOLDER_AS_DEFAULT_BUT_NEVER_USE_IN_PRODUCTION_PLEASE" 

test_member_doc

AssertionError: assert '' == None
 +  where '' = <member_doc.mem1: 1>.__doc__
 +    where <member_doc.mem1: 1> = <enum 'member_doc'>.mem1
 +      where <enum 'member_doc'> = m.member_doc
 +  and   None = <pure_native.mem: 0>.__doc__
 +    where <pure_native.mem: 0> = <enum 'pure_native'>.mem

Check failure on line 118 in tests/test_native_enum.py

View workflow job for this annotation

GitHub Actions / 🐍 graalpy-24.1 • ubuntu-latest • x64 

test_member_doc

AssertionError
assert m.member_doc.mem2.__doc__ == "docC"


Expand Down
Loading