fix(collections): add resource name validation to Collections.create

## Purpose

The backend rejects collection names with uppercase letters, underscores,
special characters, leading/trailing hyphens, or names longer than 45 chars
with a generic 400 error. The SDK only checked for empty strings, so invalid
names surfaced as confusing server errors instead of clear client-side
ValidationErrors.

## Solution

Added `require_valid_resource_name` helper to `pinecone/_internal/validation.py`
that enforces the same constraints as the backend's `is_valid_resource_name`:
- non-empty and non-whitespace
- at most 45 characters
- no leading or trailing hyphen
- only lowercase alphanumeric and hyphen characters allowed

Replaced `require_non_empty("name", name)` with `require_valid_resource_name`
in both `Collections.create` and `AsyncCollections.create`. Updated docstrings
to document the constraints. Added unit tests covering all rejection conditions
and the happy path, plus parametrized integration tests for invalid names in
both sync and async variants.

Author: jhamon

pinecone/_internal/validation.py

@@ -49,3 +49,29 @@ def require_one_of(name: str, value: str, allowed: Sequence[str]) -> None:
     if value not in allowed:
         opts = ", ".join(repr(a) for a in allowed)
         raise ValidationError(f"{name} must be one of {opts}, got {value!r}")
+
+
+_RESOURCE_NAME_MAX_LEN = 45
+_RESOURCE_NAME_CHARS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789-")
+
+
+def require_valid_resource_name(name: str, value: str) -> None:
+    """Raise ValidationError if value is not a valid Pinecone resource name.
+
+    Valid names are non-empty, at most 45 characters, consist only of lowercase
+    alphanumeric characters and hyphens, and must not start or end with a hyphen.
+    """
+    if not value or not value.strip():
+        raise ValidationError(f"{name} must be a non-empty string")
+    if len(value) > _RESOURCE_NAME_MAX_LEN:
+        raise ValidationError(
+            f"{name} is too long (max {_RESOURCE_NAME_MAX_LEN} characters, got {len(value)})"
+        )
+    if value[0] == "-":
+        raise ValidationError(f"{name} must not start with a hyphen")
+    if value[-1] == "-":
+        raise ValidationError(f"{name} must not end with a hyphen")
+    if not all(c in _RESOURCE_NAME_CHARS for c in value):
+        raise ValidationError(
+            f"{name} contains invalid characters; must be lowercase alphanumeric and hyphens only"
+        )

pinecone/async_client/collections.py

@@ -6,7 +6,7 @@
 from typing import TYPE_CHECKING
 
 from pinecone._internal.adapters.collections_adapter import CollectionsAdapter
-from pinecone._internal.validation import require_non_empty
+from pinecone._internal.validation import require_non_empty, require_valid_resource_name
 from pinecone.models.collections.list import CollectionList
 from pinecone.models.collections.model import CollectionModel
 
@@ -57,7 +57,9 @@ async def create(self, *, name: str, source: str) -> CollectionModel:
             A CollectionModel describing the created collection.
 
         Raises:
-            ValidationError: If *name* or *source* is empty.
+            ValidationError: If *name* is empty, longer than 45 characters, contains
+                characters outside ``[a-z0-9-]``, or starts/ends with a hyphen.
+                Also raised if *source* is empty.
 
         Examples:
 
@@ -66,7 +68,7 @@ async def create(self, *, name: str, source: str) -> CollectionModel:
                 col = await pc.collections.create(name="my-collection", source="my-index")
                 print(col.status)
         """
-        require_non_empty("name", name)
+        require_valid_resource_name("name", name)
         require_non_empty("source", source)
         logger.info("Creating collection %r from source %r", name, source)
         response = await self._http.post("/collections", json={"name": name, "source": source})

pinecone/client/collections.py

@@ -6,7 +6,7 @@
 from typing import TYPE_CHECKING
 
 from pinecone._internal.adapters.collections_adapter import CollectionsAdapter
-from pinecone._internal.validation import require_non_empty
+from pinecone._internal.validation import require_non_empty, require_valid_resource_name
 from pinecone.models.collections.list import CollectionList
 from pinecone.models.collections.model import CollectionModel
 
@@ -56,7 +56,9 @@ def create(self, *, name: str, source: str) -> CollectionModel:
             A CollectionModel describing the created collection.
 
         Raises:
-            ValidationError: If *name* or *source* is empty.
+            ValidationError: If *name* is empty, longer than 45 characters, contains
+                characters outside ``[a-z0-9-]``, or starts/ends with a hyphen.
+                Also raised if *source* is empty.
             ApiError: If the API returns an error response (e.g. authentication
                 failure or server error).
 
@@ -65,7 +67,7 @@ def create(self, *, name: str, source: str) -> CollectionModel:
             >>> col.status  # doctest: +SKIP
             'Initializing'
         """
-        require_non_empty("name", name)
+        require_valid_resource_name("name", name)
         require_non_empty("source", source)
         logger.info("Creating collection %r from source %r", name, source)
         response = self._http.post("/collections", json={"name": name, "source": source})

tests/integration/test_client.py

@@ -10,6 +10,7 @@
 import respx
 
 from pinecone import Pinecone
+from pinecone.errors.exceptions import ValidationError
 from pinecone.models.backups.model import CreateIndexFromBackupResponse
 from tests.factories import make_index_response
 
@@ -251,3 +252,27 @@ def test_create_byoc_index_method_schema_forwarded() -> None:
 
     sent_body = json.loads(route.calls[0].request.content)
     assert sent_body["spec"]["byoc"]["schema"] == {"genre": {"type": "str"}}
+
+
+# ---------------------------------------------------------------------------
+# Collection name validation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "invalid_name",
+    [
+        "INVALID_NAME!",
+        "MY_COLLECTION",
+        "-leading",
+        "trailing-",
+        "a" * 46,
+        "underscore_name",
+        "test@name",
+    ],
+)
+def test_create_collection_invalid_name(invalid_name: str) -> None:
+    """Collections.create raises ValidationError for invalid names before any network call."""
+    pc = Pinecone(api_key="test-key")
+    with pytest.raises(ValidationError):
+        pc.collections.create(name=invalid_name, source="fake-index")

tests/integration/test_client_async.py

@@ -5,6 +5,7 @@
 import pytest
 
 from pinecone import AsyncPinecone
+from pinecone.errors.exceptions import ValidationError
 
 
 @pytest.mark.integration
@@ -21,3 +22,27 @@ async def test_async_client_init_with_api_key(async_client: AsyncPinecone) -> No
 
     assert isinstance(__version__, str)
     assert len(__version__) > 0
+
+
+# ---------------------------------------------------------------------------
+# Collection name validation
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "invalid_name",
+    [
+        "INVALID_NAME!",
+        "MY_COLLECTION",
+        "-leading",
+        "trailing-",
+        "a" * 46,
+        "underscore_name",
+        "test@name",
+    ],
+)
+async def test_create_collection_invalid_name_async(invalid_name: str) -> None:
+    """AsyncCollections.create raises ValidationError for invalid names before any network call."""
+    pc = AsyncPinecone(api_key="test-key")
+    with pytest.raises(ValidationError):
+        await pc.collections.create(name=invalid_name, source="fake-index")

tests/unit/test_require_valid_resource_name.py

@@ -0,0 +1,75 @@
+"""Unit tests for require_valid_resource_name validation helper."""
+
+from __future__ import annotations
+
+import pytest
+
+from pinecone._internal.validation import require_valid_resource_name
+from pinecone.errors.exceptions import ValidationError
+
+
+def test_valid_name_lowercase_alphanumeric() -> None:
+    require_valid_resource_name("name", "mycollection")
+
+
+def test_valid_name_with_hyphens() -> None:
+    require_valid_resource_name("name", "my-collection-2025")
+
+
+def test_valid_name_max_length() -> None:
+    require_valid_resource_name("name", "a" * 45)
+
+
+def test_valid_name_single_char() -> None:
+    require_valid_resource_name("name", "a")
+
+
+def test_empty_string_raises() -> None:
+    with pytest.raises(ValidationError, match="non-empty"):
+        require_valid_resource_name("name", "")
+
+
+def test_whitespace_only_raises() -> None:
+    with pytest.raises(ValidationError, match="non-empty"):
+        require_valid_resource_name("name", "   ")
+
+
+def test_too_long_raises() -> None:
+    with pytest.raises(ValidationError, match="too long"):
+        require_valid_resource_name("name", "a" * 46)
+
+
+def test_leading_hyphen_raises() -> None:
+    with pytest.raises(ValidationError, match="must not start with a hyphen"):
+        require_valid_resource_name("name", "-leading")
+
+
+def test_trailing_hyphen_raises() -> None:
+    with pytest.raises(ValidationError, match="must not end with a hyphen"):
+        require_valid_resource_name("name", "trailing-")
+
+
+def test_uppercase_raises() -> None:
+    with pytest.raises(ValidationError, match="invalid characters"):
+        require_valid_resource_name("name", "MY_COLLECTION")
+
+
+def test_underscore_raises() -> None:
+    with pytest.raises(ValidationError, match="invalid characters"):
+        require_valid_resource_name("name", "under_score")
+
+
+def test_at_symbol_raises() -> None:
+    with pytest.raises(ValidationError, match="invalid characters"):
+        require_valid_resource_name("name", "test@name")
+
+
+def test_space_raises() -> None:
+    with pytest.raises(ValidationError, match="invalid characters"):
+        require_valid_resource_name("name", "my collection")
+
+
+def test_error_message_includes_param_name() -> None:
+    with pytest.raises(ValidationError) as exc_info:
+        require_valid_resource_name("collection_name", "INVALID!")
+    assert "collection_name" in str(exc_info.value)