Python tools for improving scripting code quality

Ignition
1

Recently I've been trying to improve code quality on my scripts, and I have found some tools that help me towards that goal.

Note

Since projects are now stored in the file system, we can run all of these tools under the $IGNITION_DIR/data/projects/<project>/ignition/script-python folder.

Unfortunately these don't work for scripts inside components.

Suggested software and packages

On my personal blog I have described on two separate posts how I use all of these tools (here, and here), but instead of just reposting I wanted to share with the community how I use it for Ignition projects for work and on a scripting project called incendium which I've shared on Ignition Exchange and its source code at GitHub.

I won't bore you with details on what is code quality, and why it matters, as many people are more qualified, but one interesting article I've read is Python Code Quality: Tools & Best Practices, instead I'll share with you how I use all of these tools.

Disclaimer

I adhere to PEP 8 -- Style Guide for Python Code and PEP 257 -- Docstring Conventions.

So all lines of code are kept to a maximum of 79 characters, and 72 characters for docstrings and comments.

Python 3.9

Python 2 has reached its end-of-life, and pip for Python 2 has done the same. So I wanted to find Python 3 tools I could use on my Python 2 code (or Jython in Ignition).

Commands

If you'd like to know more on the options available for each command, you may find them by running <command> --help or by reading their respective documentation. I'll limit to only posting the commands as I use them.

black

$ black --line-length 79 --target-version py27 .

isort

$ isort --multi-line 3 --profile black --python-version 27 .

flake8

$ flake8 --max-complexity=10 --max-doc-length=72 --ignore=F821,W503

pydocstyle

$ pydocstyle --convention=google .

Configuration files

.flake8

[flake8]
ignore = F821, W503
max-complexity = 10
max-doc-length = 72

.pre-commit-config.yaml

If you are committing your code to source control, I highly recommend using pre-commit. And as its creator said, the order of the tools should be as follows:

  1. Code formatter (black)
  2. Imports sorter (isort)
  3. Checker\Linter (flake8 and pydocstyle)
repos:
  - repo: https://github.com/psf/black
    rev: 21.7b0
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/isort
    rev: 5.9.3
    hooks:
      - id: isort
  - repo: https://github.com/PyCQA/flake8
    rev: 3.9.2
    hooks:
      - id: flake8
  - repo: https://github.com/PyCQA/pydocstyle
    rev: 6.1.1
    hooks:
      - id: pydocstyle
        additional_dependencies:
          - toml

pyproject.toml

[tool.black]
line-length = 79
target-version = ["py27"]

[tool.isort]
profile = "black"
multi_line_output = 3
py_version = 27

[tool.pydocstyle]
convention = "google"

pylint

It's not just a linter that annoys you!

Pylint is a Python static code analysis tool which looks for programming errors, helps enforcing a coding standard, sniffs for code smells and offers simple refactoring suggestions.

While I don't use pylint for pre-commit, I do use it for detecting "code smells" and "bad practices". that's why I listed it as an optional package to install.

And this is the command I use for checking my code:

$ pylint --disable=C0411,E0401,E0602,E1101,R0205,R1725,W0235,W0622,W0707 <dir>

A better option would be to generate a pylintrc and modify as desired.

$ pylint --generate-rcfile > pylintrc

Conclusion

By using these tools (or a subset of them) you might end up with readable code that would be easy for others to understand, enhance, and maintain.

Extras

Other recommendations.

pre-commit.ci

pre-commit ci is a continuous integration service for the pre-commit framework. Currently free for open source projects, but it also offers plans for private repos. Currently it only works on GitHub repos.

7 Likes
2

I’ve been using PyCharm which offers a lot of this functionality as you’re typing, as well as all the other powerful features of an IDE. Or maybe I’m missing the point… Are you still editing the code in ignition and using those tools to parse over it?

3

All of my scripting is done in PyCharm as it does give me code completion on my own libraries. And like you, I used code formatting using PyCharm, but all of these tools allow me to produce code that follows a standard and is well documented.

On top of those there’s a plugin called Sourcery available for PyCharm and vscode.

3 Likes
4

this is really awesome and thanks for taking the time to write it up.

1 Like