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.