Python (and documentation) code rules

Moving forward
#1

The discussion is to be held here regarding issue #1355.

Hello everyone!

I think it is time for us to think about coding rules and standards. We should be able to work on the Sanic codebase seamlessly regarding the developer, editor, OS and etc.

Some tools / configs I can think of to accomplish this:

And, of course, which rules would we set for the tools we choose. I really find problematic to work on the Sanic codebase as is, without these set of rules to effectively work on.

Also, regarding the docs: isn’t better to work with reStructuredText instead of Markdown? It has a lot of useful extra features in conjunction with Sphinx.

Let me know your thoughts!

#2

I think I brought this up once before … but here are my personal thoughts and preferences:

  • black - It is so simple to use. It does one thing and does it well. I used to think I did a good job keeping my code consistent and clean, but using black really makes a difference.
  • RST - It does make the creation of documentation easier. What a mess the current docs are with part rst and part md. So long as the documentation is built with Sphinx and hosted on RTD, I would prefer rst. Yes, it is the lesser of the two options in terms of its use. But, as @vltr said, there are plenty of features.

One thing that we have talked about (yet not formalized) is also the testing and benchmarking standards. We should make sure that any PR does not decrease our code coverage (ranging between 81-83%).

1 Like
#3

I agree on both black and RST.

  • black will make our code looks the same on every machine; we can even put a task inside tox or even a git hook to trigger black to see if no file needs formatting. Suggested settings for PEP8 compliance:
    [tool.black]
line-length = 79
safe = true
  • RST: it is the natural language of Sphinx and its ecossystem.

Regarding other tools, may I suggest the following rules (I use them in my projects, I’m dyslexic (this is a “pro” argument, believe me) and they all provide some solid results):

  • flake8, with these rules (inside setup.cfg):
    [flake8]
max-line-length = 79
ignore=E501,W503,C901
  • isort (setup.cfg):
    [isort]
atomic=true
default_section = THIRDPARTY
include_trailing_comma = true
known_first_party = sanic
known_third_party = pytest
line_length = 79
lines_after_imports = 2
lines_between_types = 1
multi_line_output = 3
not_skip = __init__.py
  • editorconfig (.editorconfig file):
    root = true

[*]
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
indent_style = space
indent_size = 4
charset = utf-8

[*.{ini,yml}]
indent_style = space
indent_size = 4
charset = utf-8

[LICENSE]
insert_final_newline = false

[Makefile]
indent_style = tab

Since this will basically rewrite the whole codebase, I would also suggest to use a src based directory structure instead of having the directory sanic in the root of the repository, mostly based on this article. For me it works great (and again, this is just a suggestion).

Those are a one-off change (with related changes to tox and etc), but can bring unity to the code style. @sjsadowski, as being one of the current PMs, what do you think?

#4

Put in a PR and see what people have to say. I’m not sure there will be strong opinions against it.

#5

isort configuration, per black documentation:

[isort]
multi_line_output=3
include_trailing_comma=True
force_grid_wrap=0
combine_as_imports=True
line_length=88

black has some good points regarding line_length on its documentation as well (for flake8 and etc). It works nicely with the isort config and respects them.

To use isort inside tox, as a command-line check, you can call it using:

isort --verbose --check-only --diff --recursive src tests setup.py

Also, I really believe that the .editorconfig file would be a good addition.