decorator — ফাংশনকে না বদলে মোড়ানো

১ · মূল ভাবনা — কাজের চারপাশে একটি মোড়ক

ধরুন আপনি একটি মোবাইল wallet অ্যাপের ব্যাকএন্ড লিখছেন। একটি ফাংশন আছে pay(sender, receiver, amount) — এক জনের কাছ থেকে আরেক জনের কাছে টাকা পাঠায়। এখন তিনটি নতুন দাবি এল: (ক) প্রতিটি লেনদেনের লগ রাখতে হবে, (খ) গুনতে হবে দিনে কতবার ফাংশনটি ডাকা হলো, (গ) শুধু লগইন করা ব্যবহারকারীই টাকা পাঠাতে পারবেন। আর একই তিনটি দাবি আছে আরও বিশটি ফাংশনের জন্য — withdraw, recharge, pay_bill…

সহজ পথ হলো প্রতিটি ফাংশনের শুরুতে আর শেষে একই পাঁচ-ছয় লাইন কপি করে বসানো। কিন্তু তাতে তিনটি সমস্যা: প্রতিটি ফাংশনের আসল কাজ (টাকা পাঠানো) চাপা পড়ে যায় পাহারাদারি কোডের নিচে; লগের ধরন বদলাতে হলে বিশ জায়গায় বদলাতে হয়; আর একটি জায়গায় ভুলে গেলে সেই ফাংশনটি পাহারা ছাড়াই চলে।

এই ধরনের কাজকে বলে cross-cutting concern — যে কাজ কোনো একটি ফাংশনের নিজস্ব নয়, বরং অনেক ফাংশনের ভেতর দিয়ে আড়াআড়ি চলে যায়: লগ, সময় মাপা, অনুমতি যাচাই, cache, retry. Python-এর উত্তর হলো decorator: একটি ফাংশন, যা আরেকটি ফাংশন নিয়ে তার চারপাশে নতুন আচরণ মুড়ে দেয়, আর মূল ফাংশনের কোড একটুও বদলায় না.

ভিত্তি: ফাংশনও একটি object

Decorator সম্ভব হয় পর্ব ১৩ আর ২০-এর একটি তথ্যের জন্য: Python-এ ফাংশন একটি first-class function — সাধারণ মানের মতোই একটি object. def pay(...) চললে Python একটি function object বানায় আর pay নামটি তার গায়ে লাগায়। তাই ফাংশন দিয়ে তিনটি কাজ করা যায়, যেগুলো decorator-এর তিনটি খুঁটি:

• অন্য নামে রাখা: send = pay — এখন send(...) আর pay(...) একই ফাংশন ডাকে। বন্ধনী ছাড়া pay মানে ফাংশন object নিজে, pay() মানে তাকে ডাকা।
• argument হিসেবে পাঠানো: sorted(students, key=by_gpa)-এ আপনি by_gpa ফাংশনটিকেই পাঠাচ্ছেন। যে ফাংশন অন্য ফাংশন নেয় বা ফেরত দেয়, তাকে বলে higher-order function.
• ফাংশন থেকে ফাংশন ফেরত দেওয়া: পর্ব ২০-এর factory function — make_vat(0.15) একটি নতুন ফাংশন বানিয়ে ফেরত দিয়েছিল, যা closure হিসেবে হারটি মনে রাখত।

পর্ব ২০-এ আরেকটি হাতিয়ারও দেখেছিলেন: wrapper function, যা *args আর **kwargs দিয়ে যা আসে সব নিয়ে নেয়, নিজের কিছু কাজ করে, তারপর হুবহু আরেকটি ফাংশনে পাঠিয়ে দেয়। Decorator হলো এই তিনটি জিনিসের মিলন: একটি higher-order function, যা ফাংশন নেয়, ভেতরে একটি wrapper closure বানায়, আর সেই wrapper ফেরত দেয়. নতুন কোনো ভাষা-বৈশিষ্ট্য নেই — শুধু @ চিহ্নটি ছাড়া, আর সেটিও নিছক একটি সংক্ষেপ।

২ · নিজের হাতে প্রথম decorator — আর @ চিহ্নের আসল মানে

প্রথমে @ ছাড়া, পুরো হাতে-কলমে। লক্ষ্য: যেকোনো ফাংশন ডাকার আগে তার নাম আর argument ছাপা, আর পরে ফলাফল ছাপা।

def log(func):                        # func = যে ফাংশন মোড়াব
    def wrapper(*args, **kwargs):     # নতুন ফাংশন: যেকোনো argument নেয়
        print("→", func.__name__, args)
        result = func(*args, **kwargs)  # আসল কাজ — হুবহু ফরোয়ার্ড
        print("←", result)
        return result                 # আসল ফল ফেরত দিতে ভুলবেন না
    return wrapper                    # ডাকা নয় — ফাংশনটিই ফেরত

def pay(to, amount):
    return amount + 5                 # ৫ টাকা চার্জসহ মোট

pay = log(pay)                        # মোড়ানো ফাংশন দিয়ে নাম বদল
total = pay("করিম", 500)

তিনটি জিনিস খেয়াল করুন। এক, log নিজে কিছু ছাপে না; সে শুধু একটি নতুন ফাংশন (wrapper) বানিয়ে ফেরত দেয়। দুই, wrapper একটি closure — সে বাইরের func-কে মনে রাখে, তাই পরে ডাকলেও জানে কোন আসল ফাংশন চালাতে হবে। তিন, শেষের pay = log(pay) লাইনটি: ডান দিকে পুরোনো pay (আসল ফাংশন) ঢুকছে, আর বাঁ দিকে pay নামটি লাগছে wrapper-এর গায়ে। আসল ফাংশন হারিয়ে যায়নি — সে এখন wrapper-এর closure-এ func নামে বসে আছে।

@ — একই কথা, সুন্দর করে

pay = log(pay) লেখার দুটি অসুবিধা আছে: ফাংশনের নাম তিনবার লিখতে হয়, আর লাইনটি থাকে ফাংশনের শেষে — বড় ফাংশন হলে পড়ার সময় চোখেই পড়ে না যে এটি মোড়ানো। তাই Python 2.4 (২০০৪) থেকে একটি সংক্ষিপ্ত লেখা এসেছে:

@log
def pay(to, amount):
    return amount + 5

# উপরের তিন লাইন = def pay(...) ... তারপর pay = log(pay)

এ ধরনের লেখাকে বলে syntactic sugar — যে লেখা নতুন কোনো ক্ষমতা দেয় না, শুধু একই জিনিস লেখা সহজ করে। (একটি সূক্ষ্ম পার্থক্য আছে: @ দিলে আসল ফাংশনটি কখনো pay নামে বসেই না; সরাসরি decorator-এর ফল নামটি পায়।) এবার ধাপে ধাপে দেখুন, এই কয়েক লাইনের পেছনে আসলে কী কী ঘটে। “পরে” চাপুন:

1def log(func):2    def wrapper(*args, **kwargs):3        print("→", func.__name__, args)4        result = func(*args, **kwargs)5        print("←", result)6        return result7    return wrapper89@log10def pay(to, amount):11    return amount + 51213total = pay("করিম", 500)

Decorator চলে একবারই — def-এর সময়

স্টেপারের ধাপ ৩ থেকে একটি গুরুত্বপূর্ণ কথা বেরিয়ে আসে: decorator ফাংশনটি (log) চলে ফাংশন সংজ্ঞায়িত হওয়ার মুহূর্তে, একবারই — সাধারণত module import হওয়ার সময়। প্রতিটি ডাকে চলে শুধু wrapper. তাই log-এর ভেতরে (wrapper-এর বাইরে) একটি print রাখলে সেটি ফাইল চালানোর সাথে সাথেই একবার ছাপা হবে, ফাংশন কেউ না ডাকলেও।

এই “একবার, সংজ্ঞার সময়” আচরণটি নিজেই কাজে লাগে। অনেক decorator wrapper বানায়ই না — শুধু ফাংশনটিকে কোথাও নিবন্ধন করে, তারপর আসল ফাংশনই ফেরত দেয়। যেমন একটি bot-এর command তালিকা:

COMMANDS = {}

def command(func):
    COMMANDS[func.__name__] = func    # def-এর সময় একবার: তালিকায় তোলা
    return func                       # মোড়ানো নয় — আসল ফাংশনই ফেরত

@command
def balance(user): ...

@command
def recharge(user, amount): ...

# এখন COMMANDS = {'balance': ..., 'recharge': ...}

এই ধাঁচকে বলে registry pattern. পর্ব ৪৮-এ দেখবেন, FastAPI-র @app.get("/") আর Flask-এর @app.route("/") মূলত এই কাজটিই করে: “এই URL-এ অনুরোধ এলে এই ফাংশনটি ডাকবে” — নিবন্ধন হয়ে যায় import-এর সময়েই।

৩ · functools.wraps — হারিয়ে যাওয়া নাম ফিরিয়ে আনা

আমাদের প্রথম log-এ একটি লুকানো সমস্যা আছে। মোড়ানোর পরে pay নামটি wrapper-কে দেখায় — তাহলে ফাংশনটির পরিচয়ও তো এখন wrapper-এর! দেখুন:

@log                       # wraps ছাড়া লেখা log
def pay(to, amount):
    """এক wallet থেকে আরেকটিতে টাকা পাঠায়।"""
    return amount + 5

print(pay.__name__)        # wrapper     ← pay নয়!
print(pay.__doc__)         # None        ← docstring হারিয়ে গেছে
help(pay)                  # wrapper(*args, **kwargs) — আসল parameter-ও নেই

এটা শুধু দেখতে খারাপ নয়, বাস্তবে ক্ষতিও করে:

• ডিবাগ কঠিন: traceback আর লগে বিশটি আলাদা ফাংশনের সবার নাম আসে wrapper — কোনটিতে সমস্যা, বোঝা যায় না।
• ডকুমেন্টেশন হারায়: docstring চলে যায়, তাই help(), editor-এর tooltip আর স্বয়ংক্রিয় ডকুমেন্টেশন টুল কিছুই দেখায় না।
• যে টুল নাম দেখে কাজ করে, সে ভেঙে যায়: উপরের COMMANDS[func.__name__] ধরনের registry-তে সবাই 'wrapper' নামে বসে একে অপরকে মুছে দেয়। pytest বা ওয়েব framework-ও অনেক সময় ফাংশনের নাম ব্যবহার করে।

সমাধান স্ট্যান্ডার্ড লাইব্রেরিতেই আছে: functools.wraps. মজার ব্যাপার, এটি নিজেই একটি decorator — wrapper-এর ওপরে বসে আসল ফাংশনের পরিচয় (__name__, __qualname__, __doc__, __module__, annotation ইত্যাদি) wrapper-এ কপি করে দেয়। সঙ্গে wrapper-এ একটি __wrapped__ attribute বসায়, যা আসল ফাংশনকে দেখায় — দরকার হলে মোড়ক খুলে সরাসরি আসলটি ডাকা যায়, আর inspect.signature, help() এর সাহায্যে আসল parameter দেখাতে পারে।

import functools

def log(func):
    @functools.wraps(func)            # শুধু এই একটি লাইন যোগ
    def wrapper(*args, **kwargs):
        ...
    return wrapper

লক্ষ করুন, wraps শুধু পরিচয়ের লেবেল কপি করে; wrapper এখনো আলাদা একটি ফাংশন। pay is pay.__wrapped__ হবে False. পরিচয় মিলল, অস্তিত্ব নয়।

এবার প্রথম runnable প্রোগ্রাম: wraps-সহ লগ decorator, যা সঙ্গে গুনেও রাখে ফাংশনটি কতবার ডাকা হলো। ফাংশনও object, তাই তার গায়ে নিজের attribute (wrapper.calls) লাগানো যায় — global ভ্যারিয়েবল লাগে না। চালানোর আগে শেষ দুই লাইনের আউটপুট অনুমান করুন:

import functools

def log(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        wrapper.calls += 1
        print(f"→ {func.__name__}{args}")
        result = func(*args, **kwargs)
        print(f"← {result}")
        return result
    wrapper.calls = 0
    return wrapper

@log
def pay(sender, receiver, amount):
    """এক wallet থেকে আরেকটিতে টাকা পাঠায়।"""
    return amount + 5

pay("রহিম", "করিম", 500)
pay("সুমি", "জামাল", 200)
print(pay.calls, pay.__name__, pay.__doc__)
print(pay.__wrapped__("রহিম", "করিম", 100))

৪ · Argument-সহ decorator — তিন স্তরের বাক্স

এখন পর্যন্ত decorator-এর কোনো সেটিং ছিল না। কিন্তু বাস্তবে প্রায়ই দরকার হয়: “নেটওয়ার্ক ডাক ব্যর্থ হলে ৩ বার চেষ্টা করো”, বা “এই ফাংশন শুধু admin ডাকতে পারবে”. লিখতে চাই এভাবে:

@retry(times=3)
def fetch_rate(currency): ...

@require_role("admin")
def delete_account(user, account_id): ...

এখানে একটি নিয়ম মনে রাখলে সব পরিষ্কার: @-এর পরে যা লেখা, Python আগে সেই expression-টি হিসাব করে, আর তার ফলকে decorator হিসেবে ব্যবহার করে. @log-এ expression হলো শুধু log — একটি ফাংশন। কিন্তু @retry(times=3)-এ expression হলো একটি ডাক: retry(times=3). তাই retry নিজে decorator নয়; retry(3) যা ফেরত দেয়, সেটি decorator. যে ফাংশন decorator বানিয়ে ফেরত দেয়, তাকে বলে decorator factory.

ফলে নেস্টিং হয় তিন স্তরের। নামগুলো মনে রাখার একটি সহজ উপায় — প্রতিটি স্তর একটি জিনিস নেয়:

• বাইরের স্তর — retry(times): সেটিং নেয়। ফেরত দেয় decorator.
• মাঝের স্তর — decorator(func): ফাংশন নেয়। ফেরত দেয় wrapper. (এটিই আমাদের আগের log-এর মতো সাধারণ decorator.)
• ভেতরের স্তর — wrapper(*args, **kwargs): প্রতিটি ডাকের argument নেয়। ফেরত দেয় আসল ফল।

অর্থাৎ @retry(times=3) লেখা মানে fetch_rate = retry(times=3)(fetch_rate) — দুই জোড়া বন্ধনী পরপর: প্রথম জোড়া সেটিং দিয়ে decorator আনে, দ্বিতীয় জোড়া সেই decorator-কে ফাংশন দেয়। ধাপে ধাপে দেখুন:

dec = retry(times=3)      # retry-র body চলে
                          # ভেতরে def decorator
                          # ফেরত: decorator (times মনে রাখে)

dec = retry(times=3)
w = dec(fetch_rate)       # decorator-এর body চলে
                          # ভেতরে def wrapper
                          # ফেরত: wrapper

fetch_rate = retry(times=3)(fetch_rate)
# wrapper-এর closure-এ দুটি cell:
#   times = 3   (বাইরের স্তর থেকে)
#   func  = আসল fetch_rate

fetch_rate("USD")         # আসলে wrapper("USD")
চেষ্টা 1: USD: timeout    # ধরা হলো, আবার
চেষ্টা 2: USD: timeout    # ধরা হলো, আবার

USD রেট: 121.5
# তিনবারই ব্যর্থ হলে: শেষে ConnectionError
# ওপরে পাঠানো হয় — চুপচাপ None নয়

দ্বিতীয় runnable প্রোগ্রামে ঠিক এটিই চলছে। নেটওয়ার্ক তো আর এখানে ব্যবহার করা যায় না, আর আসল নেটওয়ার্কের ব্যর্থতা এলোমেলো — তাই একটি iterator দিয়ে “সার্ভারের উত্তর” আগে থেকে ঠিক করে রাখা হয়েছে: প্রথম দুবার চুপ (None), তৃতীয়বার রেট। এভাবে নকল করে বানানো ব্যর্থতা প্রতিবার একই ফল দেয়, তাই পরীক্ষা করা সহজ — টেস্টিংয়েও এই কৌশল চলে (পর্ব ৩৯)।

import functools

def retry(times):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except ConnectionError as err:
                    print(f"চেষ্টা {attempt}: {err}")
            raise ConnectionError(f"{times} বার চেষ্টাতেও ব্যর্থ")
        return wrapper
    return decorator

replies = iter([None, None, 121.5])     # None মানে সার্ভার চুপ
@retry(times=3)
def fetch_rate(currency):
    if (rate := next(replies)) is None:
        raise ConnectionError(f"{currency}: timeout")
    return rate
print("USD রেট:", fetch_rate("USD"), fetch_rate.__name__)

আরেকটি factory: @require_role("admin")

একই তিন-স্তরের ছাঁচে অনুমতি যাচাই। ধরা যাক প্রতিটি সংবেদনশীল ফাংশনের প্রথম argument হলো বর্তমান ব্যবহারকারী, একটি dict:

import functools

def require_role(role):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(user, *args, **kwargs):
            if role not in user.get("roles", ()):
                raise PermissionError(f"{func.__name__}: '{role}' অনুমতি লাগবে")
            return func(user, *args, **kwargs)
        return wrapper
    return decorator

@require_role("admin")
def delete_account(user, account_id):
    ...

এখানে wrapper প্রথম argument user-কে নাম ধরে আলাদা করে নিয়েছে, যাতে পরীক্ষা করা যায়; বাকিগুলো আগের মতোই *args, **kwargs-এ। অনুমতি না থাকলে আসল ফাংশন চলেই না — decorator শুধু আগে-পরে কাজ জুড়তে পারে তা নয়, পুরো ডাকটি আটকেও দিতে পারে। @require_login-ও একই রকম, শুধু শর্তটি হবে “ব্যবহারকারী লগইন করেছেন কি না”. ভাবুন, পঞ্চাশটি admin ফাংশনে এই যাচাই হাতে লিখলে একটিতে ভুলে যাওয়ার সম্ভাবনা কত — decorator থাকলে প্রতিটি ফাংশনের ঠিক ওপরে চোখের সামনেই লেখা থাকে কে ডাকতে পারবে।

৫ · একাধিক decorator একসাথে — কে আগে, কে পরে

একটি ফাংশনের ওপরে কয়েকটি decorator সাজিয়ে লেখা যায় — একে বলে decorator stacking:

@require_login
@log
def pay(user, receiver, amount): ...

# মানে: pay = require_login(log(pay))

নিয়ম দুটি, আর দুটি আপাতদৃষ্টিতে উল্টো:

• মোড়ানো হয় নিচ থেকে ওপরে: ফাংশনের সবচেয়ে কাছের (নিচের) decorator আগে লাগে, তারপর তার ফলকে ওপরেরটি মোড়ায় — যেমন উপহার আগে রঙিন কাগজে মোড়ানো হয়, তারপর সেটি একটি বাক্সে।
• ডাকার সময় চলে ওপর থেকে নিচে: নামটি এখন সবচেয়ে বাইরের (ওপরের) wrapper-কে দেখায়, তাই ডাক এলে প্রথমে সেটিই চলে, তারপর ভেতরেরটি, শেষে আসল ফাংশন। উপহার খোলার সময় আগে বাক্স, তারপর কাগজ।

সহজ একটি উদাহরণে দেখুন — একটি decorator ফলাফলের দুই পাশে তারা বসায়, আরেকটি বসায় বন্ধনী:

1def stars(func):2    def wrapper():3        return "*" + func() + "*"4    return wrapper5def brackets(func):6    def wrapper():7        return "[" + func() + "]"8    return wrapper9@stars10@brackets11def greet():12    return "হ্যালো"13print(greet())

তারা আর বন্ধনীতে ক্রম শুধু চেহারা বদলায়, কিন্তু বাস্তবে ক্রম ভুল হলে নিরাপত্তা আর হিসাব দুটোই ভাঙে:

• @require_login ওপরে, @log নিচে: লগইন যাচাই আগে হয়; অননুমোদিত ডাক লগে পৌঁছায়ই না। উল্টো ক্রমে প্রতিটি চেষ্টা (অননুমোদিতও) আগে লগ হয়, তারপর আটকায় — যদি আপনি সন্দেহজনক চেষ্টাও রেকর্ড করতে চান, সেটাই ঠিক। কোনটি চাই, তা আগে ঠিক করুন।
• সময় মাপা আর cache: @timer ওপরে আর @cache নিচে থাকলে timer মাপে cache-সহ সময় (দ্বিতীয় ডাকে প্রায় শূন্য)। উল্টো ক্রমে cache থাকে timer-এর বাইরে, তাই cache থেকে উত্তর এলে timer চলেই না।
• Built-in decorator-এর ক্ষেত্রে: @classmethod বা @staticmethod-এর সাথে অন্য decorator মেশালে সাধারণত @classmethod সবার ওপরে রাখতে হয়, কারণ সে ফাংশনকে একটি বিশেষ object-এ বদলে দেয়, যা অন্য decorator সাধারণ ফাংশন ভেবে মোড়াতে পারে না।

৬ · কাজের decorator — লগ, সময়, যাচাই আর cache

এ পর্যন্ত লগ, গণনা, retry আর অনুমতি দেখলেন। বাস্তবের আরও কয়েকটি পরিচিত decorator, আর শেষে স্ট্যান্ডার্ড লাইব্রেরির সবচেয়ে কাজের একটি।

সময় মাপা — @timer

কোন ফাংশন ধীর, তা জানতে প্রতিটি ডাকের সময় মাপা। পর্ব ২৭-এর time.perf_counter() এর জন্য সঠিক ঘড়ি — দুটি মানের পার্থক্যই সময়:

import functools, time

def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        try:
            return func(*args, **kwargs)
        finally:                       # error হলেও সময় ছাপা হবে
            ms = (time.perf_counter() - start) * 1000
            print(f"{func.__name__}: {ms:.1f} ms")
    return wrapper

এখানে try/finally-এর ব্যবহারটি লক্ষ করুন (পর্ব ২৪): আসল ফাংশন exception দিলেও সময় ছাপা হয়, আর exception নিজে চুপচাপ হারায় না, ওপরে চলে যায়। finally-এর আগেই return থাকলেও finally চলে, তারপর ফল ফেরত যায়। বড় প্রোগ্রামে print-এর বদলে logging module ব্যবহার করুন (পর্ব ৪০)।

ইনপুট যাচাই — @validate_positive

টাকার পরিমাণ শূন্য বা ঋণাত্মক হলে কোনো লেনদেন চলবে না — এই নিয়ম বিশটি ফাংশনে একই। একটি decorator wrapper-এর শুরুতে amount পরীক্ষা করে ValueError দিতে পারে, আসল ফাংশন ডাকার আগেই। একে বলে input validation. তবে সাবধান: যাচাইয়ের নিয়ম যত জটিল হয়, decorator-এ লুকিয়ে রাখা তত কম পরিষ্কার। ফাংশনটি পড়ে কেউ যেন বুঝতে পারেন কী কী শর্ত আছে — জটিল নিয়ম ফাংশনের ভেতরেই বা আলাদা যাচাই-ফাংশনে রাখা ভালো, অথবা pydantic-এর মতো লাইব্রেরি।

আগের উত্তর মনে রাখা — functools.lru_cache আর cache

কিছু ফাংশন একই ইনপুটে সবসময় একই উত্তর দেয় আর হিসাবে অনেক সময় নেয় — যেমন একটি জটিল ফর্মুলায় মুদ্রার রূপান্তর হার, বা পরিচিত উদাহরণ Fibonacci. একই প্রশ্নের উত্তর বারবার হিসাব না করে প্রথমবারের উত্তর লিখে রাখা আর পরে খাতা দেখে বলে দেওয়া — এই কৌশলের নাম memoization. ইনপুট → উত্তরের যে খাতা, তাকে বলে cache.

নিজে dict দিয়ে লেখা যায়, কিন্তু Python-এ তৈরি decorator আছে: functools.lru_cache (Python 3.2 থেকে) আর তার সহজ রূপ functools.cache (Python 3.9 থেকে)। Recursion-এর ক্ষেত্রে এর প্রভাব নাটকীয়, কারণ ফাংশনের ভেতরের নিজেকে-ডাকাও আসলে নাম ধরে ডাকা — আর নামটি এখন cache-ওয়ালা wrapper-কে দেখায়। ধাপে ধাপে fib(10)-এ মোট কতটি ডাক হয় দেখুন:

1@functools.cache        # ধাপ ১–৩-এ এই লাইন নেই2def fib(n):3    if n < 2:4        return n5    return fib(n - 1) + fib(n - 2)67print(fib(10), fib.cache_info())

cache_info()-এর চারটি সংখ্যার মানে: hits = কতবার খাতা থেকে উত্তর দেওয়া গেছে, misses = কতবার আসল হিসাব করতে হয়েছে, maxsize = খাতায় সর্বোচ্চ কতটি উত্তর রাখা যাবে (None মানে সীমা নেই), currsize = এখন কতটি আছে। খাতা খালি করতে fib.cache_clear().

cache আর lru_cache-এর পার্থক্য খাতার আকারে। @functools.cache সব উত্তর চিরকাল রাখে — ছোট ইনপুট-জগতের জন্য ঠিক, কিন্তু লাখো আলাদা ইনপুট এলে মেমরি শুধু বাড়তেই থাকে। @functools.lru_cache(maxsize=128) সর্বোচ্চ ১২৮টি রাখে; জায়গা ফুরালে সবচেয়ে দীর্ঘ সময় ব্যবহার না হওয়া উত্তরটি ফেলে দেয় — LRU মানে “Least Recently Used”. maxsize না দিলে default ১২৮।

৭ · method, class আর আপনার ইতিমধ্যে দেখা decorator

Method-কে decorate করা — self চলে যায় *args-এ

Class-এর method-ও আসলে class-এর ভেতরে লেখা একটি সাধারণ ফাংশন, যার প্রথম parameter self (পর্ব ২৯)। তাই আমাদের @log method-এর ওপরেও কোনো বদল ছাড়াই কাজ করে: wallet.pay("করিম", 500) ডাকলে wrapper পায় args = (wallet, "করিম", 500) — self হলো args-এর প্রথম উপাদান, আর হুবহু আসল method-এ চলে যায়। এজন্যই wrapper-এ *args, **kwargs এত গুরুত্বপূর্ণ: সে জানে না, জানার দরকারও নেই, ফাংশনটি সাধারণ ফাংশন নাকি method. শুধু একটি জিনিস খেয়াল রাখবেন — লগে self ছাপলে object-এর __repr__ (পর্ব ৩০) দেখাবে, যেখানে ব্যবহারকারীর গোপন তথ্য থাকলে সেটি লগে চলে যেতে পারে।

Class decorator — পুরো class-কে মোড়ানো

@ শুধু ফাংশনের ওপরে নয়, class-এর ওপরেও বসে। তখন decorator একটি class নেয়, আর (সাধারণত সেই একই class, কিছু যোগ করে) ফেরত দেয়: @register class Plugin: ... মানে Plugin = register(Plugin). একে বলে class decorator. আপনি ইতিমধ্যে সবচেয়ে বিখ্যাতটি দেখেছেন — পর্ব ৩২-এর @dataclass. সে class-এর ফিল্ডগুলো পড়ে নিজে থেকে __init__, __repr__, __eq__ লিখে class-এ বসিয়ে দেয়, তারপর একই class ফেরত দেয় — কোনো wrapper নেই। Class decorator এসেছে Python 2.6 আর 3.0-তে।

যে decorator-গুলো আপনি আগেই ব্যবহার করেছেন

মডিউল ৫-এ বেশ কয়েকবার @ দেখেছেন, হয়তো ভেবেছেন এটি class-এর কোনো বিশেষ নিয়ম। এখন জানেন — সবই সাধারণ decorator, সবই নাম = decorator(নাম):

@property, @classmethod, @staticmethod wrapper ফাংশন ফেরত দেয় না; ফেরত দেয় বিশেষ ধরনের object (descriptor, পর্ব ৩২-এর ঝলক), যা attribute পড়ার সময় আচরণ বদলায়। নিয়ম তবু একটাই — decorator যা ফেরত দেয়, নামটি সেটাই পায়। সেটি ফাংশন, class, descriptor বা যা খুশি হতে পারে।

Framework-এ decorator — সামনে যা দেখবেন

বড় Python লাইব্রেরিগুলো decorator-কে তাদের “ভাষা” বানিয়েছে। পর্ব ৪৮-এ FastAPI-তে লিখবেন @app.get("/balance") — এটি একটি decorator factory, যা ফাংশনটিকে একটি URL-এর সাথে নিবন্ধন করে (অংশ ২-এর registry). পর্ব ৩৯-এ pytest-এ দেখবেন @pytest.fixture (পরীক্ষার আগে ডেটা প্রস্তুত করা ফাংশন চিহ্নিত করা) আর @pytest.mark.parametrize(...) (একই টেস্ট অনেক ইনপুটে চালানো)। এমনকি AI লাইব্রেরিতেও আছে — PyTorch-এর @torch.no_grad(). এখন এগুলো দেখলে আর জাদু মনে হবে না: প্রতিটি একটি ফাংশন, যা আপনার ফাংশন নিয়ে কিছু করে।

৮ · কখন decorator ক্ষতি করে — সরল রাখার নিয়ম

Decorator শক্তিশালী, আর ঠিক এই কারণেই অপব্যবহার সহজ। ক্ষতির জায়গাগুলো চিনে রাখুন:

• লুকানো জাদু: def pay(...) পড়ে মনে হয় এটি শুধু টাকা পাঠায়। কিন্তু ওপরের পাঁচটি decorator হয়তো ডাকটি আটকায়, argument বদলায়, ফল বদলায় বা ডাকটি তিনবার চালায়। আচরণ জানতে হলে প্রতিটি decorator-এর কোড খুলে পড়তে হয়। যে decorator ফাংশনের অর্থ বদলে দেয় (যেমন argument-এর type চুপচাপ বদলে দেওয়া), সেটি সবচেয়ে বিপজ্জনক।
• লম্বা traceback আর কঠিন ডিবাগ: error হলে traceback-এ প্রতিটি wrapper-এর একটি করে স্তর যোগ হয়। ডিবাগারে step করলে আপনি আসল ফাংশনের আগে কয়েকটি wrapper-এর ভেতর দিয়ে যান। wraps নাম ঠিক রাখে, কিন্তু স্তরগুলো থেকেই যায়।
• Exception গিলে ফেলা: wrapper-এর ভেতরে except Exception: return None লিখলে আসল ফাংশনের সব error অদৃশ্য — পর্ব ২৪-এর swallowing exceptions. টাকা পাঠানো ব্যর্থ হলো, অথচ কেউ জানল না।
• পরীক্ষা কঠিন: @require_login-ওয়ালা ফাংশন unit test-এ ডাকতে হলে আগে নকল লগইন সাজাতে হয়। wraps-এর দেওয়া __wrapped__ দিয়ে আসল ফাংশন আলাদাভাবে পরীক্ষা করা যায় — আরেকটি কারণ wraps ভুলবেন না।
• অতিরিক্ত কৌশল: একটি ফাংশনে মাত্র একবার দরকার এমন কাজের জন্য decorator লেখা, বা চার স্তরের factory যা কেউ পড়ে বুঝতে পারে না। Decorator-এর লাভ আসে তখনই, যখন একই কাজ অনেক ফাংশনে লাগে।

৯ · AI-এর যুগে — AI-এর লেখা decorator যাচাই করা

“একটি logging decorator লিখে দাও” — AI কয়েক সেকেন্ডে লিখে দেয়, আর সেটি চলেও। সমস্যা হলো, decorator-এর ভুলগুলো প্রথম পরীক্ষায় ধরা পড়ে না। নাম হারানো, error গিলে ফেলা বা ফল হারিয়ে যাওয়া দেখা দেয় পরে, অন্য কোনো ফাংশনে, অন্য কোনো টুলে। AI-এর লেখা decorator-এ বারবার যে ভুলগুলো দেখা যায়:

AI-এর লেখা decorator পেলে — যাচাইয়ের চেকলিস্ট

• প্রতিটি wrapper-এর ঠিক ওপরে @functools.wraps(func) আছে; মোড়ানো ফাংশনের __name__ ছাপিয়ে মিলিয়েছি
• wrapper আসল ফাংশনের ফল return করছে — একটি মান ফেরত দেয় এমন ফাংশন মুড়ে ফল ছাপিয়ে দেখেছি, None আসেনি
• wrapper-এ except থাকলে সেটি নির্দিষ্ট exception ধরে, আর হয় আবার raise করে, নয়তো স্পষ্ট কারণসহ সামলায়
• wrapper *args, **kwargs নেয়; একটি method আর keyword argument-ওয়ালা একটি ফাংশনে লাগিয়ে পরীক্ষা করেছি
• factory হলে @নাম(...) বন্ধনীসহ ব্যবহার হয়েছে; সাধারণ decorator হলে বন্ধনী ছাড়া
• stack-এর ক্রম যাচাই করেছি — অনুমতি যাচাই কি লগের আগে, নাকি পরে চাই — আর retry বা cache শুধু নিরাপদ জায়গায়