sonar-python

To set up the environment and run the serializer, follow these steps:

1. Generate Protobuf files: Navigate to the python-frontend/src/main/protobuf directory and run the protoc command to generate the necessary Python output from symbols.proto.
2. Sync dependencies: Use uv sync to prepare the environment.
3. Execute the serializer: Run the serializer runner using uv run.

# 1. Generate protobuf files
cd python-frontend/src/main/protobuf
protoc -I=. --python_out=../../../typeshed_serializer/serializer/proto_out ./symbols.proto

# 2. Sync dependencies
uv sync

# 3. Run the serializer
uv run python runners/serializer_runner.py

By default, Maven builds skip Typeshed stub generation because pre-generated stubs are committed to the repository. If you need to regenerate them, you have two options:

Option 1: Using Docker (Recommended) Navigate to the serializer directory and run the provided build script:

cd python-frontend/typeshed_serializer
./build-with-docker.sh

Option 2: Using Maven Run the Maven build with the -DgenerateTypeshedStubs flag. This requires Python 3.14 and tox to be installed.

Note: Stub generation is used to create protobuf messages for better type inference.

# Using Maven
mvn clean install -DgenerateTypeshedStubs

To build only the Java Maven modules, run tests, and install the JAR locally without requiring a Python interpreter or generating Typeshed stubs, use the following command. This is the easiest way to build the project.

Prerequisites:

• JDK 11
• Maven 3.0.0 or newer

mvn clean install -P-private

A full build executes the Typeshed serializer script, which generates protobuf messages for Typeshed symbols (standard Python API) and custom symbols (e.g., AWS CDK). This process improves type inference and rule quality.

Prerequisites:

• JDK 11
• Maven 3.0.0 or newer
• Python 3.14
• tox (install via pip install tox)
• Git submodules initialized: git submodule update --init (retrieves Typeshed and SKlearn stubs)
• Sparse checkout for SKlearn stubs:

  cd python-frontend/typeshed_serializer/resources/python-type-stubs
  git sparse-checkout set stubs/sklearn 
  git checkout

All prerequisites must be available in your PATH.

mvn clean install -P-private

Integration tests for sonar-python run the plugin inside a SonarQube instance to verify behavior across various projects and configurations. These tests validate metrics, test result imports, coverage reports, and pylint reports.

Prerequisites

1. Build the plugin: You must first build the sonar-python plugin using Maven with the -P-private profile.
2. Initialize submodules: To run the "ruling" tests, you must initialize and update the git submodules.

Execution Steps

# 1. Build the plugin
mvn clean package -P-private

# 2. Initialize submodules
git submodule init
git submodule update

# 3. Run the tests
cd its/plugin
mvn test -Dsonar.runtimeVersion=LATEST_RELEASE

By default, exceptions encountered during analysis do not stop the process. You can change this behavior using the sonar.internal.analysis.failFast property.

Set sonar.internal.analysis.failFast to true to ensure that any exceptions cause the analysis to fail immediately.

Default value: false

sonar.internal.analysis.failFast=true

In a SonarLint context, you can control the maximum project size for which the symbol table is computed. This helps manage resources for very large projects.

Use sonar.python.sonarlint.maxlines to set the threshold. If a project exceeds this number of lines, the symbol table will not be computed.

Default value: 150000

sonar.python.sonarlint.maxlines=100000

The invoke.config.DataProxy acts as a wrapper around configuration data, providing a dictionary-like interface for accessing nested configuration values using key paths.

It supports standard Python container operations:

• Access: Use __getitem__ (e.g., proxy['key']) or __getattr__ to retrieve values.
• Modification: Use __setitem__ or __setattr__ to update values.
• Deletion: Use __delitem__ or __delattr__ to remove keys.
• Iteration: Supports __iter__, __len__, and __contains__ (the in operator).
• Utility methods: clear(), pop(), popitem(), setdefault(), and update().

You can monitor the performance of the Python analyzer by enabling the sonar.python.performance.measure property. When enabled, the analyzer generates a performance monitoring report.

Use sonar.python.performance.measure.path to specify the destination for this report. The path is relative to the work directory.

Default values:

• sonar.python.performance.measure: false
• sonar.python.performance.measure.path: sonar-python-performance-measure.json

sonar.python.performance.measure=true
sonar.python.performance.measure.path=my-custom-performance-report.json

If mvn install fails with the error Some files do not have the expected license header, you must format the files to include the required headers using the license-maven-plugin.

mvn com.mycila:license-maven-plugin:format

To perform a targeted rebuild of only custom symbols, run the folder_manager utility followed by the typeshed_serializer module using the custom argument.

uv run python -m utils.folder_manager custom && uv run python -m serializer.typeshed_serializer custom

Execute the full test suite using pytest via uv run.

uv run python -m pytest tests/