deluge/docs/source/contributing/code.md

Contributing code

Basic requirements and standards

• A new ticket is required for bugs or features. Search the ticket system first, to avoid filing a duplicate.
• Ensure code follows the syntax and conventions.
• Code must pass tests. See [testing.md] for information on how to run and write unit tests.
• Commit messages are informative.

Pull request process:

• Fork us on github.
• Clone your repository.
• Create a feature branch for your issue.
• Apply your changes:
  • Add them, and then commit them to your branch.
  • Run the tests until they pass.
  • When you feel you are finished, rebase your commits to ensure a simple and informative commit log.
• Create a pull request on github from your forked repository.
  • Verify that the tests run by Travis-ci are passing.

Syntax and conventions

Code formatters

We use two applications to automatically format the code to save development time. They are both run with pre-commit.

Black

• Python

Prettier

• Javascript
• CSS
• YAML
• Markdown

Common

• Line length: 79 chars.
• Indent: 4 spaces, no tabs.
• All code should use 'single quotes'.

Python

We follow PEP8 and Python Code Style which is adhered to with Black formatter.

• Code '''must''' pass flake8 (w/[https://pypi.python.org/pypi/flake8-quotes flake8-quotes]), [https://pypi.python.org/pypi/isort isort] and [http://www.pylint.org/ Pylint] source code checkers.

  flake8 deluge isort -rc -df deluge pylint deluge pylint deluge/plugins/*/deluge/

• Using the [http://pre-commit.com/ pre-commit] app can aid in picking up issues before creating git commits.

Strings and bytes

To prevent bugs or errors in the code byte strings (str) must be decoded to strings (unicode strings, unicode) on input and then encoded on output.

Notes:

• PyGTK/GTK+ will accept str (utf8 encoded) or unicode but will only return str. See [http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html GTK+ Unicode] docs.
• There is a bytearray type which enables in-place modification of a string. See Python Bytearrays
• Python 3 renames unicode to str type and byte strings become bytes type.

Javascript

• Classes should follow the Ext coding style.
• Class names should be in !CamelCase
• Instances of classes should use camelCase.

Path separators

• All relative path separators used within code should be converted to posix format /, so should not contain \ or \\. This is to prevent confusion when dealing with cross-platform clients and servers.

Docstrings

All new docstrings must use Napoleon Google Style with old docstrings eventually converted over.

Google Style example:

def func(arg):
   """Function purpose.

   Args:
       arg (type): Description.

   Returns:
      type: Description. If the line is too, long indent next
         line with three spaces.
   """
   return

See complete list of [http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections supported headers].

Verify that the documentation parses correctly with:

python setup.py build_docs