Python

Supported Versions

  • Python 3.X
  • Python 2.X

Language-Specific Properties

Discover and update the Python-specific Administration > General Settings > Python.

Pylint

Pylint is an external static source code analyzer, it can be used in conjunction with SonarSource Python analyzer.

You can enable Pylint rules directly in your Python Quality Profile. Their rule keys start with "Pylint:".

Once the rules are activated you should run Pylint and import its report:

pylint <module_or_package> -r n --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" > <report_file>

Then pass the generated report path to analysis via the sonar.python.pylint.reportPath property.

WARNING: Future breaking changes for Pylint issues import

Pylint issues will soon be imported as external issues. You can expects multiple improvements from this:

  • It will simplify your configuration. Activating or disabling a rule in Pylint configuration will be enough. Currently you need to activate these rules in both SonarQube and Pylint.
  • You will be able to use Pylint plugins.

There will however be a few breaking changes:

  • It will not be possible to change issues' resolution (fixed/removed/won't fix) in SonarQube. Every issue reported by Pylint will be displayed as open. In order to remove an issue you will need to either change the code or disable the rule in your Pylint configuration or in your code.
  • Pylint issues will lose their history, resolution, assigned people and comments.
  • SonarQube's Python analyzer won't execute Pylint anymore. This feature was deprecated and will be removed.

How to prepare for these changes

If you closed Pylint issues in SonarQube you need to instead add pragma comments in your code. If you have many closed Pylint issues you can list them using SonarQube API.

If you let SonarQube execute Pylint you need to instead execute it yourself, generate a report and import the report via the parameter sonar.python.pylint.reportPath.

Custom Rules

Overview

The Python analyzer parses the source code, creates an Abstract Syntax Tree (AST) and then walks through the entire tree. A coding rule is a visitor that is able to visit nodes from this AST.

As soon as the coding rule visits a node, it can navigate its children and log issues if necessary.

Writing a Plugin

Custom rules for Python can be added by writing a SonarQube Plugin and using Python analyzer APIs. Here are the steps to follow:

Create a SonarQube Plugin

  • create a standard SonarQube plugin project.
  • attach this plugin to the SonarQube Python analyzer through the pom.xml:

    • add the dependency to the Python analyzer.
    • add the following line in the sonar-packaging-maven-plugin configuration.

      <requirePlugins>python:2.0-SNAPSHOT</requirePlugin>
      
  • implement the following extension points:

  • declare the RulesDefinition as an extension in the Plugin extension point.

Implement a Rule

  • create a class that will hold the implementation of the rule, it should:

    • extend PythonCheckTree or PythonSubscriptionCheck.
    • define the rule name, key, tags, etc. with Java annotations.
  • declare this class in the RulesDefinition.

Example Plugin

To get started a sample plugin can be found here: python-custom-rules.

Implementation Details

Using PythonCheckTree

To explore a part of the AST, override a method from the PythonCheckTree. For example, if you want to explore "if statement" nodes, override PythonCheckTree#visitIfStatement method that will be called each time an ifStatement node is encountered in the AST.

When overriding a visit method, you must call the super method in order to allow the visitor to visit the children of the node.

Using PythonSubscriptionCheck

To explore a part of the AST, override PythonSubscriptionCheck#initialize and call the SubscriptionCheck.Context#registerSyntaxNodeConsumer with the Tree#Kind of node you want to visit. For example, if you want to explore "if statement" you should register to the kind Tree#Kind#IF_STATEMENT and then provide a lambda that will consume a SubscriptionContext to act on such ndoes.

Create Issues

From the check, issue can be created by calling SubscriptionContext#addIssue method or PythonCheckTree#addIssue method.

Testing Checks

To test custom checks you can use method PythonCheckVerifier#verify. Don't forget to add the testkit dependency to access this class from your project :

  <dependency>
      <groupId>org.sonarsource.python</groupId>
      <artifactId>python-checks-testkit</artifactId>
      <version>${project.version}</version>
      <scope>test</scope>
  </dependency>

You should end each line having an issue with a comment in the following form:

# Noncompliant {{Message}}

Comment syntax is described here.

Related Pages