Mastering Python's Typing Extensions: A Guide to NewType, TypeVar, and Generic Constraints

            def process_order(user_id: int, order_id: int) -> None:
    print(f"Processing order {order_id} for user {user_id}...")

# A simple, but potentially disastrous, mistake
user_identification = 101
order_identification = 4512
process_order(order_identification, user_identification) # Whoops!
# Output: Processing order 101 for user 4512...
            

              
                Copy
              
            
          

            from typing import NewType

# Define distinct types for User IDs and Order IDs
UserId = NewType('UserId', int)
OrderId = NewType('OrderId', int)

def process_order(user_id: UserId, order_id: OrderId) -> None:
    print(f"Processing order {order_id} for user {user_id}...")

user_identification = UserId(101)
order_identification = OrderId(4512)

# Correct usage - works perfectly
process_order(user_identification, order_identification)

# Incorrect usage - now caught by a static type checker!
# Mypy will raise an error like:
# error: Argument 1 to "process_order" has incompatible type "OrderId"; expected "UserId"
# error: Argument 2 to "process_order" has incompatible type "UserId"; expected "OrderId"
process_order(order_identification, user_identification)

            

              
                Copy
              
            
          

            from typing import TypeAlias

# This is just an alias. A type checker sees UserIdAlias as exactly the same as int.
UserIdAlias: TypeAlias = int

def process_user(user_id: UserIdAlias) -> None:
    ...

# No error here, because UserIdAlias is just an int
process_user(123)
process_user(OrderId(999)) # OrderId is also an int at runtime
            

              
                Copy
              
            
          

            from typing import Any, List

def get_first_element_any(items: List[Any]) -> Any:
    if items:
        return items[0]
    return None

numbers = [1, 2, 3]
first_num = get_first_element_any(numbers)
# What is the type of 'first_num'? The type checker only knows 'Any'.
# This means we lose autocompletion and type safety.
# (first_num.imag) # No static error, but a runtime AttributeError!

            

              
                Copy
              
            
          

            from typing import TypeVar, List, Optional

# Create a TypeVar. The string 'T' is a convention.
T = TypeVar('T')

def get_first_element(items: List[T]) -> Optional[T]:
    if items:
        return items[0]
    return None

# --- Usage Examples ---

# Example 1: List of integers
numbers = [10, 20, 30]
first_num = get_first_element(numbers)
# Mypy correctly infers that 'first_num' is of type 'Optional[int]'

# Example 2: List of strings
names = ["Alice", "Bob", "Charlie"]
first_name = get_first_element(names)
# Mypy correctly infers that 'first_name' is of type 'Optional[str]'

# Now, the type checker can help us!
if first_num is not None:
    print(first_num + 5) # OK, it's an int!

if first_name is not None:
    print(first_name.upper()) # OK, it's a str!
            

              
                Copy
              
            
          

            from typing import TypeVar, Generic, List

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: List[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

    def is_empty(self) -> bool:
        return not self._items

# Create a stack specifically for integers
int_stack = Stack[int]()
int_stack.push(10)
int_stack.push(20)
value = int_stack.pop() # 'value' is correctly inferred as 'int'
# int_stack.push("hello") # Mypy error: Expected 'int', got 'str'

# Create a stack specifically for strings
str_stack = Stack[str]()
str_stack.push("hello")
# str_stack.push(123) # Mypy error: Expected 'str', got 'int'
            

              
                Copy
              
            
          

            from typing import TypeVar

# This version causes a type error!
T = TypeVar('T')
def find_larger(a: T, b: T) -> T:
    # Mypy error: Unsupported operand types for > ("T" and "T")
    return a if a > b else b

            

              
                Copy
              
            
          

            from typing import TypeVar

# Create a bounded TypeVar
Number = TypeVar('Number', bound=float)

def find_larger(a: Number, b: Number) -> Number:
    # This is now type-safe! The checker knows 'Number' supports '>'
    return a if a > b else b

find_larger(10, 20)       # OK, T is int
find_larger(3.14, 1.618) # OK, T is float
# find_larger("a", "b")      # Mypy error: Type 'str' is not a subtype of 'float'
            

              
                Copy
              
            
          

            from typing import TypeVar

# Create a TypeVar constrained to 'str' and 'bytes'
StrOrBytes = TypeVar('StrOrBytes', str, bytes)

def get_hash(data: StrOrBytes) -> int:
    # Both str and bytes have an __hash__ method, so this is safe.
    return hash(data)

get_hash("hello world") # OK, StrOrBytes is str
get_hash(b"hello world") # OK, StrOrBytes is bytes
# get_hash(123)           # Mypy error: Value of type variable "StrOrBytes" of "get_hash" 
#                         # cannot be "int"
            

              
                Copy
              
            
          

            import dataclasses
from typing import TypeVar, List, Set, Hashable, NewType

# 1. Use NewType for semantic clarity
ProductId = NewType('ProductId', int)

# 2. Define a data structure
@dataclasses.dataclass
class Product:
    id: ProductId
    name: str
    category: str

# 3. Use a bounded TypeVar. The attribute we extract must be hashable
#    to be put into a set for uniqueness.
HashableValue = TypeVar('HashableValue', bound=Hashable)

def get_unique_attributes(items: List[Product], attribute_name: str) -> Set[HashableValue]:
    """Extracts a unique set of attribute values from a list of products."""
    unique_values: Set[HashableValue] = set()
    for item in items:
        value = getattr(item, attribute_name)
        # A static checker can't verify 'value' is HashableValue here without
        # more complex plugins, but the bound documents our intent and helps consumers.
        unique_values.add(value)
    return unique_values

# --- Usage ---

products = [
    Product(id=ProductId(1), name="Laptop", category="Electronics"),
    Product(id=ProductId(2), name="Mouse", category="Electronics"),
    Product(id=ProductId(3), name="Desk Chair", category="Furniture"),
]

# Get unique categories. The type checker knows the return is Set[str]
unique_categories: Set[str] = get_unique_attributes(products, 'category')
print(f"Unique Categories: {unique_categories}")

# Get unique product IDs. The return is Set[ProductId]
unique_ids: Set[ProductId] = get_unique_attributes(products, 'id')
print(f"Unique IDs: {unique_ids}")

            

              
                Copy