Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-281

Coding Conventions for Pybind11 Files

    XMLWordPrintable

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None

      Description

      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.

        Attachments

          Issue Links

            Activity

            Hide
            jbosch Jim Bosch added a comment -

            Ah, excellent! I'll make that change, then.

            Show
            jbosch Jim Bosch added a comment - Ah, excellent! I'll make that change, then.
            Hide
            jbosch Jim Bosch added a comment -

            RFC adopted. Let's move discussion about style and text issues to the DM-8577 page.

            Show
            jbosch Jim Bosch added a comment - RFC adopted. Let's move discussion about style and text issues to the DM-8577 page.
            Hide
            tjenness Tim Jenness added a comment -

            All triggered tickets have been closed. Should this RFC be marked implemented now?

            Show
            tjenness Tim Jenness added a comment - All triggered tickets have been closed. Should this RFC be marked implemented now?
            Hide
            tjenness Tim Jenness added a comment -

            Reiterating my comment wondering whether this RFC should be closed now?

            Show
            tjenness Tim Jenness added a comment - Reiterating my comment wondering whether this RFC should be closed now?
            Hide
            jbosch Jim Bosch added a comment -

            This particular RFC is done, though some of the issues it raised made be revisited on DM-9786; that should produce a new RFC if needed.

            Show
            jbosch Jim Bosch added a comment - This particular RFC is done, though some of the issues it raised made be revisited on DM-9786 ; that should produce a new RFC if needed.

              People

              Assignee:
              jbosch Jim Bosch
              Reporter:
              jbosch Jim Bosch
              Watchers:
              Jim Bosch, John Swinbank, Kian-Tat Lim, Krzysztof Findeisen, Pim Schellart [X] (Inactive), Russell Owen, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:
                Planned End: