SonarScanner for Python (Beta)

pysonar-scanner is a wrapper around SonarScanner CLI, available on PyPI.

Prerequisite

• Python 3.8 or above

Installing the SonarScanner for Python

To install with pip, run the following command: 

pip install pysonar-scanner

Once installed, you can configure the analysis and run the scanner from the command line to perform an analysis. It assumes an existing SonarCloud project.

Using the SonarScanner for Python

Setting the analysis properties

For the analysis to run, you'll need to define analysis properties. There are multiple ways of providing them, described below in descending order of priority:

• Through CLI arguments to the pysonar-scanner command
• Under the [tool.sonar] key of the pyproject.toml file
• Through common properties extracted from the pyproject.toml file
• In a dedicated sonar-project.properties file
• Through environment variables

Through CLI arguments

Analysis properties can be provided as CLI arguments to the pysonar-scanner command. They follow the same convention as when running the SonarScanner CLI directly. This means that analysis properties provided that way should be prepended with -D, for example:

pysonar-scanner -Dsonar.token=myAuthenticationToken 

You can use all the arguments allowed by the SonarScanner CLI.

With a pyproject.toml file

Inside a pyproject.toml, Sonar analysis properties can be defined under the tool.sonar table.

[tool.sonar]
# must be unique in a given SonarCloud instance
projectKey=my:project

# --- optional properties ---
# defaults to project key
#projectName=My project
# defaults to 'not provided'
#projectVersion=1.0
 
# Path is relative to the pyproject.toml file. Defaults to .
#sources=.
 
# Encoding of the source code. Default is default system encoding
#sourceEncoding=UTF-8

For a list of analysis parameters, see Analysis parameters.

In the pyproject.toml file, the prefix sonar. for parameter keys should be omitted. For example, sonar.scm.provider in the documentation will become scm.provider in the pyproject.toml file.

By default, the scanner expects the pyproject.toml file to be present in the current directory. However, its path can be provided manually through the toml.path (PYSCAN-40) CLI argument as well as through the sonar.projectHome argument. For example:

pysonar-scanner -Dtoml.path="path/to/pyproject.toml"

Or:

pysonar-scanner -Dsonar.projectHome="path/to/projectHome"

Through project properties extracted from the pyproject.toml file

When a pyproject.toml file is available, it's possible to set the -read-project-config flag to allow the scanner to deduce analysis properties from the project configuration.

This is currently supported only for projects using poetry.

The Sonar scanner will then use the project name and version defined through Poetry, they won't have to be duplicated under a dedicated tool.sonar section.

With a sonar-project.properties file

The analysis can be configured with a sonar-project.properties file, exactly like when you analyze with SonarScanner CLI:

# must be unique in a given SonarCloud instance
sonar.projectKey=my:project

# --- optional properties ---

# defaults to project key
#sonar.projectName=My project
# defaults to 'not provided'
#sonar.projectVersion=1.0
 
# Path is relative to the sonar-project.properties file. Defaults to .
#sonar.sources=.
 
# Encoding of the source code. Default is default system encoding
#sonar.sourceEncoding=UTF-8

Through environment variables

You can use environment variables on the CI/CD host to define analysis parameters. See Analysis parameters to see which parameters can be set through environment variables. For example:

export SONAR_HOST_URL="http://localhost:9000"
pysonar-scanner 

Installing from testPyPI

To install the latest pre-released version of SonarScanner for Python. Execute the following command:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pysonar-scanner