Metadata-Version: 2.4
Name: pysonar
Version: 1.10.0.5888
Summary: Sonar Scanner for the Python Ecosystem
License-Expression: LGPL-3.0-only
License-File: LICENSE
Keywords: sonar,sonarqube,sonarcloud,cleancode
Author: [Code Quality] Data & ML Squad
Author-email: quality.data-ml@sonarsource.com
Requires-Python: >=3.10
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: certifi (>=2026.10.19)
Requires-Dist: jproperties (>=2.1,<3)
Requires-Dist: requests (>=2.32,<3)
Requires-Dist: tomli (>=2.0,<3)
Requires-Dist: urllib3 (>=2.8.0,<3)
Project-URL: Homepage, https://github.com/SonarSource/sonar-scanner-python
Project-URL: Repository, https://github.com/SonarSource/sonar-scanner-python
Description-Content-Type: text/markdown

<!-- Sonar Marketing hosts these approved brand assets on its Kentico Kontent CDN (assets-eu-01.kc-usercontent.com). Shared URLs are intentional; consult Marketing before replacing them. -->
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://assets-eu-01.kc-usercontent.com/ef593040-b591-0198-9506-ed88b30bc023/a23fc7ba-23f0-489a-829d-ed88c0748521/Sonar_Logo_Dark%20Backgrounds.svg">
    <img src="https://assets-eu-01.kc-usercontent.com/ef593040-b591-0198-9506-ed88b30bc023/82c13eba-d95c-4bb8-8007-7ce77c14e043/Sonar_Logo_Light%20Backgrounds.svg" alt="Sonar logo" width="400">
  </picture>
</p>

<!-- sonar-marketing:start -->
<!-- Marketing maintains this section. For wording changes, consult the relevant Product Marketing Manager (PMM). Repository maintainers review accuracy and merge changes. -->

# SonarScanner for Python (pysonar)

SonarScanner for Python runs SonarQube analysis from Python projects. It is published on PyPI as `pysonar`; use the installation and configuration instructions below to run an analysis.

To learn more about Sonar products, visit the [Sonar website](https://www.sonarsource.com/products/sonarqube/).

<!-- sonar-marketing:end -->

# Requirements

 - SonarQube v10.6 or above
 - Python 3.9 or above

# Installation

Install with pip:
```
pip install pysonar
```

# Usage

Once installed, the `pysonar` scanner can be run from the command line to perform an analysis.
It assumes a running SonarQube server or a project configured on SonarCloud.

## Setting up analysis properties

In order for the analysis to run, analysis properties need to be defined. 
There are multiple ways of providing these properties, described below in descending order of priority:

1. Through CLI arguments to the `pysonar` command
2. Environment variables for individual properties (e.g. `SONAR_TOKEN`, `SONAR_VERBOSE`, `SONAR_HOST_URL`, ...)
3. Generic environment variable `SONAR_SCANNER_JSON_PARAMS` 
4. Under the `[tool.sonar]` key of the `pyproject.toml` file
5. In a dedicated `sonar-project.properties` file
6. Through common properties extracted from the `pyproject.toml`

### Through CLI arguments

Analysis properties can be provided as CLI arguments to the `pysonar` command.
They can be provided in a similar way as when running the SonarScanner CLI directly 
(see [documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/scanners/sonarscanner/#running-from-zip-file)).
This means that analysis properties provided that way should be prepended with `-D`, for instance:

```
$ pysonar -Dsonar.token=myAuthenticationToken 
```

You can use all the arguments allowed by __SonarScanner__. 
For more information on __SonarScanner__ please refer to the [SonarScanner documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/analysis-parameters/).

Additionally, some common properties can be provided using a shorter alias, such as:
```
pysonar --token "MyToken"
```

See [CLI_ARGS](https://github.com/SonarSource/sonar-scanner-python/blob/master/CLI_ARGS.md) for more details.

### 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 SonarQube/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
```

The configuration parameters can be found in the [SonarQube documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/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.

Properties in `pyproject.toml` files are expected to be provided in camel case. However, kebab case is also accepted:

```
[tool.sonar]
project-key=My Project key # valid alias for projectKey
```

By default, the scanner will expect the `pyproject.toml` file to be present in the current directory. However, its path can be provided manually through the `toml-path` CLI argument as well as through the `sonar.projectBaseDir` argument. The `--toml-path` argument accepts either the path to the `pyproject.toml` file itself or to the folder containing it. For instance:

```
pysonar --toml-path "path/to/pyproject.toml"
```

Or equivalently:

```
pysonar --toml-path "path/to"
```

Or:

```
pysonar --sonar-project-base-dir "path/to/projectBaseDir"
```

Or:

```
pysonar -Dsonar.projectBaseDir="path/to/projectBaseDir"
```

### Through project properties extracted from the `pyproject.toml`

When a `pyproject.toml` file is available, the scanner can deduce analysis properties from the project configuration. This is currently supported only for projects using `poetry`.

### With a sonar-project.properties file

Exactly like [__SonarScanner__](https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/scanners/sonarscanner/),
the analysis can also be configured with a `sonar-project.properties` file:

```
# must be unique in a given SonarQube/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

It is also possible to configure the scanner through environment variables:

```
$ export SONAR_HOST_URL="http://localhost:9000"
$ pysonar 
```

See the __SonarScanner__ [documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/setup-and-upgrade/environment-variables/) for more information.

# Feedback

For feedback and issues regarding `pysonar`, do not hesitate to contact us through our [Community](https://community.sonarsource.com/tag/scanner).

# Installation from testPyPI

To install the latest pre-released version of Sonar Scanner Python. Execute the following command: 

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

# License

Copyright 2011-2026 SonarSource.

Licensed under the [GNU Lesser General Public License, Version 3.0](http://www.gnu.org/licenses/lgpl.txt)

