PEP 8

Overview Designing a function header isn't just about making code work; it's about making code maintainable, readable, and predictable. The function header—comprising the name, arguments, and return type—serves as the primary contract between your code and its users. A poorly designed header creates a ripple effect of technical debt and "excruciating pain" for anyone trying to consume your API. By mastering the nuances of naming conventions, type hints, and argument grouping, you transform a simple script into a professional, scalable codebase. Prerequisites Before implementing these advanced patterns, you should have a solid grasp of: * **Python 3.10+** syntax (especially for newer pipe operators in types). * **Basic Type Hinting**: Familiarity with `list`, `dict`, and `int` annotations. * **Data Structures**: Understanding the difference between mutable (lists) and immutable (tuples) objects. Key Libraries & Tools * Python Typing Module: The standard library for providing runtime and static type checking information. * Data Classes: A decorator that automatically generates special methods for classes, ideal for grouping function options. * Operator Module: Used for advanced variable unpacking and item retrieval. Code Walkthrough: Designing Clean Headers Let's break down the transformation of a messy function into a clean, generic implementation. 1. Descriptive Naming and Type Annotations Avoid generic names like `calculate`. Use verbs for actions and nouns for arguments. Note how we use `snake_case` per PEP 8. ```python def calculate_total_price(item_prices: list[int], discount: int = 0) -> int: """Calculates total with a simple discount.""" return sum(item_prices) - discount ``` 2. The Dangers of Default Arguments A critical mistake is using mutable default arguments like `[]`. These are evaluated once at module load, not at execution. Instead, use `None` and initialize inside the function. ```python from typing import Optional def log_message(message: str, timestamp: Optional[float] = None) -> None: if timestamp is None: import time timestamp = time.time() print(f"[{timestamp}] {message}") ``` 3. Implementing Python Generics To make functions more flexible, use generics. This allows your function to accept various numeric types while ensuring type consistency. ```python from typing import TypeVar, Iterable T = TypeVar("T", int, float) def add_one(numbers: Iterable[T]) -> list[T]: # We accept any iterable but return a specific list return [n + 1 for n in numbers] ``` Syntax Notes: The Power of Specificity Python's type system follows a specific philosophy: **be liberal in what you accept and conservative in what you return**. For arguments, use generic types like `Iterable` or `Sequence`. This allows users to pass in lists, tuples, or even generators. However, for return types, be as specific as possible (e.g., return a `list` rather than an `Iterable`). This guarantees the caller can use list-specific features like indexing or `.append()` without the IDE complaining about type mismatches. Practical Examples: Grouping Arguments with TypeDict When a function exceeds four arguments, it becomes a "kitchen sink" and is hard to use. Grouping related parameters into an options object is a standard best practice. While Data Classes are popular, a `TypedDict` is often better for configurations where you don't want to force the caller to import a specific class. ```python from typing import TypedDict class QueryOptions(TypedDict, total=False): limit: int offset: int sort_by: str def get_users(query: str, options: QueryOptions) -> list[str]: limit = options.get("limit", 10) # Implementation logic here... return ["User1", "User2"] ``` Tips & Gotchas * **The Grammar Rule**: Avoid typos in function names. If you force a developer to type `is_order_paied`, you've already failed. Use a linter to catch these early. * **Vocabulary Consistency**: If you use the word "User" in one part of the app, don't use "Customer" or "Account" elsewhere for the same entity. * **Mutable Trap**: Never set a default argument to `datetime.now()` or `[]`. It will lead to stale data or shared lists between different function calls. * **Access Control**: Since Python lacks true `private` modifiers, use a single leading underscore (e.g., `_internal_logic`) to signal that a function is not meant for external use.