DMTN-024: Pybind11 coding guidelines

  • Pim Schellart

Latest Revision: 2016-07-02

Warning

This document has been superseded by the pybind11 information in the LSST DM Developer Guide.

This document describes coding guidelines for using pybind11 within LSST.

1. Modules and source files

1-1. Wrapper modules SHOULD be named after the header they wrap with an underscore prefix

If a module wraps header.h the wrapper implementation should be in header.cc and the module name should be _header.

Note

Unlike what we currently have with Swig there is no Lib suffix.

1-2. Pure Python code SHOULD go in a module named after the header without a pre or suffix

So the pure Python code that extends functionality from _header goes in header.py.

1-3. Pure Python code MAY go into a differently named file to avoid circular imports

If circular imports would otherwise happen when applying 1-2 the pure Python code may go into another file.

1-4. There SHOULD be one module for each wrapped header file

By wrapping into separate modules (to be combined in __init__) we reduce compilation and linking time.

2. Naming conventions

2-1. Module object names SHOULD be mod or camel case prefixed with mod

If a wrapper only contains one module the name of the object should be mod. Otherwise it should be camel case prefixed with mod as in modExample.

2-2. Class object names SHOULD be cls or camel case prefixed with cls

If a wrapper only contains one class the name of the object should be cls. Otherwise it should be camel case prefixed with cls as in clsExample.

3. Holder types

3-1. The default unique_ptr holder type SHOULD be used where possible

By not specifying a holder type explicitly it becomes unique_ptr. This is to be preferred (over shared_ptr).

3-2. A shared_ptr holder type MAY be used where nessesary

Only to be used where required.