Python - Style Guide and Good Practices

General

It’s generally good to keep The Zen of Python in mind when writing code.

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Format

No need to worry about formatting your code. We use black.

Naming

• All names for variables/functions/classes etc. should be precise, unambiguous and intuitive.
• Your naming should also be consistent.
• Single character names like u for user or i to iterate over something are usually not a good idea. Try to be explicit so that the reader can still guess a variable’s meaning even if the variable is used far away from it’s definition in the code.
• Use a leading underscore to mark functions/methods as private, e.g. def _do_something():
• Remember to not choose variable names that are already taken by Python built-ins. Even though Python does not restrict it, the names id, str, or input are not good variable names because they are already taken. You can either use trailing underscores to solve the problem (e.g. id –> id_) or you can try to find better explicit names (e.g. id –> identifier).

Type Hints

Please use type hints for new code, and feel free to add them to existing code.

Arguments and Keyword Arguments

• Name your positional arguments and keyword arguments explicitly instead of using only *args, **kwargs, e.g.

  def do_whatever(*args, **kwargs):  # don't do this
      ...
  

  Instead, name them explicitly:

  def do_whatever(foo: int, bar: int | None = None):
      ...
  

  Valid exceptions to this rule can be made when you overwrite a function or method from an external source (e.g. overwriting methods from Django classes).

• Find sensible defaults for arguments that represent configuration. This will make the interface of your function less complex and easier to use.
• Prefer keyword arguments over positional arguments for celery tasks. This might make it easier to change the signature of the task later on.

Mutable vs. Immutable Types

• Never put a mutable collection type as a default value of an argument inside the __init__ method of a class. E.g.:

  class Something:
      def __init__(self, foo=[])  # don't do this, a list is a mutable type
  

  This usually leads to unexpected side effects, like this:

  >>> class Something:
  ...     def __init__(self, foo=[]):
  ...         self.foo = foo
  ...
  >>> a = Something()
  >>> b = Something()
  >>> a.foo
  []
  >>> b.foo
  []
  >>> a.foo.append('hello')
  >>> a.foo
  ['hello']
  >>> b.foo
  ['hello']
  

  Prefer immutable collection types, e.g.:

  >>> class SomethingElse:
  ...     def __init__(self, foo=()):
  ...         self.foo = list(foo)
  ...
  >>> a = SomethingElse()
  >>> b = SomethingElse()
  >>> a.foo
  []
  >>> b.foo
  []
  >>> a.foo.append('hello')
  >>> a.foo
  ['hello']
  >>> b.foo
  []
  

• Never return a mutable collection type from a function that is decorated with lru_cache.

  @lru_cache
  def get_best_days():
      return {'Saturday', 'Sunday'}  # don't do this, a set is a mutable type
  

  This can lead to unexpected side effects, because you are altering the return value of the cache, e.g.:

  >>> from functools import lru_cache
  >>>
  >>> @lru_cache
  ... def get_best_days():
  ...     return {'Saturday', 'Sunday'}
  ...
  >>> get_best_days()
  {'Saturday', 'Sunday'}
  >>> best_days = get_best_days()
  >>> best_days.add('Wednesday')
  >>> get_best_days()
  {'Saturday', 'Sunday', 'Wednesday'}
  

  Use an immutable type instead, e.g.:

  >>> from functools import lru_cache
  >>> @lru_cache
  ... def get_best_days():
  ...     return frozenset({'Saturday', 'Sunday'})
  ...
  >>> get_best_days()
  frozenset({'Saturday', 'Sunday'})
  >>> best_days = set(get_best_days())  # cast it to a set if you want to alter the result later
  >>> best_days.add('Wednesday')
  >>> get_best_days()
  frozenset({'Saturday', 'Sunday'})
  

External Python Packages

It’s a balancing act to find the perfect amount of external dependencies. Keep these things in mind:

• Don’t re-invent the wheel! If someone has solved a complex problem before, you don’t need to do it again.
• Don’t be lazy! You don’t need an external Python package for solving a trivial problem. This is not NPM.
• Be careful! Not everything you find on the internet is safe. Double check a project’s status of maintenance, the author and community behind it etc.
• If you are not sure whether to pull in an external package or not, try to evaluate the gain/value vs the the effort of maintenance and risk of dependency that the package will bring.

Remember to verify open source licenses of external packages to make sure commercial use is not restricted or forbidden.

Docstrings

Yes, please! Docstrings are a great way to help manage a long-lived complex code base. We would like to see docstrings for all public classes and functions/methods. But quality goes over quantity. There are valid cases where docstrings are unnecessary or redundant.

• As for the format we follow PEP 257 – Docstring Conventions and PEP 287 – reStructuredText Docstring Format.
• You do not need to add parameters and return values to the docstring. Please use type hints for this.
• A good docstring for a function/method contains one or more of the following points:
  • An instruction of HOW the function is supposed to be used in case it is an interface for other teams
  • A high level summary of WHAT is happening inside a long or complex function to make it unnecessary to read the code
  • Some context about WHY something was implemented in a particular way
• We don’t need docstrings that:
  • Repeat what the code is doing
  • Simply repeat the function’s name phrased as a sentence, for example:

    def add_two_numbers(a: int, b: int) -> int:
        """Adds 2 numbers."""  # don't do this
        return a + b
    

• Docstrings can get outdated. Please try to keep them up to date.
• If a certain detail in your docstring refers to a certain part of your code, it might be better placed as a comment in the code to prevent outdated documentation when the code changes.

Classes

Classes should be declared in the following order:

• attributes
• __init__ method
• other magic methods
• methods and properties
• subclasses

Exceptions to this rule can be made for example for Django classes. In that case, please refer to our Django style guide.