Decorators ב-Python: @functions, ארגומנטים ו-functools.wraps

decorator הוא פונקציה שעוטפת פונקציה

המשפט הזה נשמע מופשט, אבל המנגנון פשוט. decorator מקבל פונקציה ומחזיר פונקציה. הפונקציה שהוא מחזיר בדרך כלל קוראת למקורית, עם התנהגות נוספת שעוטפת את הקריאה.

הדוגמה הקצרה ביותר שאפשר:

def shout(func):
    def wrapper():
        result = func()
        return result.upper()
    return wrapper

def greet():
    return "hello"

greet = shout(greet)
print(greet())

shout הוא ה-decorator. הוא מקבל פונקציה (greet), בונה פונקציה חדשה (wrapper) שקוראת למקורית והופכת את התוצאה לאותיות גדולות, ומחזיר אותה. ההצבה מחדש greet = shout(greet) מחליפה את המקורית בגרסה העטופה.

דפוס ההצבה מחדש הזה נפוץ כל כך ש-Python נתנה לו תחביר ייעודי.

ה-@ הוא קיצור להצבה מחדש

@name בשורה שמעל def שקול ל-name = name(...) מיד אחרי הגדרת הפונקציה:

def shout(func):
    def wrapper():
        return func().upper()
    return wrapper

@shout
def greet():
    return "hello"

print(greet())

@shout נקרא "הפעילו את ה-decorator shout על הפונקציה הזו". Python מריצה greet = shout(greet) מיד אחרי ה-def: אותו מנגנון כמו קודם, פחות הקלדה.

בכל פעם שרואים @name, החליפו אותו בראש ב-function = name(function). זו כל המשמעות של התחביר.

טיפול בארגומנטים

רוב הפונקציות מקבלות ארגומנטים. decorator שימושי מעביר אותם הלאה. הביטוי המקובל הוא *args, **kwargs, הדרך של Python לקבל כל ארגומנט שהוא, כי לפונקציה העוטפת לא אמור להיות אכפת למה הפונקציה העטופה מצפה:

def shout(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return result.upper()
    return wrapper

@shout
def greet(name, punctuation="!"):
    return f"hello, {name}{punctuation}"

print(greet("rosa"))
print(greet("boris", punctuation="."))

*args תופס את כל הארגומנטים הפוזיציונליים. **kwargs תופס את כל הארגומנטים בעלי השם. הפונקציה העוטפת מעבירה הכל לפונקציה העטופה בלי שינוי, ואז עושה את העבודה הנוספת שה-decorator נועד לה: כאן, הפיכת התוצאה לאותיות גדולות.

זו הצורה שרוב ה-decorators האמיתיים לובשים.

דוגמה שימושית יותר: מדידת זמן

הדפסה של כמה זמן לוקחת פונקציה:

import time

def timed(func):
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed*1000:.2f} ms")
        return result
    return wrapper

@timed
def slow_sum(n):
    total = 0
    for i in range(n):
        total += i
    return total

print(slow_sum(1_000_000))
print(slow_sum(5_000_000))

הדפוס, להריץ משהו לפני הקריאה ומשהו אחריה, הוא מה שרוב ה-decorators עושים בסוף. לוגים, בדיקות הרשאה, ניסיונות חוזרים ואימות קלט פועלים כולם באותה צורה.

שמירה על הזהות המקורית: functools.wraps

עיטור של פונקציה מחליף אותה, ולכן הפונקציה העטופה מאבדת את התכונות המקוריות __name__ ו-__doc__ שלה:

def shout(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs).upper()
    return wrapper

@shout
def greet(name):
    """Return a personalised greeting."""
    return f"hello, {name}"

print(greet.__name__)
print(greet.__doc__)

greet.__name__ הוא עכשיו "wrapper", וה-docstring נעלם. זה שובר את help(), את ה-tracebacks, וכל כלי שבודק את הפונקציה.

התיקון הוא שורה אחת: @functools.wraps(func) על הפונקציה הפנימית מעתיק את המטא-דאטה.

from functools import wraps

def shout(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs).upper()
    return wrapper

@shout
def greet(name):
    """Return a personalised greeting."""
    return f"hello, {name}"

print(greet.__name__)
print(greet.__doc__)

הוסיפו תמיד @wraps(func) לפונקציה הפנימית. זה לא עולה כלום וחוסך סשנים מפתיעים של דיבוג בהמשך.

Decorators עם ארגומנטים

לפעמים ה-decorator עצמו צריך הגדרות: "לנסות את הפונקציה הזו עד 3 פעמים", "לרשום לוג ברמת DEBUG". זה אומר עוד שכבת קינון אחת: פונקציה חיצונית שמקבלת את הארגומנטים ומחזירה decorator.

from functools import wraps

def repeat(times):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(times=3)
def say_hi(name):
    print(f"Hi, {name}")

say_hi("Rosa")

שלוש שכבות נשמע הרבה. קראו מבחוץ פנימה:

1. repeat(times=3) היא קריאה לפונקציה. היא מחזירה את decorator.
2. decorator הוא ה-decorator האמיתי: הוא מקבל פונקציה ומחזיר פונקציה עטופה.
3. wrapper היא הפונקציה העטופה שרצה בזמן הקריאה.

הצורה הזו מפעילה את @retry(times=5), @cache(maxsize=100), ו-decorators של פריימוורקים כמו @app.route("/users"). ברגע שמזהים את דפוס שלוש השכבות, כל המשפחה נקראת באותה דרך.

שרשור decorators

אפשר להפעיל יותר מ-decorator אחד על פונקציה. הם נערמים מלמטה למעלה: זה שהכי קרוב ל-def רץ ראשון:

from functools import wraps

def add_exclaim(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs) + "!"
    return wrapper

def shout(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs).upper()
    return wrapper

@shout
@add_exclaim
def greet(name):
    return f"hi, {name}"

print(greet("rosa"))

add_exclaim עוטף ראשון ומוסיף את ה-!. אחר כך shout עוטף את זה והופך הכל לאותיות גדולות. הפלט הוא HI, ROSA!.

הסדר חשוב. היפוך הערימה נותן HI, ROSA! כשסימן הקריאה מתווסף אחרי ההמרה לאותיות גדולות. כאן זה נראה זהה, אבל דמיינו decorator שמעצב JSON: הרצה שלו לפני או אחרי decorator שרושם את הקלט ללוג יכולה לתת תוצאות שונות מאוד.

Decorators מובנים שתראו

Python והספרייה הסטנדרטית שלה מגיעות עם כמה decorators שתפגשו בקוד אמיתי:

from functools import lru_cache

class Circle:
    def __init__(self, radius):
        self.radius = radius

    @property
    def area(self):
        return 3.14159 * self.radius ** 2

    @staticmethod
    def unit_circle_area():
        return 3.14159

    @classmethod
    def from_diameter(cls, diameter):
        return cls(diameter / 2)

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

c = Circle(5)
print(c.area)
print(Circle.unit_circle_area())
print(Circle.from_diameter(10).radius)
print(fib(50))

• @property הופך מתודה לתכונה מחושבת.
• @staticmethod מסמן מתודה שלא משתמשת ב-self או ב-cls.
• @classmethod מקבל את המחלקה בתור cls במקום מופע: מצוין לבנאים חלופיים.
• @functools.lru_cache שומר תוצאות בזיכרון (memoization), כך שקריאות חוזרות עם אותם ארגומנטים מגיעות למטמון.

decorators של פריימוורקים (@app.route, @pytest.fixture, @dataclass) עובדים באותו מנגנון. שום דבר מיוחד: רק פונקציות שעוטפות פונקציות.

מתי לכתוב אחד, ומתי לא

כתבו decorator כשאתם רוצים להחיל את אותה התנהגות על פונקציות רבות: מדידת זמן, לוגים, ניסיונות חוזרים, בדיקות הרשאה. כל העניין הוא שההתנהגות נשארת מחוץ לגוף הפונקציה.

וותרו על decorator כש:

• ההתנהגות שייכת לפונקציה ספציפית אחת. שימו אותה בפונקציה.
• אתם צריכים אותו רק לבדיקות. fixture או פרמטר ברורים יותר.
• יש לכם פיתוי לשרשר ארבעה או חמישה. בשלב הזה, זרימת הבקרה מוסתרת בשרשרת ה-decorators: קורא צריך לפרק כל שכבה כדי לראות מה באמת רץ. פונקציית עזר פשוטה יכולה להיות קריאה יותר.

decorators הם כלי חד. בשימוש נכון, הם שומרים על הקוד DRY ועל הכוונה ברורה. בשימוש גרוע, הם מסתירים מה התוכנית עושה. כשאתם מתלבטים אם להשתמש באחד, העדיפו את מה שברור.

הבא בתור: Type Hints

decorators הם מקום נפוץ לפגוש type hints בשטח: פונקציות ה-wrapper מוסיפות הרבה פעמים הערות טיפוס לחתימות שלהן. type hints הם פיצ'ר קטן שמשתלם מהר, והם מגיעים בהמשך.