Skip to content

Commit 49e7c9f

Browse files
guillaume-dequenneguillaume-dequenne
authored
SCANPY-156 Expand documentation for the pysonar-scanner (#186)
1 parent d9236d9 commit 49e7c9f

File tree

5 files changed

+270
-33
lines changed

5 files changed

+270
-33
lines changed

‎.cirrus.yml

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ poetry_win_install: &POETRY_WIN_INSTALL
7878
poetry_cache_template: &POETRY_CACHE
7979
poetry_cache:
8080
folder: ~/.cache/poetry/
81-
fingerprint_script: cat poetry.lock
81+
fingerprint_script: cat poetry.lock
8282

8383
.poetry_template: &POETRY_TEMPLATE
8484
<<: *POETRY_CACHE
@@ -152,6 +152,14 @@ formatting_task:
152152
- poetry run licenseheaders -t license_header.tmpl -o "SonarSource SA" -y 2011-2024 -n "Sonar Scanner Python" -E .py -d tests/
153153
- git diff --name-only --exit-code ./src ./tests
154154

155+
documentation_task:
156+
<<: *POETRY_LINUX_TEMPLATE
157+
alias: documentation
158+
name: "CLI Documentation"
159+
cli_docs_script:
160+
- poetry run python tools/generate_cli_documentation.py
161+
- git diff --exit-code CLI_ARGS.md
162+
155163
analysis_linux_task:
156164
<<: *POETRY_LINUX_TEMPLATE
157165
alias: analysis

‎CLI_ARGS.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Sonar Scanner Python CLI Arguments
2+
3+
## Authentication
4+
5+
| Option | Description |
6+
| ------ | ----------- |
7+
| `--sonar-host-url`, `-Dsonar.host.url` | SonarQube Server base URL. For example, http://localhost:9000 for a local instance of SonarQube Server |
8+
| `--sonar-organization`, `-Dsonar.organization` | The key of the organization to which the project belongs |
9+
| `--sonar-region`, `-Dsonar.region` | The region to contact, only for SonarQube Cloud |
10+
| `-t`, `--token`, `--sonar-token`, `-Dsonar.token` | Token used to authenticate against the SonarQube Server or SonarQube Cloud |
11+
12+
## Project Configuration
13+
14+
| Option | Description |
15+
| ------ | ----------- |
16+
| `--sonar-project-base-dir`, `-Dsonar.projectBaseDir` | Directory containing the project to be analyzed. Default is the current directory |
17+
| `--sonar-project-description`, `-Dsonar.projectDescription` | Description of the project |
18+
| `--sonar-project-key`, `-Dsonar.projectKey` | Key of the project that usually corresponds to the project name in SonarQube |
19+
| `--sonar-project-name`, `-Dsonar.projectName` | Name of the project in SonarQube |
20+
| `--sonar-project-version`, `-Dsonar.projectVersion` | Version of the project |
21+
| `--sonar-sources`, `-Dsonar.sources` | The analysis scope for main source code (non-test code) in the project |
22+
| `--sonar-tests`, `-Dsonar.tests` | The analysis scope for test source code in the project |
23+
24+
## Analysis Configuration
25+
26+
| Option | Description |
27+
| ------ | ----------- |
28+
| `--sonar-filesize-limit`, `-Dsonar.filesize.limit` | Sets the limit in MB for files to be discarded from the analysis scope if the size is greater than specified |
29+
| `--sonar-python-version`, `-Dsonar.python.version` | Python version used for the project |
30+
| `-v`, `--verbose`, `--no-verbose`, `--sonar-verbose`, `--no-sonar-verbose`, `-Dsonar.verbose` | Increase output verbosity |
31+
32+
## Report Integration
33+
34+
| Option | Description |
35+
| ------ | ----------- |
36+
| `--sonar-external-issues-report-paths`, `-Dsonar.externalIssuesReportPaths` | Comma-delimited list of paths to generic issue reports |
37+
| `--sonar-python-bandit-report-paths`, `--bandit-report-paths`, `-Dsonar.python.bandit.reportPaths` | Comma-separated bandit report paths, relative to project's root |
38+
| `--sonar-python-coverage-report-paths`, `--coverage-report-paths`, `-Dsonar.python.coverage.reportPaths` | Comma-delimited list of paths to coverage reports in the Cobertura XML format. |
39+
| `--sonar-python-flake8-report-paths`, `--flake8-report-paths`, `-Dsonar.python.flake8.reportPaths` | Comma-separated flake8 report paths, relative to project's root |
40+
| `--sonar-python-mypy-report-paths`, `--mypy-report-paths`, `-Dsonar.python.mypy.reportPaths` | Comma-separated mypy report paths, relative to project's root |
41+
| `--sonar-python-pylint-report-path`, `--pylint-report-path`, `-Dsonar.python.pylint.reportPath` | Path to third-parties issues report file for pylint |
42+
| `--sonar-python-ruff-report-paths`, `--ruff-report-paths`, `-Dsonar.python.ruff.reportPaths` | Comma-separated ruff report paths, relative to project's root |
43+
| `--sonar-python-xunit-report-path`, `--xunit-report-path`, `-Dsonar.python.xunit.reportPath` | Path to the report of test execution, relative to project's root |
44+
| `--sonar-python-xunit-skip-details`, `--no-sonar-python-xunit-skip-details`, `--xunit-skip-details`, `--no-xunit-skip-details` | When enabled, the test execution statistics is provided only on project level |
45+
| `--sonar-sarif-report-paths`, `-Dsonar.sarifReportPaths` | Comma-delimited list of paths to SARIF issue reports |
46+
47+
## Other
48+
49+
| Option | Description |
50+
| ------ | ----------- |
51+
| `--skip-jre-provisioning`, `-Dsonar.scanner.skipJreProvisioning` | If provided, the provisioning of the JRE will be skipped |
52+
| `--sonar-branch-name`, `-Dsonar.branch.name` | Name of the branch being analyzed |
53+
| `--sonar-build-string`, `-Dsonar.buildString` | The string passed with this property will be stored with the analysis and available in the results of api/project_analyses/search, thus allowing you to later identify a specific analysis and obtain its key for use with api/new_code_periods/set on the SPECIFIC_ANALYSIS type |
54+
| `--sonar-cpd-python-minimum-lines`, `-Dsonar.cpd.python.minimumLines` | Minimum number of tokens to be considered as a duplicated block of code |
55+
| `--sonar-cpd-python-minimum-tokens`, `-Dsonar.cpd.python.minimumTokens` | Minimum number of tokens to be considered as a duplicated block of code |
56+
| `--sonar-links-ci`, `-Dsonar.links.ci` | The URL of the continuous integration system used |
57+
| `--sonar-links-homepage`, `-Dsonar.links.homepage` | The URL of the build project home page |
58+
| `--sonar-links-issue`, `-Dsonar.links.issue` | The URL to the issue tracker being used |
59+
| `--sonar-links-scm`, `-Dsonar.links.scm` | The URL of the build project source code repository |
60+
| `--sonar-log-level`, `-Dsonar.log.level` | Log level during the analysis |
61+
| `--sonar-modules`, `-Dsonar.modules` | Comma-delimited list of modules to analyze |
62+
| `--sonar-newcode-reference-branch`, `-Dsonar.newCode.referenceBranch` | Reference branch for new code definition |
63+
| `--sonar-pullrequest-base`, `-Dsonar.pullrequest.base` | Base branch of the pull request being analyzed |
64+
| `--sonar-pullrequest-branch`, `-Dsonar.pullrequest.branch` | Branch of the pull request being analyzed |
65+
| `--sonar-pullrequest-key`, `-Dsonar.pullrequest.key` | Key of the pull request being analyzed |
66+
| `--sonar-python-skip-unchanged`, `--no-sonar-python-skip-unchanged` | Override the SonarQube configuration of skipping or not the analysis of unchanged Python files |
67+
| `--sonar-qualitygate-timeout`, `-Dsonar.qualitygate.timeout` | The number of seconds that the scanner should wait for a report to be processed |
68+
| `--sonar-qualitygate-wait`, `--no-sonar-qualitygate-wait` | Forces the analysis step to poll the server instance and wait for the Quality Gate status |
69+
| `--sonar-scanner-api-url`, `-Dsonar.scanner.apiUrl` | Base URL for all REST-compliant API calls, https://api.sonarcloud.io for example |
70+
| `--sonar-scanner-arch`, `-Dsonar.scanner.arch` | Architecture on which the scanner will be running |
71+
| `--sonar-scanner-cloud-url`, `-Dsonar.scanner.cloudUrl` | SonarQube Cloud base URL, https://sonarcloud.io for example |
72+
| `--sonar-scanner-connect-timeout`, `-Dsonar.scanner.connectTimeout` | Time period to establish connections with the server (in seconds) |
73+
| `--sonar-scanner-internal-dump-to-file`, `-Dsonar.scanner.internal.dumpToFile` | Filename where the input to the scanner engine will be dumped. Useful for debugging |
74+
| `--sonar-scanner-internal-sq-version`, `-Dsonar.scanner.internal.sqVersion` | Emulate the result of the call to get SQ server version. Useful for debugging with --sonar-scanner-internal-dump-to-file |
75+
| `--sonar-scanner-java-exe-path`, `-Dsonar.scanner.javaExePath` | If defined, the scanner engine will be run with this JRE |
76+
| `--sonar-scanner-java-opts`, `-Dsonar.scanner.javaOpts` | Arguments provided to the JVM when running the scanner |
77+
| `--sonar-scanner-keystore-password`, `-Dsonar.scanner.keystorePassword` | Password to access the keystore |
78+
| `--sonar-scanner-keystore-path`, `-Dsonar.scanner.keystorePath` | Path to the keystore containing the client certificates used by the scanner. By default, <sonar.userHome>/ssl/keystore.p12 |
79+
| `--sonar-scanner-metadata-filepath`, `-Dsonar.scanner.metadataFilepath` | Sets the location where the scanner writes the report-task.txt file containing among other things the ceTaskId |
80+
| `--sonar-scanner-os`, `-Dsonar.scanner.os` | OS running the scanner |
81+
| `--sonar-scanner-proxy-host`, `-Dsonar.scanner.proxyHost` | Proxy host |
82+
| `--sonar-scanner-proxy-password`, `-Dsonar.scanner.proxyPassword` | Proxy password |
83+
| `--sonar-scanner-proxy-port`, `-Dsonar.scanner.proxyPort` | Proxy port |
84+
| `--sonar-scanner-proxy-user`, `-Dsonar.scanner.proxyUser` | Proxy user |
85+
| `--sonar-scanner-response-timeout`, `-Dsonar.scanner.responseTimeout` | Time period required to process an HTTP call: from sending a request to receiving a response (in seconds) |
86+
| `--sonar-scanner-socket-timeout`, `-Dsonar.scanner.socketTimeout` | Maximum time of inactivity between two data packets when exchanging data with the server (in seconds) |
87+
| `--sonar-scanner-truststore-password`, `-Dsonar.scanner.truststorePassword` | Password to access the truststore |
88+
| `--sonar-scanner-truststore-path`, `-Dsonar.scanner.truststorePath` | Path to the keystore containing trusted server certificates, used by the Scanner in addition to OS and the built-in certificates |
89+
| `--sonar-scm-exclusions-disabled`, `--no-sonar-scm-exclusions-disabled` | Defines whether files ignored by the SCM, e.g., files listed in .gitignore, will be excluded from the analysis or not |
90+
| `--sonar-scm-force-reload-all`, `--no-sonar-scm-force-reload-all` | Set this property to true to load blame information for all files, which may significantly increase analysis duration |
91+
| `--sonar-scm-revision`, `-Dsonar.scm.revision` | Overrides the revision, for instance, the Git sha1, displayed in analysis results |
92+
| `--sonar-source-encoding`, `-Dsonar.sourceEncoding` | Encoding of the source files. For example, UTF-8, MacRoman, Shift_JIS |
93+
| `--sonar-user-home`, `-Dsonar.userHome` | Base sonar directory, ~/.sonar by default |
94+
| `--sonar-working-directory`, `-Dsonar.working.directory` | Path to the working directory used by the Sonar scanner during a project analysis to store temporary data |
95+
| `--toml-path` | Path to the pyproject.toml file. If not provided, it will look in the SONAR_PROJECT_BASE_DIR |
96+
| `-Dsonar.python.skipUnchanged` | Equivalent to --sonar-python-skip-unchanged |
97+
| `-Dsonar.python.xunit.skipDetails` | Equivalent to -Dsonar.python.xunit.skipDetails |
98+
| `-Dsonar.qualitygate.wait` | Equivalent to --sonar-qualitygate-wait |
99+
| `-Dsonar.scm.exclusions.disabled` | Equivalent to --sonar-scm-exclusions-disabled |
100+
| `-Dsonar.scm.forceReloadAll` | Equivalent to --sonar-scm-force-reload-all |

‎README.md

Lines changed: 40 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,10 @@
11
# pysonar
2-
A wrapper around SonarScanner CLI, available on PyPI.
3-
4-
# Disclaimer
5-
6-
This project is currently in beta and APIs are subject to change.
7-
These changes include configuration parameter names.
2+
A Python scanner for SonarQube, available on PyPI.
83

94
# Requirements
105

11-
- SonarQube v9.9 or higher
12-
- Python 3.8 or above
6+
- SonarQube v10.6 or above
7+
- Python 3.9 or above
138

149
# Installation
1510

@@ -28,25 +23,33 @@ It assumes a running SonarQube server or a project configured on SonarCloud.
2823
In order for the analysis to run, analysis properties need to be defined.
2924
There are multiple ways of providing these properties, described below in descending order of priority:
3025

31-
* Through CLI arguments to the `pysonar` command
32-
* Under the `[tool.sonar]` key of the `pyproject.toml` file
33-
* Through common properties extracted from the `pyproject.toml`
34-
* In a dedicated `sonar-project.properties` file
35-
* Through environment variables
26+
1. Through CLI arguments to the `pysonar` command
27+
2. Environment variables for individual properties (e.g. `SONAR_TOKEN`, `SONAR_VERBOSE`, `SONAR_HOST_URL`, ...)
28+
3. Generic environment variable `SONAR_SCANNER_JSON_PARAMS`
29+
4. Under the `[tool.sonar]` key of the `pyproject.toml` file
30+
5. In a dedicated `sonar-project.properties` file
31+
6. Through common properties extracted from the `pyproject.toml`
3632

3733
### Through CLI arguments
3834

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

4440
```
45-
$ pysonar -Dsonar.login=myAuthenticationToken
41+
$ pysonar -Dsonar.token=myAuthenticationToken
4642
```
4743

48-
You can use all the argument allowed by __SonarScanner__.
49-
For more information on __SonarScanner__ please refer to the [SonarScanner documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/)
44+
You can use all the arguments allowed by __SonarScanner__.
45+
For more information on __SonarScanner__ please refer to the [SonarScanner documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/analysis-parameters/).
46+
47+
Additionally, some common properties can be provided using a shorter alias, such as:
48+
```
49+
pysonar --token "MyToken"
50+
```
51+
52+
See [CLI_ARGS](https://github.com/SonarSource/sonar-scanner-python/blob/master/CLI_ARGS.md) for more details.
5053

5154
### With a pyproject.toml file
5255

@@ -70,37 +73,43 @@ projectKey=my:project
7073
#sourceEncoding=UTF-8
7174
```
7275

73-
The configuration parameters can be found in the [SonarQube documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/analysis-parameters/).
76+
The configuration parameters can be found in the [SonarQube documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/analysis-parameters/).
7477

7578
In the `pyproject.toml` file the prefix `sonar.` for parameter keys should be omitted.
7679
For example, `sonar.scm.provider` in the documentation will become `scm.provider` in the `pyproject.toml` file.
7780

78-
By default, the scanner will expect the `pyproject.toml` file to be present in the current directory.
79-
However, its path can be provided manually through the `toml.path` ([SCANPY-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:
81+
Properties in `pyproject.toml` files are expected to be provided in camel case. However, kebab case is also accepted:
8082

8183
```
82-
pysonar --toml.path "path/to/pyproject.toml"
84+
[tool.sonar]
85+
project-key=My Project key # valid alias for projectKey
8386
```
8487

85-
Or:
88+
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. For instance:
8689

8790
```
88-
pysonar --sonar-project-home "path/to/projectHome"
91+
pysonar --toml-path "path/to/pyproject.toml"
8992
```
9093

94+
Or:
9195

92-
### Through project properties extracted from the `pyproject.toml`
96+
```
97+
pysonar --sonar-project-base-dir "path/to/projectBaseDir"
98+
```
99+
100+
Or:
93101

94-
When a `pyproject.toml` file is available, it is possible to set the `-read-project-config` flag
95-
to allow the scanner to deduce analysis properties from the project configuration.
102+
```
103+
pysonar -Dsonar.projectBaseDir="path/to/projectBaseDir"
104+
```
96105

97-
This is currently supported only for projects using `poetry`.
106+
### Through project properties extracted from the `pyproject.toml`
98107

99-
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.
108+
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`.
100109

101110
### With a sonar-project.properties file
102111

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

106115
```
@@ -130,7 +139,7 @@ $ export SONAR_HOST_URL="http://localhost:9000"
130139
$ pysonar
131140
```
132141

133-
See the __SonarScanner__ [documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/) for more information.
142+
See the __SonarScanner__ [documentation](https://docs.sonarsource.com/sonarqube-server/2025.1/setup-and-upgrade/environment-variables/) for more information.
134143

135144
# Installation from testPyPI
136145

‎src/pysonar_scanner/configuration/cli.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ def load(cls) -> dict[str, any]:
5050

5151
@classmethod
5252
def __parse_cli_args(cls) -> tuple[argparse.Namespace, list[str]]:
53+
parser = cls.__create_parser()
54+
return parser.parse_known_args()
55+
56+
@classmethod
57+
def __create_parser(cls):
5358
parser = argparse.ArgumentParser(
5459
description="Sonar scanner CLI for Python",
5560
epilog="Analysis properties not listed here will also be accepted, as long as they start with the -D prefix.",
@@ -493,4 +498,4 @@ def __parse_cli_args(cls) -> tuple[argparse.Namespace, list[str]]:
493498
"--sonar-modules", "-Dsonar.modules", type=str, help="Comma-delimited list of modules to analyze"
494499
)
495500

496-
return parser.parse_known_args()
501+
return parser

0 commit comments

Comments
 (0)