Code Conventions

Python conventions

Follow PEP 8.

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

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):

• 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

Stub conventions

Stubs mostly follow Python conventions (see above). We use some modified conventions, mostly to make stubs more compact. See the typeshed coding style for details.