azure-sdk-for-python/doc/dev/pylint_checking.md

Python SDK Pylint Guide

Cheat sheet for the Python SDK pylint general guidelines for your client library

Table of contents

• General Guidance
  • What is Pylint?
  • How to run Pylint?
• Ignoring Pylint Checkers
• Pylint Warnings and Where to Find Them
  • Next Pylint
• How to Prepare your SDK?

General Guidance

What is pylint?

Pylint is a set of (mostly) astroid based checkers that run static analysis on your code and check that your formatting aligns with Python's style guide (i.e PEPs).

In the Azure SDK for Python repository, in addition to the standard pylint library, there are also custom checkers within the azure-pylint-guidelines-checker package that help to customize our libraries to the standards described in the Azure SDK for Python Guidelines.

How to run Pylint?

One way to run pylint is to run at the package level with tox:

.../azure-sdk-for-python/sdk/eventgrid/azure-eventgrid>tox run -e pylint -c ../../../eng/tox/tox.ini --root .

If you don't want to use tox, you can also install and run pylint on its own:

• If taking this approach, in order to run with the pylintrc formatting and the custom pylint checkers you must also install the custom checkers and SET the pylintrc path.

   pip install pylint
   pip install azure-pylint-guidelines-checker --index-url="https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-python/pypi/simple/"
  
   .../azure-sdk-for-python>SET PYLINTRC="./pylintrc"
   .../azure-sdk-for-python>pylint ./sdk/eventgrid/azure-eventgrid
  

  Note that you may see different errors if running a different version of pylint or azure-pylint-guidelines-checker than the one in CI.

Ignoring Pylint Checkers

• If there is a pylint checker within your SDK that you wish to ignore for that specific scenario (i.e protected-access) you can ignore it with a comment on the offending line.

  # pylint:disable=protected-access

• (Not Recommended) Another way to disable a checker is by ignoring the entire package in the pyproject.toml.

Pylint Warnings and Where to Find Them

Information on the custom pylint checkers resides here. This table, provides information on each custom check and how to resolve them.

In addition to being a part of the CI, the custom pylint checkers are also integrated into ApiView. If there are unaddressed warnings, they will show as system comments.

Next Pylint

There is now a new step on the CI pipeline called Run Pylint Next. This is merely a duplicate of the Run Pylint step with the exception that Run Pylint Next uses the latest version of pylint and the latest version of the custom pylint checkers.

This next-pylint environment can also be run locally through tox:

tox run -e next-pylint -c ../../../eng/tox/tox.ini --root <path to python package>

The errors generated by the Run Pylint Next step will not break your weekly test pipelines, but make sure to fix the warnings so that your client library is up to date for the next pylint release.

How to prepare your SDK for a new pylint update?

Check each client library's Run Pylint Next output in the test-weekly CI pipeline. If there is no corresponding test-weekly pipeline, run next-pylint locally with tox as described in How to run Pylint?. In order to ensure that the SDK pipeline will not break when pylint is updated, make sure to address all pylint warnings present.