PEP 1: Purpose and Guidelines - The Foundation of Python Enhancement

# PEP stands for Python Enhancement Proposal
# Every major Python feature started as a PEP, including:

# PEP 289: Generator expressions (Python 2.4)
squares = (x**2 for x in range(10))

# PEP 343: The "with" statement (Python 2.5)
with open('file.txt', 'r') as f:
    content = f.read()

# PEP 498: Literal string interpolation (Python 3.6)
name = "Python"
version = 3.12
print(f"{name} {version} is awesome!")

# PEP 570: Positional-only parameters (Python 3.8)
def divide(a, b, /):  # a and b are positional-only
    return a / b

# PEP 604: Union operators (Python 3.10)
from typing import Union
# Old way: Union[int, str]
# New way: int | str
def process_value(value: int | str) -> str:
    return str(value)

# Standards Track PEPs propose new language features or libraries
# Examples include:

# PEP 484: Type Hints (Python 3.5)
def greeting(name: str) -> str:
    return f"Hello, {name}!"

# PEP 526: Variable Annotations (Python 3.6)
count: int = 0
names: list[str] = []

# PEP 585: Type Hinting Generics (Python 3.9)
# Can use built-in collections for type hints
def process_items(items: list[dict[str, int]]) -> None:
    for item in items:
        print(item)

# PEP 622: Structural Pattern Matching (Python 3.10)
def handle_response(response):
    match response:
        case {"status": "success", "data": data}:
            return data
        case {"status": "error", "message": msg}:
            raise Exception(msg)
        case _:
            raise ValueError("Invalid response format")

# Informational PEPs provide guidelines and information
# They don't propose changes but document best practices

# Example: Following PEP 8 (Style Guide) recommendations
class UserAccount:  # CamelCase for classes
    def __init__(self, user_name: str, email_address: str):  # snake_case for functions/variables
        self.user_name = user_name  # snake_case for attributes
        self.email_address = email_address
    
    def get_display_name(self) -> str:  # Method names in snake_case
        """Return formatted display name."""  # Docstring format from PEP 257
        return self.user_name.title()
    
    def validate_email(self) -> bool:
        """Validate email format following conventions."""
        import re
        pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
        return bool(re.match(pattern, self.email_address))

# PEP 20: The Zen of Python (import this)
import this  # Displays the Zen of Python principles

# Process PEPs describe processes around Python development
# They're like Standards Track but for processes, not code

# Example: Code organization following process guidelines
def main():
    """
    Main function following PEP guidelines for script structure.
    
    Process PEPs guide how we structure Python projects,
    handle governance, and manage the development process.
    """
    import sys
    import argparse
    
    # Argument parsing following best practices
    parser = argparse.ArgumentParser(
        description="Example script following PEP guidelines"
    )
    parser.add_argument("--verbose", "-v", action="store_true",
                       help="Enable verbose output")
    
    args = parser.parse_args()
    
    if args.verbose:
        print("Running in verbose mode")
    
    # Your application logic here
    print("Hello from a PEP-compliant script!")

if __name__ == "__main__":
    main()  # Standard Python script pattern

# Every PEP follows a standard format defined in PEP 1
# Here's what a typical PEP header looks like:

"""
PEP: 999
Title: Example PEP Title
Author: Author Name <author@example.com>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 15-Jun-2025
Python-Version: 3.13
"""

# PEP statuses follow a defined workflow:
pep_statuses = {
    "Draft": "Initial submission, work in progress",
    "Deferred": "Not being worked on currently",
    "Withdrawn": "Author has withdrawn the proposal",
    "Rejected": "Decided against by Python leadership",
    "Accepted": "Approved for implementation",
    "Final": "Implemented and released",
    "Superseded": "Replaced by another PEP"
}

def get_pep_status(pep_number: int) -> str:
    """
    Example function showing how you might check PEP status.
    In reality, you'd query the official PEP index.
    """
    # This is just an example - real implementation would
    # fetch from python.org/peps/
    example_statuses = {
        1: "Final",      # PEP 1 itself
        8: "Final",      # Style Guide
        20: "Final",     # Zen of Python
        484: "Final",    # Type Hints
        622: "Final",    # Pattern Matching
    }
    return example_statuses.get(pep_number, "Unknown")

# Steps to create a PEP (simplified example)
class PEPWorkflow:
    def __init__(self, title: str, author: str):
        self.title = title
        self.author = author
        self.status = "Draft"
        self.discussions = []
    
    def discuss_on_mailing_list(self, proposal_summary: str):
        """Step 1: Discuss idea on python-ideas mailing list"""
        self.discussions.append({
            "type": "mailing_list",
            "summary": proposal_summary,
            "feedback": "Community feedback collected"
        })
        print(f"Discussed '{self.title}' on python-ideas")
    
    def write_draft(self, specification: str):
        """Step 2: Write detailed PEP draft"""
        self.specification = specification
        print(f"Draft PEP written for '{self.title}'")
    
    def submit_for_review(self):
        """Step 3: Submit to PEP editors"""
        if self.status == "Draft":
            print(f"Submitted PEP '{self.title}' for editorial review")
            return True
        return False
    
    def address_feedback(self, feedback: list[str]):
        """Step 4: Address reviewer feedback"""
        for item in feedback:
            print(f"Addressing feedback: {item}")
        self.discussions.append({
            "type": "review_feedback",
            "items": feedback
        })
    
    def final_decision(self, decision: str):
        """Step 5: Final decision by Python steering council"""
        valid_decisions = ["Accepted", "Rejected", "Deferred"]
        if decision in valid_decisions:
            self.status = decision
            print(f"PEP '{self.title}' status: {decision}")
        
# Example usage
example_pep = PEPWorkflow("Better Error Messages", "Jane Developer")
example_pep.discuss_on_mailing_list("Improve traceback readability")
example_pep.write_draft("Detailed specification for enhanced error output")
example_pep.submit_for_review()

# How to effectively read and understand PEPs
def analyze_pep(pep_number: int):
    """
    Framework for analyzing any PEP systematically.
    """
    analysis = {
        "motivation": "Why is this needed?",
        "specification": "What exactly is proposed?",
        "rationale": "Why this approach vs alternatives?",
        "implementation": "How will it be built?",
        "impact": "What changes for users?",
        "timeline": "When will it be available?"
    }
    
    # Example: Analyzing PEP 622 (Pattern Matching)
    if pep_number == 622:
        return {
            "motivation": "Need for complex conditional logic",
            "specification": "match/case statements",
            "rationale": "More readable than if/elif chains",
            "implementation": "New AST nodes and bytecode",
            "impact": "New syntax available in Python 3.10+",
            "timeline": "Released October 2021"
        }
    
    return analysis

# Practical example: Using features from recent PEPs
def demonstrate_recent_peps():
    """Show features from recent PEPs in action."""
    
    # PEP 585: Built-in Generic Types (Python 3.9+)
    def process_users(users: list[dict[str, str | int]]) -> dict[str, int]:
        """Type hints using built-in collections."""
        return {user["name"]: user["age"] for user in users}
    
    # PEP 604: Union Operator (Python 3.10+)
    def handle_input(value: str | int | float) -> str:
        """Union types with | operator."""
        match value:  # PEP 622: Pattern Matching
            case str() if value.isdigit():
                return f"String number: {value}"
            case int() | float():
                return f"Numeric value: {value}"
            case str():
                return f"Text: {value}"
            case _:
                return "Unknown type"
    
    # PEP 673: Self Type (Python 3.11+)
    from typing import Self
    
    class Builder:
        def __init__(self):
            self.data = {}
        
        def add_field(self, key: str, value: str) -> Self:
            """Return Self type for method chaining."""
            self.data[key] = value
            return self
        
        def build(self) -> dict[str, str]:
            return self.data.copy()
    
    # Usage
    result = (Builder()
              .add_field("name", "Python")
              .add_field("version", "3.12")
              .build())
    
    return result

# Test the examples
users = [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]
processed = demonstrate_recent_peps()
print(f"Processed data: {processed}")

# PEPs have shaped every aspect of Python
import datetime
from pathlib import Path
from dataclasses import dataclass
from typing import Optional, Protocol

# PEP 557: Data Classes (Python 3.7)
@dataclass
class PEPExample:
    number: int
    title: str
    status: str
    created: datetime.date
    python_version: Optional[str] = None
    
    def is_final(self) -> bool:
        return self.status == "Final"
    
    def summary(self) -> str:
        return f"PEP {self.number}: {self.title} ({self.status})"

# PEP 544: Protocols (Python 3.8)
class Drawable(Protocol):
    def draw(self) -> str: ...

class Circle:
    def __init__(self, radius: float):
        self.radius = radius
    
    def draw(self) -> str:
        return f"Circle with radius {self.radius}"

def render_shape(shape: Drawable) -> str:
    """Function that accepts any object implementing Drawable protocol."""
    return shape.draw()

# PEP 309: Partial Function Application (Python 2.5)
from functools import partial

def log_message(level: str, message: str, timestamp: bool = True):
    """Log a message with specified level."""
    prefix = f"[{datetime.datetime.now()}] " if timestamp else ""
    print(f"{prefix}{level.upper()}: {message}")

# Create specialized logging functions
error_log = partial(log_message, "ERROR")
debug_log = partial(log_message, "DEBUG", timestamp=False)

# Usage
error_log("Something went wrong!")
debug_log("Debug information")

# PEP 3107: Function Annotations (Python 3.0)
# Later enhanced by PEP 484: Type Hints
def calculate_statistics(numbers: list[float]) -> dict[str, float]:
    """Calculate basic statistics for a list of numbers."""
    if not numbers:
        return {"count": 0, "mean": 0.0, "sum": 0.0}
    
    total = sum(numbers)
    count = len(numbers)
    mean = total / count
    
    return {
        "count": count,
        "sum": total,
        "mean": mean,
        "min": min(numbers),
        "max": max(numbers)
    }

# Examples of major PEPs in everyday Python
examples = [
    PEPExample(8, "Style Guide for Python Code", "Final", datetime.date(2001, 7, 5)),
    PEPExample(343, "The 'with' statement", "Final", datetime.date(2005, 5, 13), "2.5"),
    PEPExample(498, "Literal String Interpolation", "Final", datetime.date(2015, 8, 1), "3.6"),
    PEPExample(572, "Assignment Expressions", "Final", datetime.date(2018, 2, 28), "3.8"),
]

for pep in examples:
    print(pep.summary())

# Following PEP guidelines in your own code
from typing import Any, Callable, TypeVar

T = TypeVar('T')

class PEPCompliantClass:
    """
    Example class following PEP guidelines.
    
    This class demonstrates:
    - PEP 8: Style Guide compliance
    - PEP 257: Docstring conventions
    - PEP 484: Type hints
    - PEP 526: Variable annotations
    """
    
    # PEP 526: Variable annotations
    items: list[str]
    _private_data: dict[str, Any]
    
    def __init__(self, initial_items: list[str] | None = None) -> None:
        """
        Initialize the class with optional items.
        
        Args:
            initial_items: Optional list of initial items
        """
        self.items = initial_items or []
        self._private_data = {}
    
    def add_item(self, item: str) -> None:
        """Add an item to the collection."""
        if not isinstance(item, str):
            raise TypeError("Item must be a string")
        self.items.append(item)
    
    def get_items_by_filter(self, 
                           predicate: Callable[[str], bool]) -> list[str]:
        """
        Get items matching the predicate function.
        
        Args:
            predicate: Function that returns True for items to include
            
        Returns:
            List of items matching the predicate
        """
        return [item for item in self.items if predicate(item)]
    
    def transform_items(self, 
                       transformer: Callable[[str], T]) -> list[T]:
        """
        Transform all items using the provided function.
        
        Args:
            transformer: Function to transform each item
            
        Returns:
            List of transformed items
        """
        return [transformer(item) for item in self.items]
    
    def __str__(self) -> str:
        """String representation of the object."""
        return f"PEPCompliantClass({len(self.items)} items)"
    
    def __repr__(self) -> str:
        """Developer-friendly representation."""
        return f"PEPCompliantClass(items={self.items!r})"

# Usage following PEP patterns
def main() -> None:
    """Main function demonstrating PEP-compliant usage."""
    # Create instance
    collection = PEPCompliantClass(["apple", "banana", "cherry"])
    
    # Add items
    collection.add_item("date")
    collection.add_item("elderberry")
    
    # Filter items (PEP 202: List comprehensions influence)
    long_names = collection.get_items_by_filter(lambda x: len(x) > 5)
    print(f"Long names: {long_names}")
    
    # Transform items
    uppercase_items = collection.transform_items(str.upper)
    print(f"Uppercase: {uppercase_items}")
    
    # Use f-strings (PEP 498)
    print(f"Collection contains: {collection}")

if __name__ == "__main__":
    main()  # Standard Python pattern

# Useful tools and resources for PEP development
import urllib.request
import json
from pathlib import Path

def get_pep_info(pep_number: int) -> dict[str, str]:
    """
    Fetch PEP information (example implementation).
    
    In practice, you'd use the official PEP index at python.org
    """
    # This is a simplified example
    pep_database = {
        1: {"title": "PEP Purpose and Guidelines", "status": "Final"},
        8: {"title": "Style Guide for Python Code", "status": "Final"},
        20: {"title": "The Zen of Python", "status": "Final"},
        484: {"title": "Type Hints", "status": "Final"},
        622: {"title": "Structural Pattern Matching", "status": "Final"},
    }
    
    return pep_database.get(pep_number, {"title": "Unknown", "status": "Unknown"})

def list_peps_by_status(status: str) -> list[int]:
    """List PEPs with given status."""
    # Simplified example
    status_map = {
        "Final": [1, 8, 20, 343, 484, 498, 572, 622],
        "Draft": [999],  # Example draft
        "Rejected": [666],  # Example rejected
    }
    return status_map.get(status, [])

# PEP development tools you might use
class PEPTools:
    """Tools for working with PEPs."""
    
    @staticmethod
    def validate_pep_format(file_path: Path) -> list[str]:
        """Validate PEP file format."""
        issues = []
        
        try:
            content = file_path.read_text()
            lines = content.split('\n')
            
            # Check for required headers
            required_headers = ["PEP:", "Title:", "Author:", "Status:", "Type:"]
            
            for header in required_headers:
                if not any(line.startswith(header) for line in lines[:20]):
                    issues.append(f"Missing required header: {header}")
            
            # Check title format
            title_line = next((line for line in lines if line.startswith("Title:")), None)
            if title_line and len(title_line) > 79:
                issues.append("Title line too long (>79 characters)")
            
        except Exception as e:
            issues.append(f"Error reading file: {e}")
        
        return issues
    
    @staticmethod
    def generate_pep_template(pep_number: int, title: str, author: str) -> str:
        """Generate a PEP template."""
        template = f"""PEP: {pep_number}
Title: {title}
Author: {author}
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: {datetime.date.today().strftime('%d-%b-%Y')}
Python-Version: 3.13

Abstract
========

[Brief description of the proposal]

Motivation
==========

[Why is this change needed?]

Specification
=============

[Detailed technical specification]

Rationale
=========

[Why this approach? What alternatives were considered?]

Implementation
==============

[Implementation details, if available]

References
==========

[Links to related discussions, code, etc.]

Copyright
=========

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.
"""
        return template

# Example usage
def demonstrate_pep_tools():
    """Demonstrate PEP-related tools."""
    
    # Get information about important PEPs
    important_peps = [1, 8, 20, 484, 622]
    
    print("Important PEPs:")
    for pep_num in important_peps:
        info = get_pep_info(pep_num)
        print(f"  PEP {pep_num}: {info['title']} ({info['status']})")
    
    # List PEPs by status
    final_peps = list_peps_by_status("Final")
    print(f"\nFinal PEPs: {final_peps}")
    
    # Generate template for a hypothetical PEP
    template = PEPTools.generate_pep_template(
        999, 
        "Improved Error Messages", 
        "Python Developer <dev@python.org>"
    )
    print(f"\nPEP Template Preview:")
    print(template[:200] + "...")

if __name__ == "__main__":
    demonstrate_pep_tools()