Python package generation script

.github/workflows/test-cells-conda.yml

@@ -105,7 +105,10 @@ jobs:
           COVERAGE_FILE: ${{ github.workspace }}/.coverage
         run: |
           python3 -m coverage combine --rcfile=.cov_sub.rc
-          python3 -m coverage xml --rcfile=.cov_sub.rc
+          # Report with the repo's coverage config so [tool.coverage.report]
+          # exclude_also applies (.cov_sub.rc only sets [run]); otherwise excluded
+          # lines in cppwg modules this flag never imports are reported as missed.
+          python3 -m coverage xml --rcfile="$GITHUB_WORKSPACE/pyproject.toml"
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.12'

.github/workflows/test-shapes-pip.yml

@@ -60,7 +60,11 @@ jobs:
 
       - name: Generate coverage report
         if: matrix.python-version == '3.12'
-        run: python3 -m coverage xml
+        # Use the repo's coverage config so [tool.coverage.report] exclude_also
+        # applies here too (this runs from examples/shapes, where it isn't found);
+        # otherwise excluded lines (e.g. `if __name__`) in cppwg modules this flag
+        # never imports are wrongly reported as missed, failing codecov's patch gate.
+        run: python3 -m coverage xml --rcfile="$GITHUB_WORKSPACE/pyproject.toml"
         working-directory: examples/shapes
 
       - name: Upload coverage to Codecov

cppwg/__main__.py

@@ -2,6 +2,7 @@
 
 import argparse
 import logging
+import sys
 from datetime import datetime
 from pathlib import Path
 
@@ -54,6 +55,7 @@ def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         prog="cppwg",
         description="Generate Python Wrappers for C++ code",
+        epilog="Run 'cppwg genpackage --help' for the Python package-layer generator.",
     )
 
     parser.add_argument(
@@ -193,7 +195,18 @@ def generate(args: argparse.Namespace) -> None:
 
 
 def main() -> None:
-    """Generate wrappers from command line arguments."""
+    """Generate wrappers from command line arguments.
+
+    ``cppwg genpackage ...`` is dispatched to the package-layer generator
+    (:mod:`cppwg.genpackage`); any other invocation runs wrapper generation as
+    usual. The subcommand is intercepted before argument parsing so the normal
+    CLI (a leading ``SOURCE_ROOT`` positional) is entirely unaffected.
+    """
+    if len(sys.argv) > 1 and sys.argv[1] == "genpackage":
+        from cppwg.genpackage import main as genpackage_main
+
+        raise SystemExit(genpackage_main(sys.argv[2:]))
+
     args = parse_args()
 
     log_handlers = []

cppwg/generators.py

@@ -1,5 +1,6 @@
 """The main interface for generating Python wrappers."""
 
+import json
 import logging
 import os
 import re
@@ -18,7 +19,10 @@
 from cppwg.utils.constants import (
     CPPWG_DEFAULT_WRAPPER_DIR,
     CPPWG_HEADER_COLLECTION_FILENAME,
+    CPPWG_PACKAGE_MODEL_FILENAME,
+    CPPWG_PACKAGE_MODEL_NOTICE,
 )
+from cppwg.utils.package_model import build_package_model
 from cppwg.version import __version__ as cppwg_version
 from cppwg.writers.header_collection_writer import CppHeaderCollectionWriter
 from cppwg.writers.package_writer import CppPackageWrapperWriter
@@ -422,6 +426,26 @@ def write_wrappers(self) -> None:
         )
         package_writer.write()
 
+    def write_package_model(self) -> None:
+        """
+        Write the package model (cppwg_package_model.json) to the wrapper root.
+
+        A small JSON description of the generated modules and their classes /
+        instantiations / enums / free functions, so a separate step (the
+        ``cppwg genpackage`` subcommand) can generate the Python package layer
+        without re-parsing the source. Written last, once the info tree is final.
+        JSON is used deliberately: this is a machine-generated, git-diff-checked
+        artifact, so a deterministic serialization matters more than YAML's
+        readability (the hand-authored configs stay YAML).
+        """
+        model = build_package_model(self.package_info)
+        # A do-not-edit notice as `_comment` (JSON has no comments); the generator
+        # ignores unknown top-level keys.
+        model = {"_comment": CPPWG_PACKAGE_MODEL_NOTICE, **model}
+        model_path = os.path.join(self.wrapper_root, CPPWG_PACKAGE_MODEL_FILENAME)
+        content = json.dumps(model, indent=2, sort_keys=True) + "\n"
+        utils.write_file_if_changed(model_path, content, self.overwrite)
+
     def generate(self) -> None:
         """
         Parse yaml configuration and C++ source to generate Python wrappers.
@@ -482,3 +506,7 @@ def generate(self) -> None:
 
         #  Write the wrapper code for the package
         self.write_wrappers()
+
+        # Write the package model (cppwg_package_model.json) for the package-layer
+        # generator (cppwg genpackage).
+        self.write_package_model()