# pysonar-scanner
A wrapper around SonarScanner CLI, available on PyPI.
# Disclaimer
This project is currently in beta and APIs are subject to change.
These changes include configuration parameter names.
# Requirements
- SonarQube v9.9 or higher
- Python 3.8 or above
# Installation
Install with pip:
```
pip install pysonar-scanner
```
# 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:
* 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`
* 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
(see [documentation](https://docs.sonarsource.com/sonarqube/9.9/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-scanner -Dsonar.login=myAuthenticationToken
```
You can use all the argument allowed by __SonarScanner__.
For more information on __SonarScanner__ please refer to the [SonarScanner documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/)
### 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/9.9/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.
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` ([PYSCAN-40](https://sonarsource.atlassian.net/jira/software/c/projects/PYSCAN/issues/PYSCAN-40)) CLI argument as well as through the `sonar.projectHome` argument. For instance:
```
pysonar-scanner -Dtoml.path="path/to/pyproject.toml"
```
Or:
```
pysonar-scanner -Dsonar.projectHome="path/to/projectHome"
```
### Through project properties extracted from the `pyproject.toml`
When a `pyproject.toml` file is available, it is 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
Exactly like [__SonarScanner__](https://docs.sonarsource.com/sonarqube/9.9/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 define configure the scanner through environment variables:
```
$ export SONAR_HOST_URL="http://localhost:9000"
$ pysonar-scanner
```
See the __SonarScanner__ [documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/) for more information.
# 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-scanner
```
# License
Copyright 2011-2024 SonarSource.
Licensed under the [GNU Lesser General Public License, Version 3.0](http://www.gnu.org/licenses/lgpl.txt)
Raw data
{
"_id": null,
"home_page": null,
"name": "pysonar-scanner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sonar, sonarqube, sonarcloud, cleancode",
"author": "Python Squad",
"author_email": "analysis.python@sonarsource.com",
"download_url": "https://files.pythonhosted.org/packages/f2/6e/4c966fc046191973274f0117d0ce622cd04942e0defdde494d7c835f1c04/pysonar_scanner-0.2.0.520.tar.gz",
"platform": null,
"description": "# pysonar-scanner\nA wrapper around SonarScanner CLI, available on PyPI.\n\n# Disclaimer \n\nThis project is currently in beta and APIs are subject to change. \nThese changes include configuration parameter names.\n\n# Requirements\n\n - SonarQube v9.9 or higher\n - Python 3.8 or above\n\n# Installation\n\nInstall with pip:\n```\npip install pysonar-scanner\n```\n\n# Usage\n\nOnce installed, the `pysonar-scanner` can be run from the command line to perform an analysis.\nIt assumes a running SonarQube server or a project configured on SonarCloud.\n\n## Setting up analysis properties\n\nIn order for the analysis to run, analysis properties need to be defined. \nThere are multiple ways of providing these properties, described below in descending order of priority:\n\n* Through CLI arguments to the `pysonar-scanner` command\n* Under the `[tool.sonar]` key of the `pyproject.toml` file\n* Through common properties extracted from the `pyproject.toml`\n* In a dedicated `sonar-project.properties` file\n* Through environment variables\n\n### Through CLI arguments\n\nAnalysis properties can be provided as CLI arguments to the `pysonar-scanner` command.\nThey follow the same convention as when running the SonarScanner CLI directly \n(see [documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/#running-from-zip-file)).\nThis means that analysis properties provided that way should be prepended with `-D`, for instance:\n\n```\n$ pysonar-scanner -Dsonar.login=myAuthenticationToken \n```\n\nYou can use all the argument allowed by __SonarScanner__. \nFor more information on __SonarScanner__ please refer to the [SonarScanner documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/)\n\n### With a pyproject.toml file\n\nInside a `pyproject.toml`, Sonar analysis properties can be defined under the `tool.sonar` table.\n\n```\n[tool.sonar]\n# must be unique in a given SonarQube/SonarCloud instance\nprojectKey=my:project\n\n# --- optional properties ---\n# defaults to project key\n#projectName=My project\n# defaults to 'not provided'\n#projectVersion=1.0\n \n# Path is relative to the pyproject.toml file. Defaults to .\n#sources=.\n \n# Encoding of the source code. Default is default system encoding\n#sourceEncoding=UTF-8\n```\n\nThe configuration parameters can be found in the [SonarQube documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/analysis-parameters/).\n\nIn the `pyproject.toml` file the prefix `sonar.` for parameter keys should be omitted. \nFor example, `sonar.scm.provider` in the documentation will become `scm.provider` in the `pyproject.toml` file.\n\nBy default, the scanner will expect the `pyproject.toml` file to be present in the current directory. \nHowever, its path can be provided manually through the `toml.path` ([PYSCAN-40](https://sonarsource.atlassian.net/jira/software/c/projects/PYSCAN/issues/PYSCAN-40)) CLI argument as well as through the `sonar.projectHome` argument. For instance:\n\n```\npysonar-scanner -Dtoml.path=\"path/to/pyproject.toml\"\n```\n\nOr:\n\n```\npysonar-scanner -Dsonar.projectHome=\"path/to/projectHome\"\n```\n\n\n### Through project properties extracted from the `pyproject.toml`\n\nWhen a `pyproject.toml` file is available, it is possible to set the `-read-project-config` flag\nto allow the scanner to deduce analysis properties from the project configuration.\n\nThis is currently supported only for projects using `poetry`.\n\nThe 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.\n\n### With a sonar-project.properties file\n\nExactly like [__SonarScanner__](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/),\nthe analysis can also be configured with a `sonar-project.properties` file:\n\n```\n# must be unique in a given SonarQube/SonarCloud instance\nsonar.projectKey=my:project\n\n# --- optional properties ---\n\n# defaults to project key\n#sonar.projectName=My project\n# defaults to 'not provided'\n#sonar.projectVersion=1.0\n \n# Path is relative to the sonar-project.properties file. Defaults to .\n#sonar.sources=.\n \n# Encoding of the source code. Default is default system encoding\n#sonar.sourceEncoding=UTF-8\n```\n\n### Through environment variables\n\nIt is also possible to define configure the scanner through environment variables:\n\n```\n$ export SONAR_HOST_URL=\"http://localhost:9000\"\n$ pysonar-scanner \n```\n\nSee the __SonarScanner__ [documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/) for more information.\n\n# Installation from testPyPI\n\nTo install the latest pre-released version of Sonar Scanner Python. Execute the following command: \n\n```shell\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pysonar-scanner\n```\n\n# License\n\nCopyright 2011-2024 SonarSource.\n\nLicensed under the [GNU Lesser General Public License, Version 3.0](http://www.gnu.org/licenses/lgpl.txt)\n\n",
"bugtrack_url": null,
"license": "LGPL-3.0-only",
"summary": "Sonar Scanner for the Python Ecosystem",
"version": "0.2.0.520",
"project_urls": null,
"split_keywords": [
"sonar",
" sonarqube",
" sonarcloud",
" cleancode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b3107f7a2c22ef2ab379a1c997df4947bd5685ffeace97f45303402fcf5b08c",
"md5": "40788ef4489c6cc3b9eac6c1584f4b3a",
"sha256": "73c6a594fd7b8ae98841a6314f66ae838133276a320299f2a2316999c8216fff"
},
"downloads": -1,
"filename": "pysonar_scanner-0.2.0.520-py3-none-any.whl",
"has_sig": false,
"md5_digest": "40788ef4489c6cc3b9eac6c1584f4b3a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15273,
"upload_time": "2024-10-15T15:01:35",
"upload_time_iso_8601": "2024-10-15T15:01:35.210589Z",
"url": "https://files.pythonhosted.org/packages/2b/31/07f7a2c22ef2ab379a1c997df4947bd5685ffeace97f45303402fcf5b08c/pysonar_scanner-0.2.0.520-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f26e4c966fc046191973274f0117d0ce622cd04942e0defdde494d7c835f1c04",
"md5": "9409ddcd974bc760694d142080838546",
"sha256": "499989f5d85f0b6dabee52870eb1d5613de1b83bfffec7084f61a5c181cb084e"
},
"downloads": -1,
"filename": "pysonar_scanner-0.2.0.520.tar.gz",
"has_sig": false,
"md5_digest": "9409ddcd974bc760694d142080838546",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11140,
"upload_time": "2024-10-15T15:01:36",
"upload_time_iso_8601": "2024-10-15T15:01:36.554044Z",
"url": "https://files.pythonhosted.org/packages/f2/6e/4c966fc046191973274f0117d0ce622cd04942e0defdde494d7c835f1c04/pysonar_scanner-0.2.0.520.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 15:01:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pysonar-scanner"
}
JSON