Naming Conventions

Python Naming Conventions

Apply these naming patterns when writing Python code in this repository.

Quick Reference

Functions and Methods

Pattern: <verb>_<noun> in snake_case

Required Verb Prefixes

Async Functions

Required: Prefix all async functions with async_

# CORRECT
async def async_fetch_user(user_id: int) -> User:
    return await client.get(f"/users/{user_id}")

async def async_process_batch(items: list[Item]) -> list[Result]:
    return await asyncio.gather(*[async_process(item) for item in items])

# INCORRECT - missing async_ prefix
async def fetch_user(user_id: int) -> User:  # Bad: not clear await is needed
    ...

Variables

Pattern: snake_case with descriptive names

Required Patterns

Forbidden Variable Names

Never use these generic names:

• data, info, temp, tmp, val, value
• flag, result, response (without qualifier)
• Single letters except in comprehensions: [x for x in items]

# CORRECT
user_count = len(users)
max_retry_attempts = 3
embedding_dimensions = 768
is_authenticated = True
has_valid_license = check_license(user)

# INCORRECT
data = len(users)      # Too generic
n = 3                  # Single letter

Classes

Pattern: PascalCase noun describing what it represents

# CORRECT
class SearchIndex: ...
class EmbeddingModel: ...
class RetryPolicy: ...
class ValidationError: ...

# INCORRECT
class Search: ...          # Verb-like, unclear purpose
class EmbModel: ...        # Abbreviation
class DoValidation: ...    # Verb phrase

Constants

Pattern: SCREAMING_SNAKE_CASE with Final type annotation

from typing import Final

# CORRECT
MAX_RETRY_ATTEMPTS: Final = 3
DEFAULT_TIMEOUT_SECONDS: Final[float] = 30.0
SUPPORTED_FILE_FORMATS: Final[frozenset[str]] = frozenset({"json", "csv", "parquet"})

# INCORRECT
MaxRetries = 3              # Wrong case, missing Final
max_retry_attempts = 3      # Wrong case for constant
MAX_RETRY_ATTEMPTS = 3      # Missing Final annotation

Private Members

Pattern: Single underscore _ prefix for internal implementation

class SearchService:
    def __init__(self, index: VectorIndex) -> None:
        self._index = index              # Private attribute
        self._cache: dict[str, Result] = {}  # Private attribute

    def search(self, query: str) -> list[Result]:  # Public API
        return self._perform_search(query)

    def _perform_search(self, query: str) -> list[Result]:  # Private method
        ...

Type Aliases

Pattern: PascalCase describing the type

# CORRECT
JsonValue = dict[str, Any] | list[Any] | str | int | float | bool | None
Embedding = list[float]
UserId = int

# INCORRECT
json_value = dict[str, Any] | list[Any] | str | int | float | bool | None  # Wrong case