Add create_namespace method to Index and IndexAsyncio

[jhamon]

Add create_namespace method to Index and IndexAsyncio

Summary

This PR adds the create_namespace method to both synchronous and asynchronous Index clients, as well as the GRPC implementation. The method allows users to create namespaces in serverless indexes with optional schema configuration.

Changes

REST API Implementation (Sync & Async)

• Request Factory (pinecone/db_data/resources/sync/namespace_request_factory.py):

  • Added CreateNamespaceArgs TypedDict
  • Added create_namespace_args method with validation for namespace name and optional schema handling

• Resource Classes:

  • NamespaceResource.create() - Synchronous implementation
  • NamespaceResourceAsyncio.create() - Asynchronous implementation
  • Both methods accept name and optional schema (as dictionary) parameters

• Interface Definitions:

  • Added create_namespace() abstract method to IndexInterface
  • Added create_namespace() abstract method to IndexAsyncioInterface
  • Both include comprehensive RST docstrings with examples

• Class Implementations:

  • Index.create_namespace() - Delegates to namespace resource
  • IndexAsyncio.create_namespace() - Delegates to namespace resource with async support

GRPC Implementation

• GRPCIndex (pinecone/grpc/index_grpc.py):
  • Added create_namespace() method with async_req support for GRPC futures
  • Handles schema conversion from dictionary to MetadataSchema proto object
  • Supports both synchronous and asynchronous (future-based) execution

Testing

• Unit Tests (tests/unit_grpc/test_grpc_index_namespace.py):

  • test_create_namespace - Basic functionality
  • test_create_namespace_with_timeout - Timeout handling
  • test_create_namespace_with_schema - Schema conversion validation

• Integration Tests (tests/integration/data/test_namespace.py):

  • test_create_namespace - Successful namespace creation
  • test_create_namespace_duplicate - Error handling for duplicate namespaces

• Integration Tests (tests/integration/data_asyncio/test_namespace_asyncio.py):

  • test_create_namespace - Async successful namespace creation
  • test_create_namespace_duplicate - Async error handling for duplicate namespaces

• GRPC Futures Integration Tests (tests/integration/data_grpc_futures/test_namespace_future.py):

  • test_create_namespace_future - Creating namespace with async_req=True
  • test_create_namespace_future_duplicate - Error handling with futures
  • test_create_namespace_future_multiple - Concurrent namespace creation

API Design

The create_namespace method signature is consistent across all implementations:

def create_namespace(
    self, 
    name: str, 
    schema: Optional[Dict[str, Any]] = None, 
    **kwargs
) -> NamespaceDescription

• Public API: Uses Optional[Dict[str, Any]] for schema to avoid exposing OpenAPI types
• Schema Format: Accepts a dictionary with fields key containing field definitions
• Returns: NamespaceDescription object containing namespace information

Examples

REST API (Synchronous)

from pinecone import Pinecone

pc = Pinecone()
index = pc.Index(host="example-index.svc.pinecone.io")

# Create namespace without schema
namespace = index.create_namespace(name="my-namespace")

# Create namespace with schema
schema = {
    "fields": {
        "field1": {"filterable": True},
        "field2": {"filterable": False}
    }
}
namespace = index.create_namespace(name="my-namespace", schema=schema)

REST API (Asynchronous)

import asyncio
from pinecone import Pinecone

async def main():
    pc = Pinecone()
    async with pc.IndexAsyncio(host="example-index.svc.pinecone.io") as index:
        namespace = await index.create_namespace(name="my-namespace")
        print(f"Created namespace: {namespace.name}")

asyncio.run(main())

GRPC (Synchronous)

from pinecone.grpc import PineconeGRPC

pc = PineconeGRPC()
index = pc.Index(host="example-index.svc.pinecone.io")

namespace = index.create_namespace(name="my-namespace")

GRPC (Asynchronous/Futures)

from pinecone.grpc import PineconeGRPC
from concurrent.futures import as_completed

pc = PineconeGRPC()
index = pc.Index(host="example-index.svc.pinecone.io")

# Create namespace asynchronously
future = index.create_namespace(name="my-namespace", async_req=True)
namespace = future.result(timeout=30)

# Create multiple namespaces concurrently
futures = [
    index.create_namespace(name=f"ns-{i}", async_req=True) 
    for i in range(3)
]
for future in as_completed(futures):
    namespace = future.result()
    print(f"Created: {namespace.name}")

Type Hints

• Public-facing methods use Optional[Dict[str, Any]] for schema parameter
• Internal resource methods handle conversion from dict to OpenAPI models
• GRPC implementation converts dict to MetadataSchema proto object

Error Handling

• Validates that namespace name is a non-empty string
• Raises PineconeApiException for REST API errors
• Raises PineconeException for GRPC errors
• Properly handles duplicate namespace creation attempts

Documentation

All methods include comprehensive RST docstrings with:

• Parameter descriptions
• Return value descriptions
• Usage examples
• Links to relevant documentation

Testing Status

✅ All unit tests passing
✅ All integration tests passing (REST sync/async)
✅ All GRPC futures integration tests passing

Notes

• This operation is only supported for serverless indexes
• Namespaces must have unique names within an index
• Schema configuration is optional and can be added when creating the namespace or later