# Example of clean, well-structured code
class UserManager:
    """Manages user data and operations."""
    
    def __init__(self):
        self.users = {}
    
    def create_user(self, username: str, email: str) -> bool:
        """Create a new user with validation."""
        if not self._is_valid_email(email):
            raise ValueError(f"Invalid email format: {email}")
        
        if username in self.users:
            return False
        
        self.users[username] = {
            'email': email,
            'created_at': self._get_current_timestamp()
        }
        return True
    
    def _is_valid_email(self, email: str) -> bool:
        """Private method to validate email format."""
        return '@' in email and '.' in email.split('@')[1]
    
    def _get_current_timestamp(self) -> str:
        """Get current timestamp in ISO format."""
        from datetime import datetime
        return datetime.now().isoformat()

# Usage with clear, descriptive code
manager = UserManager()
success = manager.create_user("alice123", "alice@example.com")
print(f"User created: {success}")

"""
Example module demonstrating Python best practices.
Shows proper structure, naming, and documentation.
"""

from typing import List, Dict, Optional
from dataclasses import dataclass
from datetime import datetime


@dataclass
class Product:
    """Represents a product with basic information."""
    name: str
    price: float
    category: str
    in_stock: bool = True


class ShoppingCart:
    """Manages items in a shopping cart."""
    
    def __init__(self):
        self._items: List[Product] = []
    
    def add_item(self, product: Product) -> bool:
        """Add a product to the cart if it's in stock."""
        if not product.in_stock:
            return False
        
        self._items.append(product)
        return True
    
    def get_total(self) -> float:
        """Calculate total price of items in cart."""
        return sum(item.price for item in self._items)
    
    def get_items_by_category(self, category: str) -> List[Product]:
        """Get all items in cart from a specific category."""
        return [item for item in self._items if item.category == category]
    
    @property
    def item_count(self) -> int:
        """Number of items in the cart."""
        return len(self._items)


def create_sample_products() -> List[Product]:
    """Create sample products for demonstration."""
    return [
        Product("Laptop", 999.99, "Electronics"),
        Product("Coffee Mug", 12.99, "Kitchen"),
        Product("Python Book", 39.99, "Books", in_stock=False)
    ]


# Usage example with clear, professional code
def main():
    """Main function demonstrating the shopping cart."""
    cart = ShoppingCart()
    products = create_sample_products()
    
    # Add available products to cart
    for product in products:
        if cart.add_item(product):
            print(f"Added {product.name} to cart")
        else:
            print(f"{product.name} is out of stock")
    
    # Display cart summary
    print(f"\nCart summary:")
    print(f"Items: {cart.item_count}")
    print(f"Total: ${cart.get_total():.2f}")
    
    # Show electronics items
    electronics = cart.get_items_by_category("Electronics")
    print(f"Electronics items: {len(electronics)}")


if __name__ == "__main__":
    main()