fix(preview): add complete tag validation to PreviewIndexes.create and configure

## Purpose

The SDK only validated tag key/value length but not character-set constraints
or the 20-tag maximum. Users with invalid keys (e.g., containing '!') or
non-ASCII values received confusing 400 errors from the backend instead of
descriptive client-side errors.

## Solution

Extracted tag validation into a shared helper
`pinecone.preview._internal.validation.validate_tags` that enforces all three
backend constraints:
- Keys: alphanumeric, '_', '-' only; ≤80 chars
- Values: printable ASCII only; ≤120 chars
- Maximum of 20 tags

Replaced the inline length-only loops in `PreviewIndexes.create`,
`PreviewIndexes.configure`, `AsyncPreviewIndexes.create`, and
`AsyncPreviewIndexes.configure` with a single `validate_tags(tags)` call.
Updated docstrings to document all constraints.

Added 13 unit tests covering valid/invalid key characters, non-ASCII values,
control characters, boundary conditions (exactly 20/80/120), and None input.

Author: jhamon

pinecone/preview/_internal/validation.py

@@ -0,0 +1,36 @@
+"""Preview-specific input validation helpers."""
+
+from __future__ import annotations
+
+import re
+
+from pinecone.errors.exceptions import PineconeValueError
+
+_TAG_KEY_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+_MAX_TAGS = 20
+_MAX_KEY_LEN = 80
+_MAX_VAL_LEN = 120
+
+
+def validate_tags(tags: dict[str, str] | None) -> None:
+    """Raise PineconeValueError if any tag violates backend constraints."""
+    if tags is None:
+        return
+    if len(tags) > _MAX_TAGS:
+        raise PineconeValueError(f"Tags exceeded the maximum of {_MAX_TAGS}. Got {len(tags)} tags.")
+    for key, value in tags.items():
+        if len(key) > _MAX_KEY_LEN:
+            raise PineconeValueError(f"Tag key {key!r} exceeds the {_MAX_KEY_LEN}-character limit.")
+        if not _TAG_KEY_RE.match(key):
+            raise PineconeValueError(
+                f"Tag key {key!r} has invalid characters. Must be alphanumeric or '_', '-'."
+            )
+        if len(value) > _MAX_VAL_LEN:
+            raise PineconeValueError(
+                f"Tag value for key {key!r} exceeds the {_MAX_VAL_LEN}-character limit."
+            )
+        if not value.isascii() or not value.isprintable():
+            raise PineconeValueError(
+                f"Tag value for key {key!r} contains invalid characters. "
+                "Only printable ASCII characters are allowed."
+            )

pinecone/preview/async_indexes.py

@@ -24,6 +24,7 @@
     PreviewListIndexesAdapter,
 )
 from pinecone.preview._internal.constants import INDEXES_API_VERSION
+from pinecone.preview._internal.validation import validate_tags
 from pinecone.preview.models.backups import PreviewBackupModel, PreviewCreateBackupRequest
 from pinecone.preview.models.indexes import PreviewIndexModel
 from pinecone.preview.models.requests import PreviewConfigureIndexRequest, PreviewCreateIndexRequest
@@ -147,7 +148,9 @@ async def create(
                 ``"enabled"`` or ``"disabled"``. Defaults to ``"disabled"``
                 if not provided.
             tags: Optional key-value tags for the index. Keys must be at most
-                80 characters; values must be at most 120 characters.
+                80 characters and contain only alphanumeric characters,
+                underscores, or hyphens. Values must be at most 120 printable
+                ASCII characters. A maximum of 20 tags is allowed.
             source_collection: Optional name of an existing collection to
                 create the index from.
             source_backup_id: Optional ID of an existing backup to create
@@ -162,7 +165,9 @@ async def create(
 
         Raises:
             :exc:`~pinecone.errors.exceptions.PineconeValueError`: If a tag key
-                exceeds 80 characters or a tag value exceeds 120 characters.
+                exceeds 80 characters, contains invalid characters, if a tag
+                value exceeds 120 characters or contains non-ASCII/non-printable
+                characters, or if more than 20 tags are provided.
             :exc:`~pinecone.errors.exceptions.ApiError`: If the API returns an
                 error response.
 
@@ -174,14 +179,7 @@ async def create(
                     name="my-preview-index",
                 )
         """
-        if tags is not None:
-            for key, value in tags.items():
-                if len(key) > 80:
-                    raise PineconeValueError(f"Tag key {key!r} exceeds the 80-character limit.")
-                if len(value) > 120:
-                    raise PineconeValueError(
-                        f"Tag value for key {key!r} exceeds the 120-character limit."
-                    )
+        validate_tags(tags)
 
         req = PreviewCreateIndexRequest(
             schema=schema,
@@ -318,14 +316,7 @@ async def main():
                 "schema, deletion_protection, tags, read_capacity, or deployment"
             )
 
-        if tags is not None:
-            for key, value in tags.items():
-                if len(key) > 80:
-                    raise PineconeValueError(f"Tag key {key!r} exceeds the 80-character limit.")
-                if len(value) > 120:
-                    raise PineconeValueError(
-                        f"Tag value for key {key!r} exceeds the 120-character limit."
-                    )
+        validate_tags(tags)
 
         req = PreviewConfigureIndexRequest(
             schema=schema,

pinecone/preview/indexes.py

@@ -23,6 +23,7 @@
     PreviewListIndexesAdapter,
 )
 from pinecone.preview._internal.constants import INDEXES_API_VERSION
+from pinecone.preview._internal.validation import validate_tags
 from pinecone.preview.models.backups import PreviewBackupModel, PreviewCreateBackupRequest
 from pinecone.preview.models.indexes import PreviewIndexModel
 from pinecone.preview.models.requests import PreviewConfigureIndexRequest, PreviewCreateIndexRequest
@@ -137,7 +138,9 @@ def create(
                 ``"enabled"`` or ``"disabled"``. Defaults to ``"disabled"``
                 if not provided.
             tags: Optional key-value tags for the index. Keys must be at most
-                80 characters; values must be at most 120 characters.
+                80 characters and contain only alphanumeric characters,
+                underscores, or hyphens. Values must be at most 120 printable
+                ASCII characters. A maximum of 20 tags is allowed.
             source_collection: Optional name of an existing collection to
                 create the index from.
             source_backup_id: Optional ID of an existing backup to create
@@ -152,7 +155,9 @@ def create(
 
         Raises:
             :exc:`~pinecone.errors.exceptions.PineconeValueError`: If a tag key
-                exceeds 80 characters or a tag value exceeds 120 characters.
+                exceeds 80 characters, contains invalid characters, if a tag
+                value exceeds 120 characters or contains non-ASCII/non-printable
+                characters, or if more than 20 tags are provided.
             :exc:`~pinecone.errors.exceptions.ApiError`: If the API returns an
                 error response.
 
@@ -164,14 +169,7 @@ def create(
                     name="my-preview-index",
                 )
         """
-        if tags is not None:
-            for key, value in tags.items():
-                if len(key) > 80:
-                    raise PineconeValueError(f"Tag key {key!r} exceeds the 80-character limit.")
-                if len(value) > 120:
-                    raise PineconeValueError(
-                        f"Tag value for key {key!r} exceeds the 120-character limit."
-                    )
+        validate_tags(tags)
 
         req = PreviewCreateIndexRequest(
             schema=schema,
@@ -304,14 +302,7 @@ def configure(
                 "schema, deletion_protection, tags, read_capacity, or deployment"
             )
 
-        if tags is not None:
-            for key, value in tags.items():
-                if len(key) > 80:
-                    raise PineconeValueError(f"Tag key {key!r} exceeds the 80-character limit.")
-                if len(value) > 120:
-                    raise PineconeValueError(
-                        f"Tag value for key {key!r} exceeds the 120-character limit."
-                    )
+        validate_tags(tags)
 
         req = PreviewConfigureIndexRequest(
             schema=schema,

tests/unit/test_preview_tag_validation.py

@@ -0,0 +1,69 @@
+"""Unit tests for preview tag validation helper."""
+
+from __future__ import annotations
+
+import pytest
+
+from pinecone.errors.exceptions import PineconeValueError
+from pinecone.preview._internal.validation import validate_tags
+
+
+def test_validate_tags_none_ok() -> None:
+    validate_tags(None)
+
+
+def test_validate_tags_valid_ok() -> None:
+    validate_tags({"key-1": "val1", "key_2": "val2"})
+
+
+def test_validate_tags_empty_value_ok() -> None:
+    validate_tags({"key": ""})
+
+
+def test_validate_tags_special_char_key_raises() -> None:
+    with pytest.raises(PineconeValueError, match="invalid characters"):
+        validate_tags({"bad-key!": "val"})
+
+
+def test_validate_tags_non_ascii_key_raises() -> None:
+    with pytest.raises(PineconeValueError, match="invalid characters"):
+        validate_tags({"藏": "val"})
+
+
+def test_validate_tags_non_ascii_value_raises() -> None:
+    with pytest.raises(PineconeValueError, match="invalid characters"):
+        validate_tags({"key": "日本語"})
+
+
+def test_validate_tags_control_char_value_raises() -> None:
+    with pytest.raises(PineconeValueError, match="invalid characters"):
+        validate_tags({"key": "val\x00"})
+
+
+def test_validate_tags_too_many_raises() -> None:
+    tags = {f"key{i}": f"val{i}" for i in range(21)}
+    with pytest.raises(PineconeValueError, match="maximum of 20"):
+        validate_tags(tags)
+
+
+def test_validate_tags_exactly_20_ok() -> None:
+    tags = {f"key{i}": f"val{i}" for i in range(20)}
+    validate_tags(tags)
+
+
+def test_validate_tags_key_too_long_raises() -> None:
+    with pytest.raises(PineconeValueError, match="80-character limit"):
+        validate_tags({"a" * 81: "val"})
+
+
+def test_validate_tags_key_exactly_80_ok() -> None:
+    validate_tags({"a" * 80: "val"})
+
+
+def test_validate_tags_value_too_long_raises() -> None:
+    with pytest.raises(PineconeValueError, match="120-character limit"):
+        validate_tags({"key": "v" * 121})
+
+
+def test_validate_tags_value_exactly_120_ok() -> None:
+    validate_tags({"key": "v" * 120})