Cloud specs reduce extra params #997

Author: gonchik

README.rst

@@ -121,6 +121,20 @@ not base64-encode them yourself.
     page = confluence_v2.get_page_by_id("123456789", body_format="storage")
     storage_xhtml = page["body"]["storage"]["value"]
 
+    # Alternative Confluence Cloud V2 page read. Use the site URL without a trailing /wiki;
+    # the client adds the required API context.
+    from atlassian import Confluence
+
+    confluence_v2 = Confluence(
+        "https://your-domain.atlassian.net",
+        username="you@example.com",
+        password="cloud-api-token",
+        api_version=2,  # Specify API version 2
+        cloud=True
+    )
+    page = confluence_v2.get_page_by_id("123456789", body_format="storage")
+    storage_xhtml = page["body"]["storage"]["value"]
+
 See the detailed `authentication documentation`_ for Cloud gateway/scoped-token
 notes and other authentication methods.
 
@@ -169,15 +183,13 @@ The library now supports Confluence's v2 API for Cloud instances. The v2 API pro
 
 .. code-block:: python
 
-    from atlassian import Confluence
+    from atlassian import ConfluenceV2
 
-    # Initialize with v2 API
-    confluence = Confluence(
-        url='https://your-instance.atlassian.net/wiki',
+    # ConfluenceV2 is an explicit Cloud V2 client; no cloud=True flag is needed.
+    confluence = ConfluenceV2(
+        url='https://your-instance.atlassian.net',
         username='your-email@example.com',
         password='your-api-token',
-        api_version=2,  # Specify API version 2
-        cloud=True      # v2 API is only available for cloud instances
     )
 
     # Get pages from a space

atlassian/confluence/__init__.py

@@ -6,6 +6,7 @@
 """
 
 from urllib.parse import urlparse
+import warnings
 
 from ..confluence_base import ConfluenceBase
 from .cloud import Cloud as LegacyConfluenceCloud
@@ -31,6 +32,15 @@ def __new__(cls, url, *args, **kwargs):
     def __init__(self, url, *args, **kwargs):
         if type(self) is not Confluence:
             return
+        if kwargs.get("api_version") == "cloud":
+            warnings.warn(
+                "api_version='cloud' is deprecated; use cloud=True, or "
+                "ConfluenceV2 for the Cloud V2 API.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            kwargs.pop("api_version")
+            kwargs["cloud"] = True
         # Detect which implementation to use
         # Priority: explicit cloud= kwarg > URL-based heuristic
         is_cloud = kwargs.get("cloud")

atlassian/confluence/cloud/__init__.py

@@ -3,6 +3,7 @@
 import logging
 import re
 import time
+import warnings
 from urllib.parse import quote
 from .base import ConfluenceCloudBase
 import requests
@@ -22,6 +23,14 @@ class Cloud(ConfluenceCloudBase):
     """
 
     def __init__(self, url="https://api.atlassian.com/", *args, **kwargs):
+        if kwargs.get("api_version") == "cloud":
+            warnings.warn(
+                "api_version='cloud' is deprecated; ConfluenceCloud already "
+                "selects Cloud endpoints.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            kwargs.pop("api_version")
         # Set default values only if not provided
         if "cloud" not in kwargs:
             kwargs["cloud"] = True

docs/confluence.rst

@@ -341,8 +341,8 @@ Page actions
     confluence.has_unknown_attachment_error(page_id)
 
     # Export page as PDF
-    # api_version needs to be set to 'cloud' when exporting from Confluence Cloud
-    .
+    # Use ConfluenceCloud (or Confluence(..., cloud=True)) for Cloud exports.
+    # ``api_version='cloud'`` is deprecated; use ConfluenceV2 for Cloud V2 APIs.
     confluence.export_page(page_id)
 
     # Server/Data Center only: legacy Word exporter. The returned bytes are a

tests/confluence/test_confluence_cloud.py

@@ -35,6 +35,12 @@ def test_init_custom_values(self):
         assert confluence.api_version == "1"
         assert confluence.api_root == "custom/api/root"
 
+    def test_legacy_cloud_api_version_is_normalized(self):
+        with pytest.warns(DeprecationWarning):
+            confluence = ConfluenceCloud(url="https://test.atlassian.net", api_version="cloud")
+
+        assert confluence.api_version == "2"
+
     @patch.object(ConfluenceCloud, "_get_paged")
     def test_iter_cql_follows_all_result_pages(self, mock_get_paged, confluence_cloud):
         mock_get_paged.return_value = iter([{"id": "1"}, {"id": "2"}])

tests/confluence/test_confluence_routing.py

@@ -3,6 +3,8 @@
 
 from unittest.mock import patch
 
+import pytest
+
 from atlassian.confluence import Confluence, ConfluenceCloud, ConfluenceServer
 from atlassian.confluence.cloud.cloud import ConfluenceCloud as V2ConfluenceCloud
 
@@ -65,3 +67,11 @@ def test_explicit_cloud_false_overrides_url(self, mock_server, mock_cloud):
         Confluence("https://mysite.atlassian.net", cloud=False)
         mock_server.assert_called_once()
         mock_cloud.assert_not_called()
+
+    def test_legacy_cloud_api_version_is_normalized_to_cloud_flag(self):
+        """The historical api_version='cloud' spelling remains compatible."""
+        with pytest.warns(DeprecationWarning):
+            client = Confluence("https://confluence.example.test", api_version="cloud")
+
+        assert client._impl.cloud is True
+        assert client._impl.api_version == "2"