Using pylint for local development

Using pylint with IDAES for local development

Prerequisites

Clone the IDAES repo and install IDAES in development mode. The following commands assume that a Conda environment named my-idaes-env is being used.

conda activate my-idaes-env
git clone https://github.com/IDAES/idaes-pse && cd idaes-pse
pip install -r requirements-dev.txt

Verify that IDAES and pylint have been installed correctly:

idaes --version
pylint --version

• IMPORTANT Unless otherwise specified, these commands should be run in the root directory of your local clone of the IDAES repository (i.e. where the setup.py file is located)

Using pylint from the command line

Run pylint using the IDAES-specific configuration:

pylint --rcfile=.pylint/pylintrc idaes/

Run pylint using the IDAES-specific configuration, disabling all checks except for errors:

pylint --rcfile=.pylint/pylintrc  --disable=W,C,R,I idaes/

Run pylint using the IDAES-specific configuration, disabling all checks except for errors, and creating a machine-readable report of all pylint messages in addition to the real-time display:

pylint --rcfile=.pylint/pylintrc  --disable=W,C,R,I --output-format=idaes_reporters.MultiReporter idaes/

• NOTE At the time of writing, this is the same configuration being run on GitHub as part of the check suite for PRs
  • Refer to the GitHub Actions configuration in .github/actions/pylint/action.yml for more details

Running pylint on the idaes/ package directory should take 3-6 minutes on a normal personal computer.

• TIP With the idaes_reporters.MultiReporter formatter, each file being analyzed will be displayed during the run, irrespective of whether errors where found inside it.

• TIP Specify a subdirectory or a single file to avoid analyzing the entire codebase:

  pylint --rcfile=.pylint/pylintrc  --disable=W,C,R,I --output-format=idaes_reporters.MultiReporter idaes/apps/my_package
  pylint --rcfile=.pylint/pylintrc  --disable=W,C,R,I --output-format=idaes_reporters.MultiReporter idaes/apps/my_package/my_module.py

Integrating pylint with IDEs or text editors

The pylint configuration required to make pylint compatible with the IDAES codebase is designed to make it possible for it to be integrated with IDEs/text editors that support pylint, such as PyCharm or Visual Studio Code (VSCode).

At a high level, the key step is to customize within the IDE/editor's settings the command line options/flags with which pylint is invoked by the IDE/editor. The most important option to set is the --rcfile=.pylint/pylintrc flag, since without it there will be hundreds of false-positive errors being reported by pylint.

Visual Studio Code

• Open the command panel (Ctrl+Shift+P) and search for "Preferences: open settings (UI)"
• In the settings interface, search for python.linting.pylintArgs
• Add the following items:
  • --rcfile=.pylint/pylintrc
  • --disable=W,C,R,I (optional)
    • If this flag is not specified, a potentially large number of non-error messages will be displayed
• Depending on your specific workspace configuration, it might be necessary to customize the value of python.linting.cwd as well specifying the root directory of the local clone of IDAES

PyCharm

• Follow the steps here, adapting the steps described above to set the --rcfile=... and --disable=... flags
• Depending on the project configuration, it might be necessary to disable other built-in checks (i.e. so that the IDAES-compatible pylint configuration is the only check active in the project)