پروتکل توصیف‌گر پایتون: تسلط بر کنترل دسترسی به خصوصیت‌ها و اعتبارسنجی داده‌ها

پروتکل توصیف‌گر (Descriptor Protocol) پایتون یک ویژگی قدرتمند اما اغلب کم‌استفاده است که امکان کنترل دقیق بر دسترسی و تغییر صفات (attributes) در کلاس‌های شما را فراهم می‌کند. این پروتکل راهی برای پیاده‌سازی اعتبارسنجی پیچیده داده‌ها و مدیریت خصوصیت‌ها ارائه می‌دهد که منجر به کدی تمیزتر، قوی‌تر و قابل نگهداری‌تر می‌شود. این راهنمای جامع به بررسی جزئیات پروتکل توصیف‌گر، مفاهیم اصلی، کاربردهای عملی و بهترین شیوه‌های آن می‌پردازد.

درک توصیف‌گرها (Descriptors)

در هسته خود، پروتکل توصیف‌گر نحوه مدیریت دسترسی به صفات را زمانی تعریف می‌کند که یک صفت، نوع خاصی از شیء به نام توصیف‌گر باشد. توصیف‌گرها کلاس‌هایی هستند که یک یا چند مورد از متدهای زیر را پیاده‌سازی می‌کنند:

• `__get__(self, instance, owner)`: زمانی فراخوانی می‌شود که به مقدار توصیف‌گر دسترسی پیدا شود.
• `__set__(self, instance, value)`: زمانی فراخوانی می‌شود که مقدار توصیف‌گر تنظیم شود.
• `__delete__(self, instance)`: زمانی فراخوانی می‌شود که مقدار توصیف‌گر حذف شود.

زمانی که یک صفت از نمونه یک کلاس، یک توصیف‌گر باشد، پایتون به طور خودکار این متدها را به جای دسترسی مستقیم به صفت زیربنایی فراخوانی می‌کند. این مکانیزم رهگیری، پایه و اساس کنترل دسترسی به خصوصیت‌ها و اعتبارسنجی داده‌ها را فراهم می‌کند.

توصیف‌گرهای داده‌ای در مقابل توصیف‌گرهای غیرداده‌ای

توصیف‌گرها به دو دسته تقسیم می‌شوند:

• توصیف‌گرهای داده‌ای (Data Descriptors): هر دو متد `__get__` و `__set__` را (و به صورت اختیاری `__delete__`) پیاده‌سازی می‌کنند. آن‌ها نسبت به صفات نمونه با نام یکسان، اولویت بالاتری دارند. این بدان معناست که وقتی به صفتی دسترسی پیدا می‌کنید که یک توصیف‌گر داده‌ای است، متد `__get__` توصیف‌گر همیشه فراخوانی می‌شود، حتی اگر نمونه دارای صفتی با همان نام باشد.
• توصیف‌گرهای غیرداده‌ای (Non-Data Descriptors): فقط متد `__get__` را پیاده‌سازی می‌کنند. آن‌ها نسبت به صفات نمونه اولویت پایین‌تری دارند. اگر نمونه دارای صفتی با همان نام باشد، آن صفت به جای فراخوانی متد `__get__` توصیف‌گر برگردانده می‌شود. این ویژگی آن‌ها را برای مواردی مانند پیاده‌سازی خصوصیت‌های فقط-خواندنی (read-only) مفید می‌سازد.

تفاوت اصلی در وجود متد `__set__` نهفته است. عدم وجود این متد، یک توصیف‌گر را به یک توصیف‌گر غیرداده‌ای تبدیل می‌کند.

مثال‌های عملی از کاربرد توصیف‌گرها

بیایید قدرت توصیف‌گرها را با چند مثال عملی نشان دهیم.

مثال ۱: بررسی نوع (Type Checking)

فرض کنید می‌خواهید اطمینان حاصل کنید که یک صفت خاص همیشه مقداری از یک نوع مشخص را در خود نگه می‌دارد. توصیف‌گرها می‌توانند این محدودیت نوع را اعمال کنند:

class Typed:
    def __init__(self, name, expected_type):
        self.name = name
        self.expected_type = expected_type

    def __get__(self, instance, owner):
        if instance is None:
            return self  # Accessing from the class itself
        return instance.__dict__[self.name]

    def __set__(self, instance, value):
        if not isinstance(value, self.expected_type):
            raise TypeError(f"Expected {self.expected_type}, got {type(value)}")
        instance.__dict__[self.name] = value

class Person:
    name = Typed('name', str)
    age = Typed('age', int)

    def __init__(self, name, age):
        self.name = name
        self.age = age

# Usage:
person = Person("Alice", 30)
print(person.name)  # Output: Alice
print(person.age)   # Output: 30

try:
    person.age = "thirty"
except TypeError as e:
    print(e) # Output: Expected <class 'int'>, got <class 'str'>

در این مثال، توصیف‌گر `Typed` بررسی نوع را برای صفات `name` و `age` در کلاس `Person` اعمال می‌کند. اگر سعی کنید مقداری با نوع اشتباه به آن اختصاص دهید، یک `TypeError` ایجاد خواهد شد. این کار یکپارچگی داده‌ها را بهبود می‌بخشد و از خطاهای غیرمنتظره در ادامه کد جلوگیری می‌کند.

مثال ۲: اعتبارسنجی داده‌ها (Data Validation)

علاوه بر بررسی نوع، توصیف‌گرها می‌توانند اعتبارسنجی داده‌های پیچیده‌تری را نیز انجام دهند. به عنوان مثال، ممکن است بخواهید اطمینان حاصل کنید که یک مقدار عددی در یک محدوده خاص قرار دارد:

class Sized:
    def __init__(self, name, min_value, max_value):
        self.name = name
        self.min_value = min_value
        self.max_value = max_value

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__[self.name]

    def __set__(self, instance, value):
        if not isinstance(value, (int, float)):
            raise TypeError("Value must be a number")
        if not (self.min_value <= value <= self.max_value):
            raise ValueError(f"Value must be between {self.min_value} and {self.max_value}")
        instance.__dict__[self.name] = value

class Product:
    price = Sized('price', 0, 1000)

    def __init__(self, price):
        self.price = price

# Usage:
product = Product(99.99)
print(product.price) # Output: 99.99

try:
    product.price = -10
except ValueError as e:
    print(e) # Output: Value must be between 0 and 1000

در اینجا، توصیف‌گر `Sized` اعتبارسنجی می‌کند که صفت `price` در کلاس `Product` عددی در محدوده ۰ تا ۱۰۰۰ باشد. این کار تضمین می‌کند که قیمت محصول در محدوده معقولی باقی بماند.

مثال ۳: خصوصیت‌های فقط-خواندنی (Read-Only)

شما می‌توانید با استفاده از توصیف‌گرهای غیرداده‌ای، خصوصیت‌های فقط-خواندنی ایجاد کنید. با تعریف تنها متد `__get__`، از تغییر مستقیم صفت توسط کاربران جلوگیری می‌کنید:

class ReadOnly:
    def __init__(self, name):
        self.name = name

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance._private_value  # Access a private attribute

class Circle:
    radius = ReadOnly('radius')

    def __init__(self, radius):
        self._private_value = radius  # Store value in a private attribute

# Usage:
circle = Circle(5)
print(circle.radius)  # Output: 5

try:
    circle.radius = 10  # This will create a *new* instance attribute!
    print(circle.radius) # Output: 10
    print(circle.__dict__) # Output: {'_private_value': 5, 'radius': 10}
except AttributeError as e:
    print(e) # This won't be triggered because a new instance attribute has shadowed the descriptor.

در این سناریو، توصیف‌گر `ReadOnly` صفت `radius` کلاس `Circle` را فقط-خواندنی می‌کند. توجه داشته باشید که تخصیص مستقیم مقدار به `circle.radius` خطایی ایجاد نمی‌کند؛ در عوض، یک صفت نمونه جدید ایجاد می‌کند که روی توصیف‌گر سایه می‌اندازد (shadows). برای جلوگیری واقعی از تخصیص، باید متد `__set__` را پیاده‌سازی کرده و یک `AttributeError` ایجاد کنید. این مثال تفاوت ظریف بین توصیف‌گرهای داده‌ای و غیرداده‌ای و نحوه وقوع سایه‌اندازی با دومی را نشان می‌دهد.

مثال ۴: محاسبه با تأخیر (ارزیابی تنبل - Lazy Evaluation)

توصیف‌گرها همچنین می‌توانند برای پیاده‌سازی ارزیابی تنبل استفاده شوند، جایی که یک مقدار تنها زمانی محاسبه می‌شود که برای اولین بار به آن دسترسی پیدا شود:

import time

class LazyProperty:
    def __init__(self, func):
        self.func = func
        self.name = func.__name__

    def __get__(self, instance, owner):
        if instance is None:
            return self
        value = self.func(instance)
        instance.__dict__[self.name] = value  # Cache the result
        return value

class DataProcessor:
    @LazyProperty
    def expensive_data(self):
        print("Calculating expensive data...")
        time.sleep(2)  # Simulate a long computation
        return [i for i in range(1000000)]

# Usage:
processor = DataProcessor()
print("Accessing data for the first time...")
start_time = time.time()
data = processor.expensive_data  # This will trigger the computation
end_time = time.time()
print(f"Time taken for first access: {end_time - start_time:.2f} seconds")

print("Accessing data again...")
start_time = time.time()
data = processor.expensive_data  # This will use the cached value
end_time = time.time()
print(f"Time taken for second access: {end_time - start_time:.2f} seconds")

توصیف‌گر `LazyProperty` محاسبه `expensive_data` را تا اولین دسترسی به آن به تأخیر می‌اندازد. دسترسی‌های بعدی نتیجه کش‌شده را بازیابی می‌کنند و عملکرد را بهبود می‌بخشند. این الگو برای صفاتی که برای محاسبه به منابع قابل توجهی نیاز دارند و همیشه مورد نیاز نیستند، مفید است.

تکنیک‌های پیشرفته توصیف‌گر

فراتر از مثال‌های پایه، پروتکل توصیف‌گر امکانات پیشرفته‌تری را ارائه می‌دهد:

ترکیب توصیف‌گرها

شما می‌توانید توصیف‌گرها را برای ایجاد رفتارهای پیچیده‌تر برای خصوصیت‌ها ترکیب کنید. به عنوان مثال، می‌توانید یک توصیف‌گر `Typed` را با یک توصیف‌گر `Sized` ترکیب کنید تا هم محدودیت‌های نوع و هم محدوده را برای یک صفت اعمال کنید.

class ValidatedProperty:
    def __init__(self, name, expected_type, min_value=None, max_value=None):
        self.name = name
        self.expected_type = expected_type
        self.min_value = min_value
        self.max_value = max_value

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__[self.name]

    def __set__(self, instance, value):
        if not isinstance(value, self.expected_type):
            raise TypeError(f"Expected {self.expected_type}, got {type(value)}")

        if self.min_value is not None and value < self.min_value:
            raise ValueError(f"Value must be at least {self.min_value}")

        if self.max_value is not None and value > self.max_value:
            raise ValueError(f"Value must be at most {self.max_value}")

        instance.__dict__[self.name] = value

class Employee:
    salary = ValidatedProperty('salary', int, min_value=0, max_value=1000000)

    def __init__(self, salary):
        self.salary = salary

# Example
employee = Employee(50000)
print(employee.salary)

try:
    employee.salary = -1000
except ValueError as e:
    print(e)

try:
    employee.salary = "abc"
except TypeError as e:
    print(e)

استفاده از متاکلاس‌ها با توصیف‌گرها

متاکلاس‌ها می‌توانند برای اعمال خودکار توصیف‌گرها به تمام صفات یک کلاس که معیارهای خاصی را برآورده می‌کنند، استفاده شوند. این کار می‌تواند به طور قابل توجهی کد تکراری را کاهش دهد و از هماهنگی در کلاس‌های شما اطمینان حاصل کند.

class DescriptorMetaclass(type):
    def __new__(cls, name, bases, attrs):
        for attr_name, attr_value in attrs.items():
            if isinstance(attr_value, Descriptor):
                attr_value.name = attr_name  # Inject the attribute name into the descriptor
        return super().__new__(cls, name, bases, attrs)

class Descriptor:
    def __get__(self, instance, owner):
        if instance is None:
            return self
        return instance.__dict__[self.name]

    def __set__(self, instance, value):
        instance.__dict__[self.name] = value

class UpperCase(Descriptor):
    def __set__(self, instance, value):
        if not isinstance(value, str):
            raise TypeError("Value must be a string")
        instance.__dict__[self.name] = value.upper()

class MyClass(metaclass=DescriptorMetaclass):
    name = UpperCase()

# Example Usage:
obj = MyClass()
obj.name = "john doe"
print(obj.name)  # Output: JOHN DOE

بهترین شیوه‌ها برای استفاده از توصیف‌گرها

برای استفاده مؤثر از پروتکل توصیف‌گر، این بهترین شیوه‌ها را در نظر بگیرید:

• از توصیف‌گرها برای مدیریت صفات با منطق پیچیده استفاده کنید: توصیف‌گرها زمانی بیشترین ارزش را دارند که نیاز به اعمال محدودیت‌ها، انجام محاسبات، یا پیاده‌سازی رفتار سفارشی هنگام دسترسی یا تغییر یک صفت دارید.
• توصیف‌گرها را متمرکز و قابل استفاده مجدد نگه دارید: توصیف‌گرها را طوری طراحی کنید که یک کار خاص را انجام دهند و آن‌ها را به اندازه‌ای کلی بسازید که در چندین کلاس قابل استفاده مجدد باشند.
• استفاده از property() را به عنوان جایگزین برای موارد ساده در نظر بگیرید: تابع داخلی `property()` یک سینتکس ساده‌تر برای پیاده‌سازی متدهای اصلی getter، setter و deleter فراهم می‌کند. زمانی از توصیف‌گرها استفاده کنید که به کنترل پیشرفته‌تر یا منطق قابل استفاده مجدد نیاز دارید.
• مراقب عملکرد باشید: دسترسی از طریق توصیف‌گر می‌تواند در مقایسه با دسترسی مستقیم به صفت، سربار ایجاد کند. از استفاده بیش از حد از توصیف‌گرها در بخش‌های حساس به عملکرد کد خود خودداری کنید.
• از نام‌های واضح و توصیفی استفاده کنید: برای توصیف‌گرهای خود نام‌هایی انتخاب کنید که به وضوح هدف آن‌ها را نشان دهد.
• توصیف‌گرهای خود را به طور کامل مستند کنید: هدف هر توصیف‌گر و نحوه تأثیر آن بر دسترسی به صفت را توضیح دهید.

ملاحظات جهانی و بین‌المللی‌سازی

هنگام استفاده از توصیف‌گرها در یک زمینه جهانی، این عوامل را در نظر بگیرید:

• اعتبارسنجی داده‌ها و بومی‌سازی: اطمینان حاصل کنید که قوانین اعتبارسنجی داده‌های شما برای مناطق مختلف مناسب است. به عنوان مثال، فرمت‌های تاریخ و اعداد در کشورهای مختلف متفاوت است. استفاده از کتابخانه‌هایی مانند `babel` را برای پشتیبانی از بومی‌سازی در نظر بگیرید.
• مدیریت ارز: اگر با مقادیر پولی کار می‌کنید، از کتابخانه‌ای مانند `moneyed` برای مدیریت صحیح ارزهای مختلف و نرخ‌های تبدیل استفاده کنید.
• مناطق زمانی: هنگام کار با تاریخ و زمان، از مناطق زمانی آگاه باشید و از کتابخانه‌هایی مانند `pytz` برای مدیریت تبدیل مناطق زمانی استفاده کنید.
• کدگذاری کاراکترها: اطمینان حاصل کنید که کد شما کدگذاری‌های مختلف کاراکترها را به درستی مدیریت می‌کند، به خصوص هنگام کار با داده‌های متنی. UTF-8 یک کدگذاری با پشتیبانی گسترده است.

جایگزین‌های توصیف‌گرها

در حالی که توصیف‌گرها قدرتمند هستند، همیشه بهترین راه‌حل نیستند. در اینجا چند جایگزین برای بررسی وجود دارد:

• `property()`: برای منطق ساده getter/setter، تابع `property()` سینتکس مختصرتری را فراهم می‌کند.
• `__slots__`: اگر می‌خواهید مصرف حافظه را کاهش دهید و از ایجاد پویای صفات جلوگیری کنید، از `__slots__` استفاده کنید.
• کتابخانه‌های اعتبارسنجی: کتابخانه‌هایی مانند `marshmallow` روشی اعلانی برای تعریف و اعتبارسنجی ساختارهای داده ارائه می‌دهند.
• کلاس‌های داده (Dataclasses): کلاس‌های داده در پایتون ۳.۷ به بالا روشی مختصر برای تعریف کلاس‌ها با متدهای تولید شده خودکار مانند `__init__`، `__repr__` و `__eq__` ارائه می‌دهند. آن‌ها می‌توانند با توصیف‌گرها یا کتابخانه‌های اعتبارسنجی برای اعتبارسنجی داده‌ها ترکیب شوند.

نتیجه‌گیری

پروتکل توصیف‌گر پایتون ابزاری ارزشمند برای مدیریت دسترسی به صفات و اعتبارسنجی داده‌ها در کلاس‌های شماست. با درک مفاهیم اصلی و بهترین شیوه‌های آن، می‌توانید کدی تمیزتر، قوی‌تر و قابل نگهداری‌تر بنویسید. در حالی که ممکن است توصیف‌گرها برای هر صفتی ضروری نباشند، زمانی که به کنترل دقیق بر دسترسی به خصوصیت‌ها و یکپارچگی داده‌ها نیاز دارید، ضروری هستند. به یاد داشته باشید که مزایای توصیف‌گرها را در برابر سربار بالقوه آن‌ها بسنجید و در صورت لزوم رویکردهای جایگزین را در نظر بگیرید. از قدرت توصیف‌گرها برای ارتقای مهارت‌های برنامه‌نویسی پایتون خود و ساخت برنامه‌های پیچیده‌تر بهره ببرید.