Code Conventions

Python conventions

Follow PEP 8.

We use the flake8 linter to enforce style rules. This greatly simplifies code reviews.

All functions must have type annotations (except for test data).

Exceptions:

• We use 99 characters as the maximum line length.
• Use spaces around = signs in default parameter values in functions with annotations:

def f(x: int = 1) -> None: ...  # OK, since f is annotated

def f(x=1) -> None: ...         # OK, fall back to PEP 8 if there is no annotation

Features to avoid

It's usually better to avoid these Python features (at least in performance-sensitive code):

• getattr, setattr
  • Mypy can't type check these calls properly
  • These get compiled into slow dynamic attribute gets/sets by mypyc
• functools
  • Type checking is sometimes limited, resulting in Any types
  • Mypyc, our compiler, often generates better code if these are replaced with more "primitive" / lower level Python code
• copy.deepcopy
  • This may be dangerous with objects with complex state such as caches (we might also add such state later)
  • Performance can be hard to predict
  • This can cause problems in code compiled with mypyc
• Metaclasses
  • Mypyc, our compiler, generates less efficient code for metaclasses
  • Type checking may be limited
  • Metaclasses can make code harder to understand
• Any types
  • These compromise type checking precision
  • Operations on Any types get compiled to slow generic operations by mypyc