add sla metrics atlassian-api#1261 atlassian-api#1149

Author: gonchik

atlassian/bitbucket/cloud/repositories/commits.py

@@ -15,15 +15,19 @@ def __init__(self, url, *args, **kwargs):
     def __get_object(self, data):
         return Commit(data, **self._new_session_args)
 
-    def each(self, top=None, q=None, sort=None):
+    def each(self, top=None, q=None, sort=None, include=None, exclude=None, path=None):
         """
         Return the list of commits in this repository.
 
         :param top: string: Hash of commit to get the history for.
-        :param q: string: Query string to narrow down the response.
-                          See https://developer.atlassian.com/bitbucket/api/2/reference/meta/filtering for details.
+        :param q: string: Legacy query expression. Bitbucket Cloud does not
+                          support arbitrary ``q`` filtering for commits; it is
+                          retained for compatibility and passed to the API.
         :param sort: string: Name of a response property to sort results.
                              See https://developer.atlassian.com/bitbucket/api/2/reference/meta/filtering for details.
+        :param include: string: Commit or ref to include in the history.
+        :param exclude: string: Commit or ref to exclude from the history.
+        :param path: string: File path used to filter commits.
 
         :return: A generator for the Commit objects
 
@@ -35,6 +39,12 @@ def each(self, top=None, q=None, sort=None):
             params["sort"] = sort
         if q is not None:
             params["q"] = q
+        if include is not None:
+            params["include"] = include
+        if exclude is not None:
+            params["exclude"] = exclude
+        if path is not None:
+            params["path"] = path
         trailing = True
         if top is not None:
             trailing = False

atlassian/jira/jira_cloud.py

@@ -209,6 +209,34 @@ def endpoint(self, resource: str = "") -> str:
         """Return a JSM public REST endpoint path without issuing a request."""
         return self.url_joiner("rest/servicedeskapi", resource)
 
+    def get_sla_metrics(self, service_desk_id, start=None, limit=None):
+        """Return SLA metric configuration from Jira's agent endpoint.
+
+        This is an internal endpoint used by the JSM settings UI and may not
+        be available on every Cloud or Data Center release.
+        """
+        params = {key: value for key, value in {"start": start, "limit": limit}.items() if value is not None}
+        return self.get(
+            f"rest/servicedesk/1/servicedesk/agent/{service_desk_id}/sla/metrics",
+            params=params or None,
+        )
+
+    def update_sla_metric(self, service_desk_id, sla_id, data):
+        """Update an SLA metric configuration for a service desk.
+
+        Jira exposes this through an internal agent endpoint used by the JSM
+        settings UI. The payload is passed through unchanged to support the
+        metric schema used by the target Jira release.
+        """
+        return self.put(
+            f"rest/servicedesk/1/servicedesk/agent/{service_desk_id}/sla/metrics/{sla_id}",
+            data=data,
+        )
+
+    def set_sla_metric(self, service_desk_id, sla_id, data):
+        """Backward-compatible alias for :meth:`update_sla_metric`."""
+        return self.update_sla_metric(service_desk_id, sla_id, data)
+
 
 def create_jira_cloud(url: str, *args: Any, api_version: Union[str, int] = 3, **kwargs: Any) -> JiraCloud:
     """Create a versioned Jira Cloud Core client (v3 by default)."""

atlassian/service_desk.py

@@ -689,6 +689,42 @@ def get_sla_by_id(self, issue_id_or_key, sla_id):
 
         return self.get(url, headers=self.experimental_headers)
 
+    def get_sla_metrics(self, service_desk_id, start=None, limit=None):
+        """Return SLA metric configuration for a service desk.
+
+        Jira Service Management exposes this configuration through an internal
+        agent endpoint used by the service-desk settings UI. It is not part of
+        the public ``rest/servicedeskapi`` contract and may require an agent
+        or Jira administrator permission.
+
+        :param service_desk_id: Service desk/project identifier used by Jira.
+        :param start: Optional result offset, when supported by the instance.
+        :param limit: Optional result limit, when supported by the instance.
+        :return: SLA metric configuration response.
+        """
+        params = {key: value for key, value in {"start": start, "limit": limit}.items() if value is not None}
+        url = f"rest/servicedesk/1/servicedesk/agent/{service_desk_id}/sla/metrics"
+        return self.get(url, params=params or None, headers=self.experimental_headers)
+
+    def update_sla_metric(self, service_desk_id, sla_id, data):
+        """Update an SLA metric configuration for a service desk.
+
+        This uses Jira Service Management's internal agent endpoint. The
+        payload is passed through unchanged because its schema varies between
+        Jira releases and contains the metric definition, goals and calendars.
+
+        :param service_desk_id: Service desk/project identifier used by Jira.
+        :param sla_id: SLA metric identifier.
+        :param data: Metric configuration payload accepted by Jira.
+        :return: Updated SLA metric response.
+        """
+        url = f"rest/servicedesk/1/servicedesk/agent/{service_desk_id}/sla/metrics/{sla_id}"
+        return self.put(url, data=data, headers=self.experimental_headers)
+
+    def set_sla_metric(self, service_desk_id, sla_id, data):
+        """Backward-compatible alias for :meth:`update_sla_metric`."""
+        return self.update_sla_metric(service_desk_id, sla_id, data)
+
     def sla_rebuild(self, tickets=None):
         """
         Fix corrupted or missing sla

docs/bitbucket.rst

@@ -139,6 +139,21 @@ so retain the results by pull request ID to avoid duplicates.
 See ``examples/bitbucket/bitbucket_server_release_report.py`` for a complete
 environment-variable-based script.
 
+Commits belonging to an open pull request may not be reachable from the
+repository ref used by ``get_commits``. To retrieve the commits that belong to
+a specific pull request on Server/Data Center, query the pull-request commits
+endpoint instead:
+
+.. code-block:: python
+
+    for commit in bitbucket.get_pull_requests_commits("PROJ", "repository", pull_request_id):
+        print(commit["id"])
+
+The Cloud object model provides the equivalent operation as
+``repository.pullrequests.get(pull_request_id).commits``. Use
+``get_pull_requests_contain_commit`` when starting from an individual commit
+and looking up its associated pull requests.
+
 Manage projects
 ---------------
 
@@ -558,6 +573,20 @@ July 2026, so new integrations must use API tokens.
     # Get a repository
     repository = workspace.repositories.get(repository_slug)
 
+    # Commit history supports include/exclude refs and a file-path filter.
+    commits = repository.commits.each(
+        include="main",
+        exclude="release",
+        path="src/app.py",
+    )
+    for commit in commits:
+        print(commit.hash)
+
+The Cloud commits endpoint does not support arbitrary ``q`` expressions for
+filtering by author or date. Filter those fields in the returned commits, or
+use ``include``, ``exclude`` and ``path`` when those server-side filters fit
+the use case.
+
     # Read raw bytes from a file at a branch, tag, or commit SHA
     readme = repository.get_source_file("main", "README.md")
 
@@ -567,20 +596,26 @@ July 2026, so new integrations must use API tokens.
     # Get a list of deployment environments from a repository
     repository.deployment_environments.each()
 
-    # Get a single deployment environment from a repository by deployment environment key
+    # Get a deployment environment by key
     deployment_environment = repository.deployment_environments.get(deployment_environment_key)
 
-    # Get a list of deployment environment variables from a deployment environment
+    # Get deployment environment variables from an environment
     deployment_environment_variables = deployment_environment.deployment_environment_variables.each()
 
-    # Create a new deployment environment variable with a name of 'KEY', value of 'VALUE' and is not secured.
-    new_deployment_environment_variable = deployment_environment.deployment_environment_variables.create("KEY", "VALUE", False)
+    # Create a non-secured deployment environment variable.
+    new_deployment_environment_variable = deployment_environment.deployment_environment_variables.create(
+    "KEY", "VALUE", False
+    )
 
     # Update the 'key' field of repository_variable
-    updated_deployment_environment_variable = new_deployment_environment_variable.update(key="UPDATED_DEPLOYMENT_ENVIRONMENT_VARIABLE_KEY")
+    updated_deployment_environment_variable = new_deployment_environment_variable.update(
+    key="UPDATED_DEPLOYMENT_ENVIRONMENT_VARIABLE_KEY"
+    )
 
     # Update the 'value' field of repository_variable
-    updated_deployment_environment_variable = new_deployment_environment_variable.update(value="UPDATED_DEPLOYMENT_ENVIRONMENT_VARIABLE_VALUE")
+    updated_deployment_environment_variable = new_deployment_environment_variable.update(
+    value="UPDATED_DEPLOYMENT_ENVIRONMENT_VARIABLE_VALUE"
+    )
 
     # Delete deployment environment variable
     updated_deployment_environment_variable.delete()
@@ -594,17 +629,25 @@ July 2026, so new integrations must use API tokens.
     # Get a list of repository variables from a repository
     repository.repository_variables.each()
 
-    # Get a single repository variable from a repository by repository variable key
-    repository_variable = repository.repository_variables.get(repository_variable_key)
+    # Get a repository variable by key
+    repository_variable = repository.repository_variables.get(
+    repository_variable_key
+    )
 
-    # Create a new repository variable with a name of 'KEY', value of 'VALUE' and is not secured.
-    new_repository_variable = repository.repository_variables.create("KEY", "VALUE", False)
+    # Create a non-secured repository variable.
+    new_repository_variable = repository.repository_variables.create(
+    "KEY", "VALUE", False
+    )
 
     # Update the 'key' field of repository_variable
-    updated_repository_variable = repository_variable.update(key="UPDATED_REPOSITORY_VARIABLE_KEY")
+    updated_repository_variable = repository_variable.update(
+    key="UPDATED_REPOSITORY_VARIABLE_KEY"
+    )
 
     # Update the 'value' field of repository_variable
-    updated_repository_variable = repository_variable.update(value="UPDATED_REPOSITORY_VARIABLE_VALUE")
+    updated_repository_variable = repository_variable.update(
+    value="UPDATED_REPOSITORY_VARIABLE_VALUE"
+    )
 
     # Delete repository_variable
     repository_variable.delete()
@@ -613,13 +656,19 @@ July 2026, so new integrations must use API tokens.
     repository.hooks.each()
 
     # Create a hook for a repository
-    hook  = repo.hooks.create(url="endpoint-url", description="description", active=True, events=["a-repository-event"])
+    hook = repo.hooks.create(
+    url="endpoint-url", description="description", active=True,
+    events=["a-repository-event"]
+    )
 
     # Get a single hook for a repository
     hook = repo.hooks.get("a-webhook-id")
 
     # Update a specific hook for a repository
-    hook.update(url="endpoint-url", description="description", active=True, events=["a-repository-event"])
+    hook.update(
+    url="endpoint-url", description="description", active=True,
+    events=["a-repository-event"]
+    )
 
     # Delete a speicifc hook for a repository
     hook.delete()

docs/jira_cloud.rst

@@ -59,6 +59,22 @@ documented root/version. Supported API names are ``agile``, ``software``,
 ``security``, ``operations``, and ``devopscomponents``.  The separate roots
 avoid incorrectly treating Jira Software as Core v1.
 
+Issue ranking
+-------------
+
+Jira Software exposes ranking through the Agile API. ``rank_issues`` accepts
+multiple issue keys or IDs and placement fields supported by Jira:
+
+.. code-block:: python
+
+    software.rank_issues({
+        "issues": ["EXAMPLE-1", "EXAMPLE-2"],
+        "rankAfterIssue": "EXAMPLE-10",
+    })
+
+Use ``rank_epics`` for ranking epics. These methods are available on Cloud and
+on Jira Software Server/Data Center installations exposing the Agile REST API.
+
 Generated OpenAPI operations
 ----------------------------
 

docs/service_desk.rst

@@ -196,6 +196,14 @@ SLA actions
     # IMPORTANT: The calling user must be an agent
     sd.get_sla_by_id(issue_id_or_key, sla_id)
 
+    # Get SLA metric configuration for a service desk/project.
+    # This uses an internal agent endpoint and may vary by Jira release.
+    sd.get_sla_metrics(service_desk_id)
+
+    # Update one SLA metric. Pass the metric definition/goals payload required
+    # by your Jira release; this is an internal agent endpoint.
+    sd.update_sla_metric(service_desk_id, sla_id, metric_payload)
+
 Approvals
 ---------
 

tests/test_bitbucket_cloud_oo.py

@@ -137,6 +137,28 @@ def fail_get(*args, **kwargs):
         assert commit.hash == "1fbd047cd99a"
         assert commit.message == "src created online with Bitbucket"
 
+    def test_repository_commits_each_forwards_supported_filters(self, monkeypatch):
+        repository = CLOUD.workspaces.get("TestWorkspace1").repositories.get("testrepository1")
+        calls = []
+
+        def get_paged(*args, **kwargs):
+            calls.append((args, kwargs))
+            return iter([])
+
+        monkeypatch.setattr(repository.commits, "_get_paged", get_paged)
+
+        list(repository.commits.each(include="main", exclude="release", path="src/app.py"))
+
+        assert calls == [
+            (
+                (None,),
+                {
+                    "trailing": True,
+                    "params": {"include": "main", "exclude": "release", "path": "src/app.py"},
+                },
+            )
+        ]
+
     def test_not_exists_repository(self):
         assert not CLOUD.workspaces.get("TestWorkspace1").repositories.exists(
             "testrepository1xxx"

tests/test_jira_cloud_clients.py

@@ -57,6 +57,24 @@ def test_core_methods_cover_the_supplied_v3_document(self):
             jira.get_issue("ABC-1", fields="summary")
         get.assert_called_once_with("rest/api/3/issue/ABC-1", params={"fields": "summary"}, data=None)
 
+    def test_software_rank_issues_supports_multiple_issue_keys(self):
+        jira = JiraSoftware("https://example.atlassian.net")
+        payload = {"issues": ["EXAMPLE-1", "EXAMPLE-2"], "rankAfterIssue": "EXAMPLE-10"}
+
+        with patch.object(jira, "put", return_value=None) as put:
+            jira.rank_issues(payload)
+
+        put.assert_called_once_with("rest/agile/1.0/issue/rank", params=None, data=payload)
+
+    def test_software_rank_epics_uses_epic_endpoint(self):
+        jira = JiraSoftware("https://example.atlassian.net")
+        payload = {"epic": "EXAMPLE-1", "rankBeforeEpic": "EXAMPLE-2"}
+
+        with patch.object(jira, "put", return_value=None) as put:
+            jira.rank_epics("EXAMPLE-1", payload)
+
+        put.assert_called_once_with("rest/agile/1.0/epic/EXAMPLE-1/rank", params=None, data=payload)
+
     def test_core_methods_honor_the_selected_v2_route(self):
         jira = JiraCloud("https://example.atlassian.net", api_version=2)
 

tests/test_sla_metrics.py

@@ -0,0 +1,55 @@
+from unittest.mock import patch
+
+from atlassian import JiraServiceManagement, ServiceDesk
+
+
+def test_legacy_service_desk_get_sla_metrics_uses_agent_endpoint():
+    service_desk = ServiceDesk("https://example.atlassian.net")
+
+    with patch.object(service_desk, "get", return_value={"metrics": []}) as get:
+        result = service_desk.get_sla_metrics("10", start=0, limit=25)
+
+    assert result == {"metrics": []}
+    get.assert_called_once_with(
+        "rest/servicedesk/1/servicedesk/agent/10/sla/metrics",
+        params={"start": 0, "limit": 25},
+        headers=service_desk.experimental_headers,
+    )
+
+
+def test_jsm_cloud_get_sla_metrics_uses_agent_endpoint():
+    service_management = JiraServiceManagement("https://example.atlassian.net")
+
+    with patch.object(service_management, "get", return_value={"metrics": []}) as get:
+        service_management.get_sla_metrics("10")
+
+    get.assert_called_once_with("rest/servicedesk/1/servicedesk/agent/10/sla/metrics", params=None)
+
+
+def test_legacy_service_desk_update_sla_metric_uses_agent_endpoint():
+    service_desk = ServiceDesk("https://example.atlassian.net")
+    payload = {"id": 42, "name": "Time to resolution", "config": {"goals": []}}
+
+    with patch.object(service_desk, "put", return_value=payload) as put:
+        result = service_desk.update_sla_metric("10", "42", payload)
+
+    assert result == payload
+    put.assert_called_once_with(
+        "rest/servicedesk/1/servicedesk/agent/10/sla/metrics/42",
+        data=payload,
+        headers=service_desk.experimental_headers,
+    )
+
+
+def test_jsm_cloud_update_sla_metric_uses_agent_endpoint():
+    service_management = JiraServiceManagement("https://example.atlassian.net")
+    payload = {"id": 42, "config": {"goals": []}}
+
+    with patch.object(service_management, "put", return_value=payload) as put:
+        result = service_management.update_sla_metric("10", "42", payload)
+
+    assert result == payload
+    put.assert_called_once_with(
+        "rest/servicedesk/1/servicedesk/agent/10/sla/metrics/42",
+        data=payload,
+    )