المُزخرفات

المُزخرفات — Decorators

المُزخرفات هي واحدة من أكثر أدوات Python قوةً وأناقةً. تجدها في كل مكتبة Python ناضجة — Flask يستخدمها لتعريف المسارات (@app.route), Django لصلاحيات المستخدم (@login_required), وdataclasses نفسها مُزخرف. فهمها يفتح لك باباً لكتابة كود أكثر نظافة وأقل تكراراً.

الدوال كقيم من الدرجة الأولى

قبل أن نتحدث عن المُزخرفات، يجب أن تفهم مبدأً أساسياً في Python: الدوال قيم مثل الأعداد والنصوص. يمكن تمريرها كمعاملات، تخزينها في متغيرات، وإرجاعها من دوال أخرى.

main.go

# الدوال قيم — Functions are values
def greet(name):
    return f"مرحباً، {name}!"

# تخزين الدالة في متغير — Store function in a variable
say_hello = greet
print(say_hello("أحمد"))  # يعمل تماماً — works perfectly

# تمرير دالة كمعامل — Pass function as argument
def call_twice(fn, arg):
    fn(arg)
    fn(arg)

def print_name(name):
    print(f"الاسم: {name}")

call_twice(print_name, "فاطمة")  # يطبع مرتين — prints twice

# دالة تُرجع دالة — Function returning a function
def make_multiplier(factor):
    def multiply(n):        # دالة داخلية — inner function
        return n * factor   # تستطيع الوصول لـ factor من الخارج
    return multiply         # نُرجع الدالة نفسها وليس نتيجتها

double = make_multiplier(2)
triple = make_multiplier(3)

print(double(5))   # 10
print(triple(5))   # 15

Output:

الدالة make_multiplier تُنشئ دالة جديدة في كل استدعاء وتُرجعها. هذه الدالة الداخلية تتذكر قيمة factor حتى بعد خروج make_multiplier — هذا يسمى Closure (إغلاق).

مُزخرف بسيط — Simple Decorator

المُزخرف في جوهره هو دالة تأخذ دالة وتُرجع دالة. تُضيف سلوكاً قبل أو بعد الدالة الأصلية دون تعديلها.

main.go

# مُزخرف بسيط — Simple decorator
def log_call(fn):
    # wrapper تُغلّف الدالة الأصلية — wrapper wraps the original
    def wrapper(*args, **kwargs):
        print(f"[LOG] استدعاء {fn.__name__}")   # قبل — before
        result = fn(*args, **kwargs)             # تنفيذ الدالة الأصلية
        print(f"[LOG] انتهى {fn.__name__}")      # بعد — after
        return result
    return wrapper  # نُرجع wrapper وليس نتيجة الاستدعاء

# الطريقة اليدوية — Manual application
def add(a, b):
    return a + b

add = log_call(add)  # هذا هو ما يفعله @ تحت الغطاء

result = add(3, 4)
print(f"الناتج: {result}")

Output:

*args و**kwargs تجعل wrapper مرنة — تقبل أي عدد من المعاملات وأي معاملات مسماة، وتُمررها للدالة الأصلية كما هي.

صياغة @ — The @ Syntax

Python توفر صياغة مختصرة باستخدام @ تجعل الكود أكثر وضوحاً. ما فعلناه يدوياً (add = log_call(add)) يعادل تماماً:

main.go

def log_call(fn):
    def wrapper(*args, **kwargs):
        print(f"[LOG] بدء تنفيذ: {fn.__name__}")  # before — قبل التنفيذ
        result = fn(*args, **kwargs)
        print(f"[LOG] انتهى التنفيذ: {fn.__name__}")  # after — بعد التنفيذ
        return result
    return wrapper


# @ تطبّق المُزخرف تلقائياً — @ applies the decorator automatically
@log_call
def greet(name):
    return f"مرحباً، {name}!"


@log_call
def multiply(a, b):
    return a * b


print(greet("عمر"))
print()
print(f"الحاصل: {multiply(6, 7)}")

Output:

@log_call قبل تعريف greet يعادل كتابة greet = log_call(greet) بعد التعريف. الصياغة بـ@ أكثر وضوحاً لأن المُزخرف يظهر مع تعريف الدالة مباشرةً.

مُزخرف مع معاملات — Decorator Factory

أحياناً تريد مُزخرفاً قابلاً للإعداد — مثل @retry(times=3) أو @cache(ttl=60). هنا تحتاج decorator factory: دالة تُنتج مُزخرفاً.

main.go

# decorator factory — مصنع مُزخرفات
def repeat(times):
    # هذا هو المُزخرف الفعلي — This is the actual decorator
    def decorator(fn):
        def wrapper(*args, **kwargs):
            for i in range(times):
                result = fn(*args, **kwargs)  # نُنفّذ times مرات — execute times times
            return result
        return wrapper
    return decorator  # نُرجع المُزخرف وليس wrapper


@repeat(times=3)
def say(message):
    print(message)


@repeat(times=2)
def greet(name):
    print(f"أهلاً {name}!")


say("مرحبا!")
print("---")
greet("سارة")

Output:

لاحظ الطبقات الثلاث:

repeat(times) — تأخذ الإعداد وتُرجع مُزخرفاً
decorator(fn) — المُزخرف الفعلي، يأخذ الدالة ويُرجع wrapper
wrapper(*args, **kwargs) — الدالة المُعدَّلة الفعلية

@repeat(times=3) يعادل: أولاً يستدعي repeat(3) للحصول على مُزخرف، ثم يُطبّق ذلك المُزخرف على say.

`functools.wraps` — حفظ البيانات الوصفية

مشكلة صامتة تحدث مع المُزخرفات: wrapper تحلّ محل الدالة الأصلية، فتضيع اسمها ووثائقها.

main.go

import functools


def log_call(fn):
    def wrapper(*args, **kwargs):
        print(f"[LOG] {fn.__name__}")
        return fn(*args, **kwargs)
    return wrapper


def log_call_fixed(fn):
    @functools.wraps(fn)  # يحفظ __name__ و__doc__ وغيرها — preserves metadata
    def wrapper(*args, **kwargs):
        print(f"[LOG] {fn.__name__}")
        return fn(*args, **kwargs)
    return wrapper


@log_call
def add(a, b):
    """تجمع رقمين — Adds two numbers."""
    return a + b


@log_call_fixed
def subtract(a, b):
    """تطرح رقمين — Subtracts two numbers."""
    return a - b


# بدون wraps — without wraps
print(f"الاسم: {add.__name__}")   # wrapper! ليس add
print(f"الوثيقة: {add.__doc__}")  # None!

print()

# مع wraps — with wraps
print(f"الاسم: {subtract.__name__}")   # subtract — صحيح
print(f"الوثيقة: {subtract.__doc__}")  # الوثيقة الأصلية — correct

Output:

functools.wraps ضروري في أي مُزخرف تكتبه. بدونه يفشل help() ويتعطّل inspect، وتختفي وثائقك.

مُزخرفات متعددة — Stacking Decorators

يمكن تطبيق أكثر من مُزخرف على دالة واحدة. تُطبَّق من الأقرب للدالة إلى الأبعد (من الأسفل للأعلى):

main.go

import functools


def bold(fn):
    @functools.wraps(fn)
    def wrapper(*args, **kwargs):
        result = fn(*args, **kwargs)
        return f"**{result}**"  # إضافة تنسيق عريض — add bold formatting
    return wrapper


def uppercase(fn):
    @functools.wraps(fn)
    def wrapper(*args, **kwargs):
        result = fn(*args, **kwargs)
        return result.upper()  # تحويل لحروف كبيرة — convert to uppercase
    return wrapper


# bold يُطبَّق على uppercase(greet) — bold applied to uppercase(greet)
@bold
@uppercase
def greet(name):
    return f"hello {name}"


# الترتيب: greet → uppercase → bold
print(greet("world"))   # **HELLO WORLD**

Output:

مُزخرف عملي — Timing Decorator

main.go

import functools
import time


def timer(fn):
    """يقيس وقت تنفيذ الدالة — Measures function execution time."""
    @functools.wraps(fn)
    def wrapper(*args, **kwargs):
        start = time.time()           # ابدأ المؤقت — start timer
        result = fn(*args, **kwargs)  # نفّذ الدالة — execute function
        elapsed = time.time() - start  # احسب الوقت — calculate time
        print(f"[TIMER] {fn.__name__} أخذت {elapsed:.4f}s")
        return result
    return wrapper


@timer
def slow_sum(n):
    """يحسب مجموع 1 إلى n — Computes sum from 1 to n."""
    total = 0
    for i in range(n):
        total += i
    return total


@timer
def fast_sum(n):
    """يحسب المجموع بالصيغة المغلقة — Computes sum with closed formula."""
    return n * (n - 1) // 2


result1 = slow_sum(1_000_000)
result2 = fast_sum(1_000_000)

print(f"slow_sum: {result1}")
print(f"fast_sum: {result2}")
print(f"متطابقان: {result1 == result2}")

Output:

متى تستخدم المُزخرفات؟

المُزخرفات مناسبة عندما يكون لديك سلوك متكرر ينطبق على دوال متعددة، ومستقل عن منطقها الرئيسي. أمثلة شائعة:

Logging — تسجيل كل استدعاء ومعاملاته
Timing — قياس الأداء
Caching — حفظ النتائج لتجنب إعادة الحساب (functools.lru_cache)
Auth — التحقق من صلاحية المستخدم قبل تنفيذ الدالة
Retry — إعادة المحاولة عند الفشل (ما ستبنيه في الدرس الأخير)

تحدي — Challenge

import functools


def simple_cache(fn):
    """مُزخرف caching بسيط — Simple caching decorator."""
    cache = {}  # قاموس لتخزين النتائج — dict to store results

    @functools.wraps(fn)
    def wrapper(*args):
        if args in cache:
            print(f"[CACHE] hit: {fn.__name__}({args[0]})")
            return cache[args]
        print(f"[CACHE] miss: {fn.__name__}({args[0]})")
        result = fn(*args)
        cache[args] = result  # خزّن النتيجة — store result
        return result

    return wrapper


@simple_cache
def fib(n):
    # أكمل الكود — Complete the code
    if n <= 1:
        return n
    return fib(n - 1) + fib(n - 2)


print(f"fib(5) = {fib(5)}")

المُزخرفات