شرح مصممو بايثون: الدليل الكامل لعام 2026

@my_decorator
def greet(name):
    return f"Hello, {name}!"

greet = my_decorator(greet)

def log_calls(func):
    """Decorator that logs function entry and exit."""
    def wrapper(*args, **kwargs):
        print(f"→ Calling {func.__name__} with args={args}, kwargs={kwargs}")
        result = func(*args, **kwargs)
        print(f"← {func.__name__} returned {result!r}")
        return result
    return wrapper

@log_calls
def add(a, b):
    return a + b

add(3, 4)
# Output:
# → Calling add with args=(3, 4), kwargs={}
# ← add returned 7

import functools

def log_calls(func):
    @functools.wraps(func)   # ← copies __name__, __doc__, __module__, etc.
    def wrapper(*args, **kwargs):
        print(f"→ Calling {func.__name__}")
        result = func(*args, **kwargs)
        print(f"← {func.__name__} returned {result!r}")
        return result
    return wrapper

@log_calls
def add(a, b):
    """Add two numbers."""
    return a + b

print(add.__name__)   # 'add'  ✅
print(add.__doc__)    # 'Add two numbers.'  ✅

import functools, time

def retry(times=3, delay=1.0, exceptions=(Exception,)):
    """Retry a function up to `times` times on specified exceptions."""
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            last_err = None
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions as e:
                    last_err = e
                    print(f"   Attempt {attempt}/{times} failed: {e}")
                    if attempt < times:
                        time.sleep(delay)
            raise last_err
        return wrapper
    return decorator

@retry(times=3, delay=0.5, exceptions=(ConnectionError,))
def fetch_data(url):
    # simulate a flaky network call
    raise ConnectionError("timeout")

try:
    fetch_data("https://api.example.com/data")
except ConnectionError:
    print("All retries exhausted.")

import functools, time

def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.4f}s")
        return result
    return wrapper

def log_calls(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

@timer          # applied second (outer)
@log_calls      # applied first (inner)
def process(n):
    return sum(range(n))

process(1_000_000)
# Output:
# Calling process
# process took 0.0312s

import functools

class CallCounter:
    """Counts how many times a function is called."""
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"{self.func.__name__} called {self.count} time(s)")
        return self.func(*args, **kwargs)

@CallCounter
def say_hello(name):
    print(f"Hello, {name}!")

say_hello("Alice")   # called 1 time(s)
say_hello("Bob")     # called 2 time(s)
print(say_hello.count)  # 2

class Temperature:
    _kelvin_offset = 273.15

    def __init__(self, celsius):
        self._celsius = celsius

    @property
    def fahrenheit(self):
        """Computed attribute — no () needed when accessing."""
        return self._celsius * 9/5 + 32

    @fahrenheit.setter
    def fahrenheit(self, value):
        self._celsius = (value - 32) * 5/9

    @classmethod
    def from_kelvin(cls, kelvin):
        """Factory method — creates instance from Kelvin."""
        return cls(kelvin - cls._kelvin_offset)

    @staticmethod
    def is_valid_celsius(value):
        """Utility — no access to instance or class."""
        return value >= -273.15

t = Temperature(100)
print(t.fahrenheit)                      # 212.0  (property)
t.fahrenheit = 32                        # setter
t2 = Temperature.from_kelvin(373.15)    # classmethod
print(Temperature.is_valid_celsius(-300))  # False (staticmethod)

from functools import lru_cache

@lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(50))  # Instant — cached results
print(fibonacci.cache_info())  # CacheInfo(hits=48, misses=51, ...)

import functools

def require_auth(func):
    """Decorator for protected routes."""
    @functools.wraps(func)
    def wrapper(request, *args, **kwargs):
        token = request.headers.get("Authorization", "")
        if not token.startswith("Bearer "):
            return {"error": "Unauthorized"}, 401
        return func(request, *args, **kwargs)
    return wrapper

@require_auth
def get_user_profile(request):
    return {"user": "Alice", "email": "alice@example.com"}

import functools, time
from collections import defaultdict, deque

def rate_limit(calls=10, period=60):
    """Allow at most `calls` per `period` seconds per caller."""
    history = defaultdict(deque)
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            key = args[0] if args else "default"  # use first arg as caller ID
            q = history[key]
            while q and now - q[0] > period:
                q.popleft()
            if len(q) >= calls:
                raise RuntimeError(f"Rate limit exceeded: {calls} calls per {period}s")
            q.append(now)
            return func(*args, **kwargs)
        return wrapper
    return decorator

@rate_limit(calls=5, period=60)
def send_email(user_id, message):
    print(f"Email sent to {user_id}: {message}")

# ❌ Wrong — returns None
def broken(func):
    def wrapper(*args, **kwargs):
        func(*args, **kwargs)   # no return!
    return wrapper

# ✅ Correct
def fixed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)  # always return
    return wrapper