Code Style Guidelines

Basic concepts:

• Use PyLint as the verification tool for code style
• Start with base rules, and add additional ones every time we run into any ambiguous scenarios
• Aspire to only support rules which can be verified automatically
• Upon PyLint new release, consider the new base rules and possibly add new exceptions rather than changing the code to fit the new base rules

List of pylint builtin messages (rules): http://pylint-messages.wikidot.com/all-messages

List of additional rules:

1. Line width should be capped at 100 rather than the default 79
2. Exceptions
1. Exceptions are a means of breaking out of the normal flow of control of a code block to handle errors or other exceptional conditions.
2. Never use catch-all except: statements, or catch Exception or StandardError, unless you are re-raising the exception or in the outermost block in your thread (and printing an error message). Python is very tolerant in this regard and except: will really catch everything including misspelled names, sys.exit() calls, Ctrl+C interrupts, unittest failures and all kinds of other exceptions that you simply don't want to catch.

3. Power Features

1. It's very tempting to use these "cool" features when they're not absolutely necessary. It's harder to read, understand, and debug code that's using unusual features underneath. It doesn't seem that way at first (to the original author), but when revisiting the code, it tends to be more difficult than code that is longer but is straightforward.
4. Classes
1. If a class inherits from no other base classes, explicitly inherit from object. This also applies to nested classes.
5. Imports
1. Import modules and (and not attributes).
2. Use relative import when possible (while maintaining readability).

3. When importing several modules from the same package always use parenthesis, while breaking lines between each module.

4. When importing several attributes from the same module, the import should be on the same line, separated by commas. 
5. The import section should hold 3 (4 - optional) subsection:
   1. standard libs
   2. 3d party libs
   3. remote aria packages (if for readability reasons, it is better to import directly from aria, and not a relative path). - This is optional.
   4. aria packages (while inside this section the order should be according to the relative import 'distance' - that is, the closer the actual module is, the lower it will be. In effect ... will come before ..). 

   in each subsection, `import X` should come before from A import B, while inside each import and from . import . the order should be according to the length of the line

   for example:

   import time
   from datetime import datetime
   from contextlib import contextmanager
   
   import networkx
   
   from aria import (
       events,
   	logger,
   )
   from aria.workflows.core.task import BaseTask, OperationTask
   
   from ...storage import models
   from .. import exceptions
   from . import translation
   from . import task as engine_task

    

    

6. Naming  
   • if the variable is not a part of the public API, use ‘_’ as a prefix to the variables name.
   • single_trailing_underscore_: used by convention to avoid conflicts with Python keyword, e.g. class_
7. between class declaration and any following member should be exactly one empty line
8. When creating a mixin class, the name should end with ‘mixin’ (not case sensitive) - this will enable ignoring missing members.

TODO: attach an updated PyLint configuration file