Enum support

[kwabenantim]

Fixes #113

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[Copilot]

Pull request overview

Adds first-class support for wrapping C++ enums in cppwg, allowing enums to be specified directly in package_info.yaml (or discovered via CPPWG_ALL) and emitted as module-scope py::enum_ registrations ahead of functions/classes to support default enum arguments at import time.

Changes:

• Introduces enums / use_all_enums in config parsing and ModuleInfo, plus enum discovery/update wiring.
• Adds CppEnumInfo and CppEnumWrapperWriter, and injects enum registration into the module template before free functions and class register calls.
• Extends tests, documentation, and the shapes example to demonstrate and validate enum wrapping (including defaulted enum args).

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_utils.py	Adds regression test ensuring scoped enums aren’t misdetected as classes.
tests/test_package_info_parser.py	Adds parsing tests for explicit enums: and CPPWG_ALL enums.
tests/test_module_writer.py	Tests enum registration ordering before free functions/classes for default-arg safety.
tests/test_header_collection_writer.py	Updates test stubs to include enums/use_all_enums.
tests/test_enum_writer.py	Adds unit tests for enum wrapper code generation.
tests/test_enum_info.py	Adds unit tests for CppEnumInfo construction/config application.
examples/shapes/wrapper/wrapper_header_collection.cppwg.hpp	Includes the new enum header in the wrapper header collection.
examples/shapes/wrapper/primitives/ShapeClassifier.cppwg.hpp	Adds generated wrapper header for the new example class.
examples/shapes/wrapper/primitives/ShapeClassifier.cppwg.cpp	Adds generated wrapper implementation using an enum default argument.
examples/shapes/wrapper/primitives/_pyshapes_primitives.main.cppwg.cpp	Demonstrates generated module-scope enum registrations and class registration order.
examples/shapes/wrapper/package_info.yaml	Demonstrates configuring enums: in a real wrapper config.
examples/shapes/src/py/tests/test_classes.py	Adds Python-level tests for enum wrapping and defaulted enum args.
examples/shapes/src/cpp/primitives/ShapeKind.hpp	Adds example unscoped + scoped enums and a class using a defaulted enum argument.
doc/reference.md	Documents the new enums module option and per-enum options.
cppwg/writers/module_writer.py	Emits enum registration blocks into the module body (before free funcs/classes).
cppwg/writers/header_collection_writer.py	Includes headers for explicitly configured enums and treats use_all_enums as include-all.
cppwg/writers/enum_writer.py	New writer to generate py::enum_ registration code.
cppwg/utils/utils.py	Adjusts class-finder regex to avoid treating enum class/struct as classes.
cppwg/templates/pybind11_default.py	Adds ${enums} to the module template and adds an enum_register template.
cppwg/parsers/package_info_parser.py	Parses enums / use_all_enums and constructs CppEnumInfo objects.
cppwg/info/module_info.py	Adds enum collection fields, discovery/update behavior, and sorting.
cppwg/info/enum_info.py	New info type resolving enums from pygccxml namespace declarations.

Suppressed comments (1)

examples/shapes/src/cpp/primitives/ShapeKind.hpp:64

• This #endif comment should be updated to match the (non-reserved) include guard macro name so it stays consistent after renaming.

#endif // _SHAPEKIND_HPP

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated no new comments.

Suppressed comments (2)

cppwg/writers/header_collection_writer.py:132

• Enum headers are only added to the header-collection include list when source_file_path is set. However the enum config/parser (and tests) also populate source_file; with the current logic, providing only source_file won’t include the header, so the enum won’t be parsed and CppEnumInfo.update_from_ns() will fail to resolve it.

                for enum_info in module_info.enum_collection:
                    if enum_info.source_file_path:
                        include_files.add(
                            os.path.basename(enum_info.source_file_path)
                        )

cppwg/info/enum_info.py:67

• The error message here says the user must set source_file_path, but enums can also be configured with source_file (and the parser/tests accept it). If enum headers are included via source_file too, this message becomes misleading; it should mention both options (or otherwise be aligned with the supported config keys).

            logger.error(
                f"Could not find enum {self.name}. Set source_file_path "
                "in the config so that its header is included."
            )

[Copilot]

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated no new comments.

Suppressed comments (2)

cppwg/info/module_info.py:300

• When use_all_enums discovers enums, the created CppEnumInfo objects are appended directly without setting parent. CppEnumInfo.should_export_values() relies on hierarchy_attribute("export_values"), which walks the parent chain, so module/package-level export_values (and any other inheritable options) won’t apply for enums discovered via CPPWG_ALL.

                    enum_info = CppEnumInfo(enum_decl.name)
                    enum_info.module_info = self
                    self.enum_collection.append(enum_info)

cppwg/info/enum_info.py:67

• The error log here says only source_file_path will cause an explicitly listed enum’s header to be included, but source_file is also supported (and the header may already be included via another wrapped entity). This message/comment is misleading and will send users toward the wrong fix.

            # header is only included when source_file_path is set in the config.
            logger = logging.getLogger()
            logger.error(
                f"Could not find enum {self.name}. Set source_file_path "
                "in the config so that its header is included."