Python

You can analyze your Python projects using the Qodana for Python linter based on PyCharm Professional and licensed under the Ultimate and Ultimate Plus licenses, and the Qodana Community for Python linter based on PyCharm Community and licensed under the Community license. To learn more about Qodana licenses, navigate to the Pricing Model section. To see the list of supported features, you can navigate to the Supported technologies and features section.

Before your start

Qodana for Python requires a valid Qodana license for running, and it can be identified and verified using a project token generated in Qodana Cloud. If you use the Qodana Community for Python linter, the project token is optional.

If your project has external pip dependencies, set them up using the bootstrap key in the YAML-formatted configuration 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

Run Qodana locally

By default, you can run Qodana using Qodana CLI. To run it, you must have Docker or Podman 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.

Alternatively, you can use the Docker commands from the Docker image tab.

            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.

Run Qodana in CI/CD pipelines

GitHub Actions

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

On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.
On the Actions tab of the GitHub UI, set up a new workflow and create the .github/workflows/code_quality.yml file.
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:

Docker and Docker Pipeline are required for running Docker images
git is required for git operations in Jenkins projects

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.

Explore analysis results

View results in 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.

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

Receive analysis results in PyCharm

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

In your IDE, navigate to Tools | Qodana | Log in to Qodana.
In the Settings dialog, click Log in.
This will redirect you to the authentication page.
Select the Qodana Cloud project to link your local project with.
By enabling the Always load most relevant Qodana report option, you get actual reports automatically retrieved from Qodana Cloud.
In this case, PyCharm 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, PyCharm will select the previous report with the revision closest to the current revision ID (HEAD). Otherwise, PyCharm retrieves the latest available report from Qodana Cloud.
In the Server-Side Analysis tool window, view analysis results.

Using the Server-Side Analysis tool window of PyCharm, you can view Qodana reports and navigate to the code fragments containing such problems.

The upper part of the Server-Side Analysis tool window contains information about the project and branch names, the analysis date, and the number of problems. The left part contains several buttons.

Functionalities of the Server-Side Analysis tool window

This table explains each button from top to bottom:

Button	Description
Close Report	Close the report that was previously opened
Refresh Report	Download the updated version of the report from Qodana Cloud. This requires that you first link your project with Qodana Cloud
Log in to Qodana / Logged in to Qodana	Log in Qodana Cloud, or log out. This action is a prerequisite for linking your project with Qodana Cloud-based reports
Link project with Cloud / Linked with Cloud	Link your project with a specific Qodana Cloud-based project, or unlink it. This requires that you first log in to Qodana Cloud
View Options	Filter out code issues by their severity and configure their sorting. When no grouping or sorting options are selected, the issues are listed in the order they appear in the file. You can also filter all issues by the baseline
Open Editor Preview	Open the preview pane to view the selected issue in its source context. This preview lets you change the code and apply available quick-fixes
Expand All	Expand all nodes to see all issues in the expanded form
Collapse All	Collapse all nodes that were previously expanded
Show Qodana in Browser	Open the report using your default browser
Other	Functionalities from the Tools \| Qodana menu

Extend Qodana configuration

Adjust the scope of analysis

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

The qodana.starter profile is the default profile that triggers the 3-phase analysis. This is a subset of the qodana.recommended profile,
The qodana.recommended profile is suitable for running in CI/CD pipelines and mostly implements the default PyCharm profile, see the PyCharm documentation for details.

You can configure Qodana profiles in YAML and XML formats.

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

In the project directory, create a 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
In the YAML-formatted 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 use the baseline feature to compare your current code with its baseline state and see new, unchanged, and resolved problems:

            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
        

Here, the -v <path_to_baseline>:/data/base/ line mounts the directory containing the SARIF-formatted baseline file to the /data/base directory of the Qodana Docker image. The QODANA_TOKEN variable refers to the project token.

                    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 }}
                

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

            docker run \
               -v $(pwd):/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
        

In this snippet, the -v <path_to_baseline>:/data/base/ line mounts the directory containing the SARIF-formatted baseline file to the /data/base directory of the Qodana Docker image. The --baseline option specifies the path to the baseline file from the Docker filesystem. The QODANA_TOKEN variable refers to the project token.

In your IDE, navigate to the Problems tool window.
In the Problems tool window, click the Server-Side Analysis tab.
On the Server-Side Analysis tab, click the Try Locally button.
In the dialog that opens, expand the Advanced configuration section and specify the path to the baseline file, and then click Run.

This animation shows how the baseline feature works.

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>
                '''
            }
        }
    }
}

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.

Enable the quality gate

Using the YAML format, you can configure quality gates for the total number of project problems, specific problem severities, and code coverage.

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

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>
        

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

On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.
On the Actions tab of the GitHub UI, set up a new workflow and create the .github/workflows/code_quality.yml file.
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 }}

Make sure that your project repository is accessible by 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'
        

            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 the Qodana for Python and Qodana Community for Python linters.

Programming languages	Python
Markup languages	CSS HTML JSON and JSON5 RELAX NG XML YAML
Scripting languages	Shell script
Databases and ORM	MongoJS MySQL Oracle PostgreSQL SQL SQL Server
Frameworks and libraries	Django Google App Engine Jupyter Pyramid

This table shows Qodana features supported by both linters.

Feature	Qodana Community for Python	Qodana for Python
Baseline	✔	✔
Quality gate	✔	✔
Code coverage	❌	✔
License audit	❌	✔
Quick-fix	❌	✔
Vulnerability checker	❌	✔

Last modified: 03 May 2024