While pybind11 wrappers are a combination of C++ and Python code, they contain enough common patterns and special considerations that they merit their own section in the DM style guide.

Pim Schellart [X] and I have put together a draft proposal for that guide here:

https://developer.lsst.io/v/DM-8577/coding/pybind11_style_guide.html#

Most rules are derived from conventions either put in place at the beginning of the pybind11 port or from practices that developed during the port that need to be formalized.

In one major area - Modules and Source Files - we have proposed a convention quite different from either of the two conventions currently used in the pybind11 branch, motivated by prioritizing the following:

1. Avoid accidental use of "incomplete" wrappers, by ensuring there is exactly one consistently-named module that serves as the entry point to each set of wrappers.
2. Do not require developers to enumerate the classes or functions covered by a set of wrappers in more than one place (as such lists can easily get out of sync).
3. Make module and file names the same whenever possible.

These goals seem to be fundamentally incompatible with two other common goals, which we were not able to meet:

• Avoid from <module> import *.
• Avoid having to rename the C++ module when the first pure-Python code is added (or the last pure-Python code removed) for a set of wrappers.

As a result, we expect the Module and Source files rules to be the most contentious, as the relative priority of all of these goals may not be held universally. To help keep the discussion constructive, we ask that any alternatives proposals for this section include whether they are proposing a different technical solution, a different ordering of priorities, or both.