Qodana 2024.1 Help

Python

All Qodana linters are based on IDEs designed for particular programming languages and frameworks. To analyze Python projects, you can use the following linters:

  • Qodana for Python is based on PyCharm Professional and licensed under the Ultimate and Ultimate Plus licenses,

  • Qodana Community for Python is based on PyCharm Community and licensed under the Community license.

To see the list of supported features, you can navigate to the Supported technologies and features section.

Before your start

Create a Qodana Cloud account. In Qodana Cloud, obtain a project token that will be used by Qodana for identifying and verifying a license.

If your project has external pip dependencies, set them up using the bootstrap key in the qodana.yaml file. For example, if your project dependencies are specified by the requirements.txt file in your project root, in the configuration file add the following line:

bootstrap: pip install -r requirements.txt

Run Qodana

JetBrains IDEs

You can run Qodana in IDE and forward inspection reports to Qodana Cloud for storage and analysis purposes.

  1. In the IDE, navigate to Tools | Qodana | Try Code Analysis with Qodana.

  2. In the Run Qodana dialog, you can configure:

    Configuring Qodana in the Run Qodana dialog

    Click Run for inspecting your code.

  3. In the Server-Side Analysis tool window, see the inspection results.

GitHub Actions

You can run Qodana using the Qodana Scan GitHub action as shown below.

  1. On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.

  2. On the Actions tab of the GitHub UI, set up a new workflow and create the .github/workflows/code_quality.yml file.

  3. To inspect the main branch, release branches and the pull requests coming to your repository, save this workflow configuration to the .github/workflows/code_quality.yml file:

    name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2024.1 env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

More configuration examples are available in the GitHub Actions section.

Jenkins

Make sure that these plugins are installed on your Jenkins instance:

Make sure that Docker is installed and accessible by Jenkins.

If applicable, make sure that Docker is accessible by the jenkins user as described in the Manage Docker as a non-root user section of the Docker documentation.

Create a Multibranch Pipeline project as described on the Jenkins documentation portal.

In the root directory of your project repository, create the Jenkinsfile.

Save this snippet to the Jenkinsfile:

pipeline { environment { QODANA_TOKEN=credentials('qodana-token') } agent { docker { args ''' -v "${WORKSPACE}":/data/project --entrypoint="" ''' image 'jetbrains/qodana-python<-community>:2024.1' } } stages { stage('Qodana') { steps { sh '''qodana''' } } } }

In this configuration, the environment block defines the QODANA_TOKEN variable to invoke the project token.

More configuration examples are available in the Jenkins section.

GitLab CI/CD

Make sure that your project repository is accessible by GitLab CI/CD.

In the root directory of your project, create the .gitlab-ci.yml file and save this configuration in it:

qodana: image: name: jetbrains/qodana-python<-community>:2024.1 entrypoint: [""] cache: - key: qodana-2024.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG fallback_keys: - qodana-2024.1-$CI_DEFAULT_BRANCH- - qodana-2024.1- paths: - .qodana/cache variables: QODANA_TOKEN: $qodana_token script: - qodana --cache-dir=$CI_PROJECT_DIR/.qodana/cache

Here:

  • The cache keyword configures GitLab CI/CD caches to store the Qodana cache, so subsequent runs will be faster,

  • The script keyword runs the qodana command and enumerates the Qodana configuration options described in the Shell commands section,

  • The variables keyword defines the QODANA_TOKEN variable referring to the project token.

You can find more configuration examples in the GitLab CI/CD section.

Local run

Because Qodana linters are distributed in Docker containers, to run Qodana locally you must have Docker installed and running locally. If you are using Linux, you should be able to run Docker under your current non-root user, check the installation page for details.

You can run Qodana locally using Qodana CLI or Docker:

qodana scan \ -e QODANA_TOKEN="<cloud-project-token>" \ -l jetbrains/qodana-python<-community>:2024.1

Here, the QODANA_TOKEN variable refers to the project token.

If you omit the -l option, the Qodana for Python linter will run by default.

To start, pull the image from Docker Hub (only necessary to get the latest version):

docker pull jetbrains/qodana-python<-community>:2024.1

Start local analysis with source-directory pointing to the root of your project and QODANA_TOKEN referring to the project token:

docker run \ -v <source-directory>/:/data/project/ \ -e QODANA_TOKEN="<cloud-project-token>" \ jetbrains/qodana-python<-community>:2024.1

In your browser, open Qodana Cloud to examine analysis results and reconfigure the analysis, see the Inspection report section for details.

Explore analysis results

JetBrains IDEs

You can get the latest Qodana report in your IDE as explained below.

  1. In your IDE, navigate to Tools | Qodana | Log in to Qodana.

  2. In the Settings dialog, click Log in.

    Connecting to Qodana Cloud

    This will redirect you to the authentication page.

  3. Select the Qodana Cloud project to link your local project with.

    Linking the project to Qodana Cloud
  4. By enabling the Always load most relevant Qodana report option, you get actual reports automatically retrieved from Qodana Cloud.

    Enabling to load the most relevant reports

    In this case, the IDE will search and fetch from Qodana Cloud the report that has the revision ID corresponding to the current revision ID (HEAD). If this report was not found, the IDE will select the previous report with the revision closest to the current revision ID (HEAD). Otherwise, the IDE retrieves the latest available report from Qodana Cloud.

  5. In the Server-Side Analysis tool window, view analysis results.

Qodana Cloud

Once Qodana analyzed your project and uploaded the analysis results to Qodana Cloud, in Qodana Cloud navigate to your project and study the analysis results report.

Analysis report example

To learn more about Qodana report UI, see the Inspection report section.

Extend Qodana configuration

Adjust the scope of analysis

Out of the box, Qodana provides two predefined profiles hosted on GitHub:

  • qodana.starter is the default profile and a subset of the qodana.recommended profile,

  • qodana.recommended is best for running in CI/CD pipelines and mostly implements the default PyCharm profile, see the PyCharm documentation for details.

You can customize Qodana profiles using configurations in YAML and XML formats.

For example, you can enable JavaScript and TypeScript inspections by overriding the qodana.recommended profile as shown below.

  1. In the project directory, create a qodana.yaml file and save this profile configuration to it:

    name: "Enabling JavaScript and TypeScript" baseProfile: qodana.recommended inspections: - group: "category:JavaScript and TypeScript" # Specify the inspection category enabled: true # Enable the JavaScript and TypeScript category
  2. In the qodana.yaml file, save this configuration to enable your profile:

    profile: path: <relative-path-to-yaml-config-file>

To learn more about configuration basics, visit the Configure Qodana your way section. Complete guides are available in the Custom YAML profiles and Custom XML profiles sections.

Enable the baseline

You can skip analysis for specific problems using the baseline feature.

JetBrains IDEs

  1. In your IDE, navigate to the Problems tool window.

  2. In the Problems tool window, click the Server-Side Analysis tab.

  3. On the Server-Side Analysis tab, click the Try Locally button.

  4. In the dialog that opens, expand the Advanced configuration section and specify the path to the baseline file, and then click Run.

GitHub Actions

This snippet contains the args: --baseline,qodana.sarif.json line that specifies the path to the SARIF-formatted file containing a baseline:

name: Qodana on: workflow_dispatch: pull_request: push: branches: # Specify your branches here - main # The 'main' branch - 'releases/*' # The release branches jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2024.1 with: args: --baseline,qodana.sarif.json env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

Jenkins

The stages block contains the --baseline <path/to/qodana.sarif.json> line that specifies the path to the SARIF-formatted file containg information about a baseline:

pipeline { environment { QODANA_TOKEN=credentials('qodana-token') } agent { docker { args ''' -v "${WORKSPACE}":/data/project --entrypoint="" ''' image 'jetbrains/qodana-python<-community>:2024.1' } } stages { stage('Qodana') { steps { sh ''' qodana \ --baseline <path/to/qodana.sarif.json> ''' } } } }

GitLab CI/CD

You can use the --baseline <path/to/qodana.sarif.json> line in the script block to invoke the baseline feature.

qodana: image: name: jetbrains/qodana-<linter> entrypoint: [""] cache: - key: qodana-2024.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG fallback_keys: - qodana-2024.1-$CI_DEFAULT_BRANCH- - qodana-2024.1- paths: - .qodana/cache variables: QODANA_TOKEN: $qodana_token - script: - qodana --baseline <path/to/qodana.sarif.json> --results-dir=$CI_PROJECT_DIR/.qodana/results --cache-dir=$CI_PROJECT_DIR/.qodana/cache artifacts: paths: - qodana/report/ expose_as: 'Qodana report'

Local run

In these snippets, the --baseline option configures the path to the SARIF-formatted file containin a baseline:

qodana scan \ -v <path_to_baseline>:/data/base/ \ -e QODANA_TOKEN="<cloud-project-token>" \ -l jetbrains/qodana-python<-community>:2024.1 \ --baseline /data/base/qodana.sarif.json
docker run \ -v <source-directory>/:/data/project/ \ -v <path_to_baseline>:/data/base/ \ -e QODANA_TOKEN="<cloud-project-token>" \ jetbrains/qodana-python<-community>:2024.1 \ --baseline /data/base/qodana.sarif.json

Enable the quality gate

You can configure quality gates for the total number of project problems, specific problem severities, and code coverage by saving this snippet to the qodana.yaml file:

failureConditions: severityThresholds: any: 50 # Total number of problems in all severities critical: 1 # Severities high: 2 moderate: 3 low: 4 info: 5 testCoverageThresholds: fresh: 6 # Fresh code coverage total: 7 # Total percentage

Analyze pull requests

GitHub Actions

In GitHub Actions, --diff-start can be omitted because it will be added automatically while running Qodana, so you can follow this procedure:

  1. On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.

  2. On the Actions tab of the GitHub UI, set up a new workflow and create the .github/workflows/code_quality.yml file.

  3. Add this snippet to the .github/workflows/code_quality.yml file:

        name: Qodana     on:       workflow_dispatch:       pull_request:       push:         branches: # Specify your branches here           - main # The 'main' branch           - 'releases/*' # The release branches     jobs:       qodana:         runs-on: ubuntu-latest         permissions:           contents: write           pull-requests: write           checks: write         steps:           - uses: actions/checkout@v3             with:               ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit               fetch-depth: 0 # a full history is required for pull request analysis           - name: 'Qodana Scan'             uses: JetBrains/qodana-action@v2024.1             env:               QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}

GitLab CI/CD

In the root directory of your project, save the .gitlab-ci.yml file containing the following snippet:

qodana: image: name: jetbrains/qodana-python<-community>:2024.1 entrypoint: [""] cache: - key: qodana-2024.1-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG fallback_keys: - qodana-2024.1-$CI_DEFAULT_BRANCH- - qodana-2024.1- paths: - .qodana/cache variables: QODANA_TOKEN: $qodana_token script: - > qodana --diff-start=$CI_MERGE_REQUEST_TARGET_BRANCH_SHA \ --results-dir=$CI_PROJECT_DIR/.qodana/results \ --cache-dir=$CI_PROJECT_DIR/.qodana/cache artifacts: paths: - .qodana/results expose_as: 'Qodana report'

Here, the --diff-start option specifies a hash of the commit that will act as a base for comparison.

Local run

To analyze changes in your code, employ the --diff-start option and specify a hash of the commit that will act as a base for comparison:

qodana scan \    -e QODANA_TOKEN="<cloud-project-token>" \    -l jetbrains/qodana-python<-community>:2024.1 \    --diff-start=<GIT_START_HASH>
docker run \    -v $(pwd):/data/project/ \    -e QODANA_TOKEN="<cloud-project-token>" \    jetbrains/qodana-python<-community>:2024.1 \    --diff-start=<GIT_START_HASH>

Supported technologies and features

This table contains the list of technologies supported by both linters.

Programming languages

Python

Frameworks and libraries

Django

Google App Engine

Jupyter

Pyramid

Databases and ORM

MongoJS

MySQL

Oracle

PostgreSQL

SQL

SQL Server

Markup languages

CSS

HTML

JSON and JSON5

RELAX NG

XML

YAML

Scripting languages

Shell script

Here is the list of Qodana features supported per each linter.

Feature

Qodana Community for Python

Qodana for Python

Baseline

Quality gate

Code coverage

License audit

Quick-fix

Vulnerability checker

Last modified: 17 May 2024