Hide implementation details

Design public APIs to hide implementation details and focus on the user’s mental model of the system. Avoid exposing internal classes, implementation-specific parameters, or technical approaches that might change in the future.

Key principles:

• Use terminology that matches the user’s conceptual model, not internal implementation
• Avoid exposing implementation-specific parameters like parallel or internal classes
• Prefer extensible parameter designs (e.g., string literals) over booleans for features that might be expanded
• Use full descriptive names in public APIs instead of abbreviations

Example - Before:

def set_gpu_engine(cls, active: bool | None = None) -> type[Config]:
    """Set the default engine to use the GPU."""
    # ...

def filter(self, predicate: Expr, *, parallel: bool = False) -> Series:
    """Filter elements in each list by a boolean expression."""
    # ...

Example - After:

def set_default_engine(cls, engine: Literal["cpu", "gpu"]) -> type[Config]:
    """Set the default engine type."""
    # ...

def filter(self, predicate: Expr) -> Series:
    """Filter elements in each list by a boolean expression."""
    # ...

This approach creates more maintainable APIs, gives implementation flexibility, and provides a clearer mental model for users.