Projects

API for managing SonarQube projects.

Projects API for SonarQube SDK.

This module provides methods to manage SonarQube projects including creating, searching, updating, and deleting projects.

Example

Using the Projects API:

from sonarqube import SonarQubeClient

client = SonarQubeClient(base_url="...", token="...")

# Search for projects
projects = client.projects.search(q="backend")
for project in projects.components:
    print(project.name)

# Create a project
project = client.projects.create(name="My Project", project="my-project")

class sonarqube.api.projects.ProjectsAPI(client)[source]

Bases: BaseAPI

API for managing SonarQube projects.

Projects are the main organizational unit in SonarQube. This API provides methods to create, search, update, and delete projects.

API_PATH: Base path for projects API (“/api/projects”).

Example

Using the projects API:

# Search for projects
projects = client.projects.search(q="backend")

# Create a project
project = client.projects.create(name="My Project", project="my-project")

# Delete a project
client.projects.delete(project="my-project")

Parameters:: client (HTTPClient)

bulk_delete(analyzed_before=None, on_provisioned_only=None, projects=None, q=None, qualifiers=None, visibility=None)[source]

Delete multiple projects at once.

Requires ‘Administer System’ permission. At most 1000 projects can be deleted per request.

Parameters:

analyzed_before (Optional[str], default: None) – Filter projects analyzed before this date (ISO format).
on_provisioned_only (Optional[bool], default: None) – Filter on provisioned projects only.
projects (Optional[list[str]], default: None) – Comma-separated list of project keys to delete.
q (Optional[str], default: None) – Search query for project names or keys.
qualifiers (Optional[list[str]], default: None) – Filter by component qualifiers (TRK, VW, APP).
visibility (Optional[str], default: None) – Filter by visibility (public/private).

Raises:

SonarQubeValidationError – If validation fails.
SonarQubePermissionError – If lacking required permissions.

Return type:

None

Example

>>> client.projects.bulk_delete(projects=["project1", "project2"])

create(name, project, main_branch=None, new_code_definition_type=None, new_code_definition_value=None, visibility=None)[source]

Create a new project.

Requires ‘Create Projects’ permission.

Parameters:

name (str) – Project name (max 500 characters).
project (str) – Project key (unique identifier).
main_branch (Optional[str], default: None) – Main branch name (defaults to ‘main’).
new_code_definition_type (Optional[str], default: None) – Type for new code definition.
new_code_definition_value (Optional[str], default: None) – Value for new code definition.
visibility (Optional[str], default: None) – Project visibility (public/private).

Return type:

ProjectCreateResponse

Returns:

Response containing the created project.

Raises:

SonarQubeValidationError – If validation fails.
SonarQubePermissionError – If lacking required permissions.

Example

>>> project = client.projects.create(
...     name="My Project", project="my-project", visibility="private"
... )
>>> print(project.project.key)
'my-project'

delete(project)[source]

Delete a project.

Requires ‘Administer System’ permission or ‘Administer’ on the project.

Parameters:

project (str) – Project key.

Raises:

SonarQubeNotFoundError – If project not found.
SonarQubePermissionError – If lacking required permissions.

Return type:

None

Example

>>> client.projects.delete(project="my-project")

export_findings(project, branch=None, pull_request=None)[source]

Export all findings for a project.

Requires ‘Browse’ permission on the project.

Parameters:

project (str) – Project key.
branch (Optional[str], default: None) – Branch name.
pull_request (Optional[str], default: None) – Pull request ID.

Return type:

ExportFindingsResponse

Returns:

Response containing exported findings.

Example

>>> findings = client.projects.export_findings(project="my-project")

license_usage()[source]

Get license usage statistics.

Requires ‘Administer System’ permission.

Return type:: LicenseUsageResponse
Returns:: Response containing license usage information.

Example

>>> usage = client.projects.license_usage()
>>> print(f"Total lines of code: {usage.lines_of_code}")

search(analyzed_before=None, on_provisioned_only=None, p=None, projects=None, ps=None, q=None, qualifiers=None, s=None, visibility=None)[source]

Search for projects.

Requires ‘Browse’ permission on each returned project.

Parameters:

analyzed_before (Optional[str], default: None) – Filter projects analyzed before this date.
on_provisioned_only (Optional[bool], default: None) – Filter on provisioned projects only.
p (Optional[int], default: None) – Page number (1-based).
projects (Optional[list[str]], default: None) – Comma-separated list of project keys.
ps (Optional[int], default: None) – Page size (max 500).
q (Optional[str], default: None) – Search query for project names or keys.
qualifiers (Optional[list[str]], default: None) – Filter by component qualifiers.
s (Optional[str], default: None) – Sort field (key, name, qualifier, visibility).
visibility (Optional[str], default: None) – Filter by visibility.

Return type:

ProjectSearchResponse

Returns:

Response containing list of projects and paging info.

Example

>>> response = client.projects.search(q="backend")
>>> for project in response.components:
...     print(project.name)

update_key(from_key, to_key)[source]

Update a project’s key.

Requires ‘Administer’ permission on the project.

Parameters:

from_key (str) – Current project key.
to_key (str) – New project key.

Raises:

SonarQubeNotFoundError – If project not found.
SonarQubeValidationError – If new key is invalid.
SonarQubePermissionError – If lacking required permissions.

Return type:

None

Example

>>> client.projects.update_key(from_key="old-project-key", to_key="new-project-key")

update_visibility(project, visibility)[source]

Update a project’s visibility.

Requires ‘Administer’ permission on the project.

Parameters:

project (str) – Project key.
visibility (str) – New visibility (public/private).

Raises:

SonarQubeNotFoundError – If project not found.
SonarQubePermissionError – If lacking required permissions.

Return type:

None

Example

>>> client.projects.update_visibility(project="my-project", visibility="private")

Models

Pydantic models for Projects API.

This module provides models for the /api/projects endpoints including creating, searching, and managing projects.

Example

Using project models:

from sonarqube.models.projects import ProjectSearchResponse

response = client.projects.search(q="backend")
for project in response.components:
    print(project.name)

class sonarqube.models.projects.ProjectComponent(**data)[source]

Bases: SonarQubeModel

A project component in search results.

key: Unique project key.

name: Project display name.

qualifier: Component qualifier (TRK for projects).

visibility: Project visibility.

last_analysis_date: Date of last analysis.

revision: Last analysis revision.

managed: Whether the project is managed.

Example

>>> component = ProjectComponent(
...     key="my-project", name="My Project", qualifier="TRK", visibility="private"
... )

Parameters:

data (Any)
key (str)
name (str)
qualifier (str)
visibility (str | None)
lastAnalysisDate (str | None)
revision (str | None)
managed (bool | None)
isFavorite (bool | None)
tags (list[str] | None)
needIssueSync (bool | None)

key: str

name: str

qualifier: str

visibility: Optional[str]

last_analysis_date: Optional[str]

revision: Optional[str]

managed: Optional[bool]

is_favorite: Optional[bool]

tags: Optional[list[str]]

needs_issue_sync: Optional[bool]

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'str_strip_whitespace': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sonarqube.models.projects.ProjectSearchResponse(**data)[source]

Bases: SonarQubeModel

Response from searching projects.

paging: Paging information.

components: List of project components.

Example

>>> response = client.projects.search(q="backend")
>>> print(f"Found {response.paging.total} projects")
>>> for project in response.components:
...     print(project.name)

Parameters:

data (Any)
paging (Paging)
components (list[ProjectComponent])

paging: Paging

components: list[ProjectComponent]

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'str_strip_whitespace': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sonarqube.models.projects.ProjectCreateResponse(**data)[source]

Bases: SonarQubeModel

Response from creating a project.

project: The created project.

Example

>>> response = client.projects.create(name="My Project", project="my-project")
>>> print(response.project.key)

Parameters:

data (Any)
project (ProjectComponent)

project: ProjectComponent

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'str_strip_whitespace': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sonarqube.models.projects.ExportFindingsResponse(**data)[source]

Bases: SonarQubeModel

Response from exporting findings.

export_date: Date of the export.

findings: List of findings.

Parameters:

data (Any)
exportDate (str | None)
findings (list[dict[str, Any]] | None)

export_date: Optional[str]

findings: Optional[list[dict[str, Any]]]

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'str_strip_whitespace': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class sonarqube.models.projects.LicenseUsageResponse(**data)[source]

Bases: SonarQubeModel

Response from getting license usage.

lines_of_code: Total lines of code.

Parameters:

data (Any)
linesOfCode (int | None)

lines_of_code: Optional[int]

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'populate_by_name': True, 'str_strip_whitespace': True, 'use_enum_values': True, 'validate_by_alias': True, 'validate_by_name': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].