CONTRIBUTING.md

Contribution Guidelines

Code style

Code style we follow

The Python code style used by BioThings projects generally folllows PEP8.

In addition to the standards outlined in PEP 8, we have a few guidelines:

• Max line length

  Line-length can exceed 79 characters, we set max-line-length to 120 to ignore most of line-length warning, But try to keep the line-length within 100 characters.

• Import order and grouping

  Imports at the beginning of the code should be grouped into three groups in this order:

  1. Python's builtin modules
  2. Third-party modules
  3. The modules from this project Leave an empty line to separate each import group.

  The only exception is import logging, where we often need to add logging settings immediately after import. We recommend to put this logging block at the end of the imports.

  See this code as an example.

  Note: You can use isort package or its vscode extension to format import order and grouping easily.

• docstring format

  A typical docstring should follow this Google style:

  """[Summary]
  
  Args:
      path (str): The path of the file to wrap
      field_storage (FileStorage): The :class:`FileStorage` instance to wrap
      temporary (bool): Whether or not to delete the file when the File
        instance is destructed
  
  Returns:
      BufferedFileStorage: A buffered writable file descriptor
  """
  

  This is enabled by using sphinx.ext.napoleon extension in the docs/conf.py file.

  Alternatively, a default sphinx docstring style is also supported:

  """[Summary]
  
  :param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
  :type [ParamName]: [ParamType](, optional)
  ...
  :raises [ErrorType]: [ErrorDescription]
  ...
  :return: [ReturnDescription]
  :rtype: [ReturnType]
  """
  

  See examples and additional details here.

Please also check this CODING_STYLE_EXAMPLES.md doc for some common styling issues we should avoid.

In some particular cases, the style guidelines may not be suitable. Use your own best judgment, and also raise the issue with the team members for their opinions. Read more about when to ignore a particular guideline from PEP8 doc.

Check your code style

We recommand to setup fourmat as your code-style checker/formmater with your editor. Fix the styling issue before you push the code to the github. fourmat conviniently combines three code-styling tools: flake8, black and isort.

We have already included config files for code styling check and formatting: .flake8 for flake8 and pyproject.toml for black and isort, so that we all use the same settings when run fourmat.

You can check out more config options for each tool:

• flake8 configuration
• black configuration
• isort configuration

run fourmat in CLI

• install fourmat

  pip install fourmat

• check code

  fourmat check <file_or_folder>

• format code

  fourmat fix <file_or_folder>

setup black and isort formatter in VSCode

• install both Black Formatter and isort vscode extensions

• setup auto formatting on file dave:

  Add this settings to your vscode's settings.json file (up to you to set it at the project, user or workspace level):

  "[python]": {
      "editor.defaultFormatter": "ms-python.black-formatter",
      "editor.formatOnSave": true,
      "editor.codeActionsOnSave": {
          "source.organizeImports": true
      },
  },
  "isort.args":["--profile", "black"],

Ignore some code-styling check errors

For some particular cases, if you think the reported errors are false alerts, you can ignore specific errors/warnings at the specific code instead. A few common examples below:

# ignore one or muliple errors
example = lambda: 'example'  # noqa: E731

example = lambda: 'example'  # noqa: E731,E123

# ignore all errors, but not recommended, better to include specific errors
example = lambda: 'example'  # noqa

# ignore the whole file if this is at the top:
# flake8: noqa

Other recommended but not required style checks

You can always do extra checks on your code before commits. Some checkers may give you extra code style suggestions which will make your code more readable or more efficient (or not). Use your own judgement to decide to use it or not. For beginners, you may found it could be a good learning process to know some Python syntax you may not know before.

• Extra flake8 plugins

  You may find these flake plugins can be very useful (install them using pip):

  pip install flake8-builtins flake8-comprehensions flake8-logging-format pep8-naming
  

• PyLint

  pip install pylint
  

  When there are conflicts with our style guidelines above from these extra checkers, follow our own rules.

Setup pre-commit

Optionally, you can also setup pre-commit for your local repository. We have included a .pre-commit-config.yaml file in this repository. You just need to install it on your local git repository:

pre-commit install

Some useful references

• fourmat: Flake8 + Black + isort = ❤️
• The list of Flake8 rules
• The Black code style
• requests code style
• Google's Python code style guide