Define enum classes with control plane configuration options

[jhamon]

Problem

Many configuration fields take string inputs even though there is a limited range of accepted values. It's poor UX having to go into documentation or examples in order to know which string values are available. This also means support via type hints from code editors are not available to keep people moving quickly.

Solution

• Create Enum classes for control plane configuration fields under pinecone.enum:
  • General index configs: Metric, VectorType, DeletionProtection
  • Serverless spec: CloudProvider, AwsRegion, GcpRegion, AzureRegion
  • Pod spec: PodIndexEnvironment, PodType

kwargs that accept these values are loosely typed as the union of the enum type and string. This should prevent unnecessary breaking changes and maintain flexibility to accept new values that may not be avaialble or known at the time this SDK release is published. For example, if in the future pinecone can deploy to more Azure regions, this loose typing would allow a person to pass that configuration as region without necessarily having to update their SDK to satisfy to a type check.

Usage: Serverless

# Old way, which still works but requires you to know what values are available
from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key='key')

pc.create_index(
    name="my-index",
    dimension=1024,
    metric="cosine",
    spec=ServerlessSpec(
        cloud="aws", 
        region="us-west-2"
    ),
    vector_type="sparse"
)

# New way, using enum types
from pinecone import (
    Pinecone, 
    ServerlessSpec, 
    Metric, 
    VectorType, 
    CloudProvider, 
    AwsRegion
)

pc = Pinecone(api_key='key')

pc.create_index(
    name="my-index",
    dimension=1024,
    metric=Metric.COSINE,
    spec=ServerlessSpec(
        cloud=CloudProvider.AWS, 
        region=AwsRegion.US_WEST_2
    ),
    vector_type=VectorType.SPARSE
)

Usage: Pods

# old way, you have to know all the magic strings

from pinecone import Pinecone, PodSpec

pc = Pinecone(api_key='key')

pc.create_index(
    name="my-index",
    dimension=1024,
    spec=PodSpec(
        pod_type='s1.x4'
        environment="us-east1-gcp"
    ),
)

# Later, when scaling
pc.configure_index(
    name="my-index",
    pod_type="s1.x8"
)

# New way, using enum types
from pinecone import (
    Pinecone, 
    PodSpec, 
    PodIndexEnvironment,
    PodType
)

pc = Pinecone(api_key='key')

pc.create_index(
    name="my-index",
    dimension=1024,
    spec=PodSpec(
        environment=PodIndexEnvironment.US_EAST1_GCP,
        pod_type=PodType.S1_X4
    )
)

# Later, when scaling
pc.configure_index(
    name="my-index",
    pod_type=PodType.S1_X8
)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• Infrastructure change (CI configs, etc)
• Non-code change (docs, etc)
• None of the above: (explain here)