Python Naming Conventions

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

Quick Reference

| Element | Case | Pattern | Example | |---------|------|---------|---------| | Function | snake_case | <verb>_<noun> | fetch_user, validate_input | | Async function | snake_case | async_<verb>_<noun> | async_fetch_user | | Variable | snake_case | descriptive | user_count, is_valid | | Class | PascalCase | noun | SearchIndex, UserSession | | Constant | SCREAMING_SNAKE_CASE | + Final | MAX_RETRIES: Final = 3 | | Private | _snake_case | _ prefix | _cache, _validate | | Type alias | PascalCase | noun | JsonValue, Embedding |

Functions and Methods

Pattern: <verb>_<noun> in snake_case

Required Verb Prefixes

| Verb | When to use | Example | |------|-------------|---------| | get_ | Retrieve data already in memory or from local cache | get_user_by_id, get_config | | fetch_ | Retrieve from external source (API, database, file system) | fetch_api_data, fetch_remote_file | | create_ | Instantiate a new object | create_session, create_embedding | | build_ | Construct a complex object step-by-step | build_query, build_request | | parse_ | Convert raw data into structured format | parse_json, parse_response | | validate_ | Check correctness, return bool or raise | validate_input, validate_schema | | calculate_ | Compute and return a value | calculate_score, calculate_distance | | transform_ | Convert from one format to another | transform_coordinates, transform_response | | is_ | Return boolean for state check | is_valid, is_authenticated | | has_ | Return boolean for existence check | has_permission, has_feature |

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

| Variable type | Pattern | Examples | |---------------|---------|----------| | Counts | <noun>_count | user_count, retry_count | | Maximums | max_<noun> | max_retry_attempts, max_connections | | Minimums | min_<noun> | min_threshold, min_batch_size | | Boolean state | is_<adjective> | is_authenticated, is_valid | | Boolean existence | has_<noun> | has_permission, has_feature | | Dimensions/sizes | <noun>_dimensions or <noun>_size | embedding_dimensions, batch_size |

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