# Naming Conventions

## Overview

Consistent naming makes code predictable for both humans and AI agents. This document defines naming patterns for all SDK components.

## General Principles

1. **Descriptive over Short**: `create_serverless_index` not `create_idx`
2. **Consistent Terminology**: Use same words for same concepts
3. **No Abbreviations**: Write full words unless universally known (e.g., `id`, `url`, `api`)
4. **Explicit Intent**: Name should reveal purpose without reading implementation

## Files and Directories

### Module Files

**Pattern**: `snake_case.py`

```python
# ✅ Good
client.py
async_client.py
rate_limiter.py
http_config.py

# ❌ Bad
Client.py              # Wrong case
httpclient.py          # Missing underscore
rl.py                  # Abbreviation
utils.py               # Too generic
```

### Directory Names

**Pattern**: `snake_case/`

```python
# ✅ Good
_internal/
http/
models/
inference/

# ❌ Bad
Internal/              # Wrong case
HTTP/                  # Wrong case
inferenceEngine/       # camelCase
```

### Special Files

```python
__init__.py            # Package initialization
__main__.py            # CLI entry point
py.typed               # PEP 561 type marker
```

## Classes

### Regular Classes

**Pattern**: `PascalCase`

```python
# ✅ Good
class HTTPClient:
    pass

class IndexManager:
    pass

class RateLimiter:
    pass

# ❌ Bad
class httpClient:      # Wrong case
class index_manager:   # Wrong case
class RL:              # Abbreviation
```

### Protocol Classes

**Pattern**: `PascalCase` + `Protocol` suffix

```python
# ✅ Good
class ClientProtocol(Protocol):
    pass

class IndexManagerProtocol(Protocol):
    pass

# ❌ Bad
class Client(Protocol):        # Missing Protocol suffix
class IClient(Protocol):        # Don't use "I" prefix
class ClientInterface(Protocol): # Use Protocol not Interface
```

### Exception Classes

**Pattern**: `PascalCase` + `Error` suffix

```python
# ✅ Good
class PineconeError(Exception):
    pass

class APIConnectionError(PineconeError):
    pass

class RateLimitError(PineconeError):
    pass

# ❌ Bad
class Pinecone_Error(Exception):    # Wrong case
class APIConnException(Exception):  # Use Error suffix
class RateLimitExceeded(Exception): # Use Error suffix
```

### Configuration Classes

**Pattern**: `PascalCase` + `Config` suffix

```python
# ✅ Good
class HTTPConfig(Struct):
    pass

class RetryConfig(Struct):
    pass

# ❌ Bad
class HTTPConfiguration(Struct):  # Too long, use Config
class HTTPSettings(Struct):       # Use Config not Settings
class Config(Struct):             # Too generic
```

## Functions and Methods

### Regular Functions

**Pattern**: `snake_case`, verb-based

```python
# ✅ Good
def create_index(name: str) -> Index:
    pass

def list_indexes() -> list[str]:
    pass

def delete_index(name: str) -> None:
    pass

# ❌ Bad
def CreateIndex():        # Wrong case
def index_create():       # Verb should come first
def idx():                # Not descriptive
def doStuff():            # Too vague
```

### Boolean Functions

**Pattern**: `is_`, `has_`, `can_`, `should_` prefixes

```python
# ✅ Good
def is_ready() -> bool:
    pass

def has_data() -> bool:
    pass

def can_retry() -> bool:
    pass

# ❌ Bad
def ready() -> bool:      # Unclear it returns bool
def check_ready():        # What does "check" return?
```

### Private Methods

**Pattern**: Single underscore prefix `_snake_case`

```python
class Client:
    # ✅ Good
    def _make_request(self, url: str) -> dict:
        pass

    def _parse_response(self, response: httpx.Response) -> dict:
        pass

    # ❌ Bad
    def __make_request(self):  # Double underscore (name mangling)
    def MakeRequest(self):     # Wrong case
    def make_request(self):    # Should be private
```

### Async Methods

**Pattern**: Same as sync, no special prefix

```python
# ✅ Good
async def create_index(name: str) -> Index:
    pass

# ❌ Bad
async def async_create_index():    # Don't add "async" prefix
async def create_index_async():    # Don't add "async" suffix
```

## Variables

### Local Variables

**Pattern**: `snake_case`, noun-based

```python
# ✅ Good
index_name = "my-index"
retry_count = 3
api_response = await client.get()

# ❌ Bad
indexName = "my-index"    # Wrong case
idx = "my-index"          # Abbreviation
x = "my-index"            # Not descriptive
```

### Constants

**Pattern**: `UPPER_SNAKE_CASE`

```python
# ✅ Good
DEFAULT_TIMEOUT = 30
MAX_RETRIES = 3
API_BASE_URL = "https://api.pinecone.io"

# ❌ Bad
default_timeout = 30      # Wrong case
DefaultTimeout = 30       # Wrong case
TIMEOUT = 30              # Not specific enough
```

### Private Variables

**Pattern**: Single underscore prefix `_snake_case`

```python
class Client:
    def __init__(self):
        # ✅ Good
        self._http_client = HTTPClient()
        self._api_key = api_key

        # ❌ Bad
        self.__http_client = HTTPClient()  # Double underscore
        self.http_client = HTTPClient()    # Should be private
```

### Type Variables

**Pattern**: Short `PascalCase` (T, KT, VT) or descriptive

```python
# ✅ Good
T = TypeVar("T")
KT = TypeVar("KT")  # Key type
VT = TypeVar("VT")  # Value type
ResponseT = TypeVar("ResponseT")

# ❌ Bad
t = TypeVar("t")              # Wrong case
type_var = TypeVar("type")    # Wrong case
```

## Parameters and Arguments

### Function Parameters

**Pattern**: `snake_case`, descriptive

```python
# ✅ Good
def create_index(
    name: str,
    dimension: int,
    metric: str = "cosine",
    timeout: int = 30
) -> Index:
    pass

# ❌ Bad
def create_index(n, d, m, t):  # Not descriptive
def create_index(indexName):   # Wrong case
```

### Keyword Arguments

**Pattern**: Always use descriptive names

```python
# ✅ Good
client.create_index(
    name="my-index",
    dimension=1536,
    metric="cosine"
)

# ❌ Bad
client.create_index("my-index", 1536, "cosine")  # Positional only
```

## Properties

### Property Names

**Pattern**: `snake_case`, noun-based

```python
class Client:
    # ✅ Good
    @property
    def api_key(self) -> str:
        return self._api_key

    @property
    def is_connected(self) -> bool:
        return self._connected

    # ❌ Bad
    @property
    def get_api_key(self):     # Don't use "get" prefix
        return self._api_key

    @property
    def ApiKey(self):          # Wrong case
        return self._api_key
```

## Namespaces

### Public Namespaces

**Pattern**: Plural nouns for collections, singular for operations

```python
# ✅ Good
client.indexes              # Collection of indexes
client.inference            # Singular namespace
index.data                  # Data operations

# ❌ Bad
client.index_manager        # Implementation detail
client.embed                # Should be client.inference.embed
```

## Type Aliases

### Type Alias Names

**Pattern**: `PascalCase`, descriptive

```python
# ✅ Good
Vector = list[float]
Metadata = dict[str, Any]
IndexName = str

# ❌ Bad
vector = list[float]        # Wrong case
Vec = list[float]           # Abbreviation
ListFloat = list[float]     # Too generic
```

## HTTP and API Terms

### Standardized Terms

Always use these exact terms:

```python
# HTTP Operations
request, response, endpoint, url, headers, body

# API Concepts
api_key, timeout, retry, rate_limit

# Pinecone Concepts
index, namespace, vector, metadata, embedding
dimension, metric, host, environment

# Don't use variations:
# ❌ idx, vec, meta, env, req, resp, hdr
```

## Acronyms

### Acronym Capitalization

**Pattern**: Treat as words in PascalCase/snake_case

```python
# ✅ Good
class HTTPClient:           # HTTP stays uppercase
class ApiError:             # API as word
def parse_json():           # json lowercase
url_path: str               # url lowercase

# ❌ Bad
class HttpClient:           # Well-known acronym
class APIError:             # API should be Api in PascalCase
def parse_JSON():           # JSON should be json
URL_PATH: str               # url should be url
```

### Exceptions for Well-Known Acronyms

Keep uppercase for these:

```python
HTTP, HTTPS, URL, API, JSON, XML, UUID, ID
```

## Anti-Patterns

### ❌ Generic Names

```python
# Bad
def process(): ...
def handle(): ...
def do_stuff(): ...
class Manager: ...
class Helper: ...
class Utils: ...
```

**Solution**: Be specific about what is being processed/handled.

```python
# Good
def process_response(): ...
def handle_rate_limit(): ...
def serialize_vector(): ...
class IndexManager: ...
class ResponseParser: ...
class VectorSerializer: ...
```

### ❌ Inconsistent Terminology

```python
# Bad: Using different words for same concept
def create_index(): ...
def make_embedding(): ...
def build_query(): ...
```

**Solution**: Pick one verb per concept.

```python
# Good: Consistent terminology
def create_index(): ...
def create_embedding(): ...
def create_query(): ...
```

### ❌ Abbreviations

```python
# Bad
idx, vec, meta, dim, cfg, req, resp, conn
```

**Solution**: Write full words.

```python
# Good
index, vector, metadata, dimension, config, request, response, connection
```

### ❌ Type Prefixes

```python
# Bad: Hungarian notation
str_name: str
int_count: int
list_items: list
```

**Solution**: Use type hints, not prefixes.

```python
# Good: Type hints instead
name: str
count: int
items: list
```

## Terminology Dictionary

Standard terms to use consistently:

| Concept | Use | Don't Use |
|---------|-----|-----------|
| Create | `create_index` | make, build, new |
| Delete | `delete_index` | remove, destroy |
| List | `list_indexes` | get_all, fetch_all |
| Retrieve | `get_index` | fetch, retrieve, read |
| Update | `update_index` | modify, change, edit |
| Vector | `vector` | vec, embedding (when referring to data) |
| Embedding | `embedding` | embed, vec (when referring to operation result) |
| Metadata | `metadata` | meta, data |
| Dimension | `dimension` | dim, dims |
| Configuration | `config` | configuration, settings, options |
| Namespace | `namespace` | ns, space |

## References

- See [architecture.md](./architecture.md) for module organization
- See [types.md](./types.md) for type hint naming patterns
- See [errors.md](./errors.md) for exception naming
- See [async.md](./async.md) for async/sync naming conventions
