Code Conventions

Style

Python code should follow the Python Style Guide: PEP 8.

Documentation Strings should follow Python’s documentation style given in Chapter 7 of the Python Developer’s Guide. Use reStructuredText (reST) as extended by Sphinx.

The docstrings of MainToolWindow and MainToolWindow.create_child_window() can serve as reference docstrings. Specifying an argument’s type is not necessary; if PEP 484 style type hints are used, Sphinx (through the spinx_autodoc_typehints extension) will pick them up automatically.

Editor Defaults

All python files should have the following modeline at the top:

# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4:

But modelines are a security risk, so put:

au FileType python setlocal tabstop=8 expandtab shiftwidth=4 softtabstop=4

in your .vimrc as well.

Line Endings

The ChimeraX git repository uses line ending normalization. On checkout, the majority of files will have LF line endings. Use any editor in any configuration; line endings in mixed files or CRLF files will be converted to LF on check-in except as specified in .gitattributes, which you may edit to protect any file that must have its original line endings.

If you are comfortable, you can set core.safecrlf to false in your ~/.gitconfig in order to ignore routine normalization warnings from git when using CRLF line endings on Windows.

Wheel API Control

The canonical way to guard code against being imported in the wheel is to import runtime_env_is_chimerax_app from chimerax.core and put app-specific code under a guard:

if runtime_env_is_chimerax_app():
    # app-specific code

This can be used, among other things, to ensure that when users use tab completion on modules, what’s shown to be available to them isn’t polluted by code that won’t work outside the application. If you find yourself feeling the urge to guard code inside a function, consider how the function could be refactored into an app-specific function that calls a general one.