fix(backups): omit description from wire payload when not provided

## Purpose

`Backups.create` was unconditionally writing `body["description"] = description`
with a default of `""`. This prevented callers from ever reaching the backend's
`None` storage state — every backup received `description: Some("")` instead of
`None`, making the two states indistinguishable.

## Solution

Changed `description` parameter from `str = ""` to `str | None = None` in both
sync (`Backups.create`) and async (`AsyncBackups.create`) implementations, and in
both backcompat shims (`Pinecone.create_backup`, `AsyncPinecone.create_backup`).
The body assignment is now conditional on `description is not None`, so omitting
the parameter leaves the field absent from the JSON payload.

Updated unit tests to assert the new behaviour: description absent when not
provided, present when explicitly passed (including `""`).

Author: jhamon

pinecone/_client.py

@@ -690,7 +690,7 @@ def create_backup(
         *,
         index_name: str,
         backup_name: str | None = None,
-        description: str = "",
+        description: str | None = None,
     ) -> BackupModel:
         """Backwards-compatibility shim for :meth:`Pinecone.backups.create`.
 

pinecone/async_client/backups.py

@@ -48,14 +48,15 @@ async def create(
         *,
         index_name: str,
         name: str | None = None,
-        description: str = "",
+        description: str | None = None,
     ) -> BackupModel:
         """Create a backup of an existing index.
 
         Args:
             index_name (str): Name of the index to back up.
             name (str | None): Optional name for the backup.
-            description (str): Description for the backup (defaults to empty string).
+            description (str | None): Description for the backup. When ``None``
+                (the default), no description is sent and the backend stores ``None``.
 
         Returns:
             A :class:`BackupModel` describing the created backup.
@@ -90,7 +91,8 @@ async def create(
         body: dict[str, Any] = {}
         if name is not None:
             body["name"] = name
-        body["description"] = description
+        if description is not None:
+            body["description"] = description
         logger.info("Creating backup for index %r", index_name)
         response = await self._http.post(f"/indexes/{index_name}/backups", json=body)
         result = self._adapter.to_backup(response.content)

pinecone/async_client/pinecone.py

@@ -618,7 +618,7 @@ async def create_backup(
         *,
         index_name: str,
         backup_name: str | None = None,
-        description: str = "",
+        description: str | None = None,
     ) -> BackupModel:
         """Backwards-compatibility shim for :meth:`AsyncPinecone.backups.create`.
 

pinecone/client/backups.py

@@ -47,14 +47,15 @@ def create(
         *,
         index_name: str,
         name: str | None = None,
-        description: str = "",
+        description: str | None = None,
     ) -> BackupModel:
         """Create a backup of an existing index.
 
         Args:
             index_name (str): Name of the index to back up.
             name (str | None): Optional name for the backup.
-            description (str): Description for the backup (defaults to empty string).
+            description (str | None): Description for the backup. When ``None``
+                (the default), no description is sent and the backend stores ``None``.
 
         Returns:
             A :class:`BackupModel` describing the created backup.
@@ -80,7 +81,8 @@ def create(
         body: dict[str, Any] = {}
         if name is not None:
             body["name"] = name
-        body["description"] = description
+        if description is not None:
+            body["description"] = description
         logger.info("Creating backup for index %r", index_name)
         response = self._http.post(f"/indexes/{index_name}/backups", json=body)
         result = self._adapter.to_backup(response.content)

tests/unit/test_async_backups.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from collections.abc import AsyncGenerator
 
 import httpx
@@ -49,10 +50,10 @@ async def test_async_create_backup(async_backups: AsyncBackups) -> None:
     assert isinstance(result, BackupModel)
     assert result.backup_id == "670e8400-e29b-41d4-a716-446655440001"
 
-    # Verify body contains empty description when no optional params
+    # Verify description is absent from body when not provided
     request = route.calls[0].request
-    expected_body = httpx.Request("POST", "/", json={"description": ""})
-    assert request.content == expected_body.content
+    body = json.loads(request.content)
+    assert "description" not in body
 
 
 @respx.mock

tests/unit/test_async_pinecone_backcompat.py

@@ -223,7 +223,7 @@ async def test_async_create_backup_delegate_forwards() -> None:
     pc, mock_backups = _make_async_pc_with_mock_backups()
     await pc.create_backup(index_name="my-index", backup_name="my-backup")
     mock_backups.create.assert_called_once_with(
-        index_name="my-index", name="my-backup", description=""
+        index_name="my-index", name="my-backup", description=None
     )
 
 

tests/unit/test_backup_description_default.py

@@ -1,4 +1,4 @@
-"""Unit tests for backup description default — empty string when not provided."""
+"""Unit tests for backup description default — absent from wire payload when not provided."""
 
 from __future__ import annotations
 
@@ -45,14 +45,44 @@ def async_backups(async_http_client: AsyncHTTPClient) -> AsyncBackups:
 
 
 @respx.mock
-def test_create_backup_sends_empty_description_by_default(backups: Backups) -> None:
-    """When description is not provided, an empty string is sent in the body."""
+def test_create_backup_description_default(backups: Backups) -> None:
+    """When description is not provided, it is absent from the wire payload."""
     route = respx.post(f"{BASE_URL}/indexes/test/backups").mock(
         return_value=httpx.Response(201, json=make_backup_response()),
     )
 
     result = backups.create(index_name="test")
 
+    assert isinstance(result, BackupModel)
+    request = route.calls[0].request
+    body = json.loads(request.content)
+    assert "description" not in body
+
+
+@respx.mock
+def test_create_backup_explicit_description_sent(backups: Backups) -> None:
+    """When description is explicitly provided, it is included in the wire payload."""
+    route = respx.post(f"{BASE_URL}/indexes/test/backups").mock(
+        return_value=httpx.Response(201, json=make_backup_response()),
+    )
+
+    result = backups.create(index_name="test", description="my description")
+
+    assert isinstance(result, BackupModel)
+    request = route.calls[0].request
+    body = json.loads(request.content)
+    assert body["description"] == "my description"
+
+
+@respx.mock
+def test_create_backup_empty_string_description_sent(backups: Backups) -> None:
+    """When description is explicitly set to empty string, it is sent in the payload."""
+    route = respx.post(f"{BASE_URL}/indexes/test/backups").mock(
+        return_value=httpx.Response(201, json=make_backup_response()),
+    )
+
+    result = backups.create(index_name="test", description="")
+
     assert isinstance(result, BackupModel)
     request = route.calls[0].request
     body = json.loads(request.content)
@@ -62,10 +92,10 @@ def test_create_backup_sends_empty_description_by_default(backups: Backups) -> N
 
 @respx.mock
 @pytest.mark.anyio
-async def test_async_create_backup_sends_empty_description_by_default(
+async def test_async_create_backup_description_default(
     async_backups: AsyncBackups,
 ) -> None:
-    """Async variant: empty string description sent when not provided."""
+    """Async variant: description absent from wire payload when not provided."""
     route = respx.post(f"{BASE_URL}/indexes/test/backups").mock(
         return_value=httpx.Response(201, json=make_backup_response()),
     )
@@ -75,5 +105,22 @@ async def test_async_create_backup_sends_empty_description_by_default(
     assert isinstance(result, BackupModel)
     request = route.calls[0].request
     body = json.loads(request.content)
-    assert "description" in body
-    assert body["description"] == ""
+    assert "description" not in body
+
+
+@respx.mock
+@pytest.mark.anyio
+async def test_async_create_backup_explicit_description_sent(
+    async_backups: AsyncBackups,
+) -> None:
+    """Async variant: explicit description is included in the wire payload."""
+    route = respx.post(f"{BASE_URL}/indexes/test/backups").mock(
+        return_value=httpx.Response(201, json=make_backup_response()),
+    )
+
+    result = await async_backups.create(index_name="test", description="async desc")
+
+    assert isinstance(result, BackupModel)
+    request = route.calls[0].request
+    body = json.loads(request.content)
+    assert body["description"] == "async desc"

tests/unit/test_backups.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import json
+
 import httpx
 import pytest
 import respx
@@ -45,10 +47,10 @@ def test_create_backup_minimal(backups: Backups) -> None:
     assert isinstance(result, BackupModel)
     assert result.backup_id == "670e8400-e29b-41d4-a716-446655440001"
 
-    # Verify body contains empty description when no optional params
+    # Verify description is absent from body when not provided
     request = route.calls[0].request
-    expected_body = httpx.Request("POST", "/", json={"description": ""})
-    assert request.content == expected_body.content
+    body = json.loads(request.content)
+    assert "description" not in body
 
 
 @respx.mock

tests/unit/test_pinecone_class.py

@@ -342,7 +342,7 @@ def test_forwards(self) -> None:
         pc, mock_backups = _make_pc_with_mock_backups()
         pc.create_backup(index_name="my-index", backup_name="my-backup")
         mock_backups.create.assert_called_once_with(
-            index_name="my-index", name="my-backup", description=""
+            index_name="my-index", name="my-backup", description=None
         )