Basics¶

CppWG is driven by a YAML configuration file that describes a package made of one or more modules, and the classes and free functions each module wraps.

name: pyshapes                 # package
modules:
  - name: primitives           # module -> _pyshapes_primitives extension
    source_locations:
      - src/cpp/primitives
    classes:
      - name: Rectangle        # class
        excluded_methods:
          - GetArea

Note

Each module is compiled into its own extension.

Selecting what to wrap¶

As in the example above, you can list classes and free functions explicitly under a module. Alternatively, you can wrap everything found in the module’s source_locations with the CPPWG_ALL setting.

modules:
  - name: all
    source_locations:
      - src/cpp
    classes: CPPWG_ALL
    free_functions: CPPWG_ALL

CPPWG_ALL must be the whole value. A list that merely contains it (e.g. [CPPWG_ALL, Foo]) is treated as literal class names, not “wrap everything”.

Excluding members¶

Several options drop members that should not (or cannot) be wrapped.

excluded: True: drop the whole class.
excluded_methods: drop methods by name.
return_type_excludes: drop methods whose return type match.
arg_type_excludes: drop methods (and constructors) with an argument type match.
constructor_arg_type_excludes: drop constructors with an argument type match.
constructor_signature_excludes: drop a constructor by its full argument type list.

modules:
  - name: primitives
    classes:
      - name: Rectangle
        excluded_methods:
          - GetArea                     # drop Rectangle::GetArea
        return_type_excludes:
          - Shape<2>                    # drop methods returning Shape<2>
        arg_type_excludes:
          - AbstractMesh                # drop methods/constructors taking an AbstractMesh
        constructor_arg_type_excludes:
          - AbstractMesh                # drop constructors taking an AbstractMesh
        constructor_signature_excludes:
          - [unsigned]                  # drop the Rectangle(unsigned) constructor
          - [double, double]            # drop the Rectangle(double, double) constructor
      - name: Circle
        excluded: True                  # drop the whole Circle class