Descriptors Behind the Scenes

Introduction

Welcome back to Class Machinery: Dataclasses, Descriptors, Metaclasses! You've successfully completed the first lesson on advanced dataclasses, where you built robust, immutable configuration objects with sophisticated validation. You now understand how to leverage frozen, slots, and kw_only arguments alongside__post_init__processing to create production-ready data containers. Today, we're diving into one of Python's most elegant yet underutilized features: descriptors . While dataclasses help us create better data containers, descriptors give us fine-grained control over attribute access itself. They're the mechanism that powers Python's properties, methods, and even the classmethod and staticmethod decorators you use every day. In this lesson, we'll build a reusable Range descriptor that provides type coercion and validation for numeric attributes. We'll explore the three core methods of the descriptor protocol:__get__,__set__, and__delete__, and also use the optional__set_name__hook for automatic naming. By the end, you'll understand how to create descriptors that can be applied to multiple classes and attributes, providing centralized validation logic that makes your code more maintainable and DRY (Don't Repeat Yourself).

Understanding the Descriptor Protocol

Descriptors are objects that define how attribute access is handled for other objects. When you access an attribute on an instance, Python checks if the class defines that attribute as a descriptor. If it does, Python delegates the access operation to the descriptor's special methods rather than performing the default attribute lookup. The Python descriptor protocol consists of three main methods that control attribute access:__get__(self, instance, owner) : retrieval (reading a value)__set__(self, instance, value) : assignment (writing a value)__delete__(self, instance) : deletion (del obj.attr) Python also defines an optional__set_name__(self, owner, name) method, which is called automatically when the descriptor is assigned to a class attribute during class creation. This hook is not part of per-access operations; instead, it provides the descriptor with its attribute name and the owning class, which is often useful for automatic naming and storage. This protocol is incredibly powerful because it allows you to centralize attribute logic in reusable objects. Instead of writing custom property definitions for every validated attribute, you can create a single descriptor class and apply it to multiple attributes across different classes. This approach promotes code reuse and ensures consistent behavior across your entire application.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Python

from typing import Any, Callable

class Range:
    """
    Reusable validating descriptor.
    - coerce: callable to convert incoming value (e.g., float, int, Decimal)
    - min/max: inclusive numeric bounds (in coerced type)
    """
    def __init__(
        self,
        *,
        min: Any | None = None,
        max: Any | None = None,
        coerce: Callable[[Any], Any] = float,
    ) -> None:
        self._coerce = coerce
        self._min = None if min is None else coerce(min)
        self._max = None if max is None else coerce(max)
        self._name = ""
        self._storage = ""

from typing import Any, Callable

class Range:
    """
    Reusable validating descriptor.
    - coerce: callable to convert incoming value (e.g., float, int, Decimal)
    - min/max: inclusive numeric bounds (in coerced type)
    """
    def __init__(
        self,
        *,
        min: Any | None = None,
        max: Any | None = None,
        coerce: Callable[[Any], Any] = float,
    ) -> None:
        self._coerce = coerce
        self._min = None if min is None else coerce(min)
        self._max = None if max is None else coerce(max)
        self._name = ""
        self._storage = ""

Python

    def __set_name__(self, owner: type, name: str) -> None:
        self._name = name
        self._storage = f"_{name}"

    def __set_name__(self, owner: type, name: str) -> None:
        self._name = name
        self._storage = f"_{name}"

Python

    def __get__(self, instance: Any, owner: type | None = None) -> Any:
        if instance is None:
            return self
        return getattr(instance, self._storage, None)

    def __get__(self, instance: Any, owner: type | None = None) -> Any:
        if instance is None:
            return self
        return getattr(instance, self._storage, None)

Python

    def __set__(self, instance: Any, value: Any) -> None:
        v = self._coerce(value)
        if self._min is not None and v < self._min:
            raise ValueError(f"{self._name} must be >= {self._min}")
        if self._max is not None and v > self._max:
            raise ValueError(f"{self._name} must be <= {self._max}")
        object.__setattr__(instance, self._storage, v)

    def __set__(self, instance: Any, value: Any) -> None:
        v = self._coerce(value)
        if self._min is not None and v < self._min:
            raise ValueError(f"{self._name} must be >= {self._min}")
        if self._max is not None and v > self._max:
            raise ValueError(f"{self._name} must be <= {self._max}")
        object.__setattr__(instance, self._storage, v)

Python

    def __delete__(self, instance: Any) -> None:
        try:
            object.__delattr__(instance, self._storage)
        except AttributeError:
            raise AttributeError(f"{self._name} is not set") from None

    def __delete__(self, instance: Any) -> None:
        try:
            object.__delattr__(instance, self._storage)
        except AttributeError:
            raise AttributeError(f"{self._name} is not set") from None

Python

class Product:
    price = Range(min=0, coerce=float)
    rating = Range(min=0, max=5, coerce=float)
    stock = Range(min=0, coerce=int)

    def __init__(self, name: str, price: Any, rating: Any, stock: Any) -> None:
        self.name = " ".join(str(name).split())  # Normalize whitespace
        self.price = price
        self.rating = rating
        self.stock = stock

    def __repr__(self) -> str:
        return (
            f"Product({self.name!r}, price={self.price:.2f}, "
            f"rating={self.rating:.1f}, stock={self.stock})"
        )

class Product:
    price = Range(min=0, coerce=float)
    rating = Range(min=0, max=5, coerce=float)
    stock = Range(min=0, coerce=int)

    def __init__(self, name: str, price: Any, rating: Any, stock: Any) -> None:
        self.name = " ".join(str(name).split())  # Normalize whitespace
        self.price = price
        self.rating = rating
        self.stock = stock

    def __repr__(self) -> str:
        return (
            f"Product({self.name!r}, price={self.price:.2f}, "
            f"rating={self.rating:.1f}, stock={self.stock})"
        )

Python

from decimal import Decimal, ROUND_HALF_EVEN

class ServicePlan:
    monthly_fee = Range(min=0, coerce=Decimal)
    users = Range(min=1, max=1000, coerce=int)

    def __init__(self, name: str, monthly_fee: Any, users: Any) -> None:
        self.name = " ".join(str(name).split())
        self.monthly_fee = monthly_fee
        self.users = users

    def __repr__(self) -> str:
        fee = self.monthly_fee.quantize(Decimal("0.01"), rounding=ROUND_HALF_EVEN)
        return f"ServicePlan({self.name!r}, monthly_fee={fee}, users={self.users})"

from decimal import Decimal, ROUND_HALF_EVEN

class ServicePlan:
    monthly_fee = Range(min=0, coerce=Decimal)
    users = Range(min=1, max=1000, coerce=int)

    def __init__(self, name: str, monthly_fee: Any, users: Any) -> None:
        self.name = " ".join(str(name).split())
        self.monthly_fee = monthly_fee
        self.users = users

    def __repr__(self) -> str:
        fee = self.monthly_fee.quantize(Decimal("0.01"), rounding=ROUND_HALF_EVEN)
        return f"ServicePlan({self.name!r}, monthly_fee={fee}, users={self.users})"

Python

if __name__ == "__main__":
    p = Product("  Deluxe   Widget ", "10.50", 4.25, 3)
    print(repr(p))
    print(f"{p.price:.2f}")
    print(p.stock)
    del p.stock
    print(p.stock)

    sp = ServicePlan("Team", "12.499", 50)
    print(repr(sp))
    print(isinstance(Product.price, Range))

if __name__ == "__main__":
    p = Product("  Deluxe   Widget ", "10.50", 4.25, 3)
    print(repr(p))
    print(f"{p.price:.2f}")
    print(p.stock)
    del p.stock
    print(p.stock)

    sp = ServicePlan("Team", "12.499", 50)
    print(repr(sp))
    print(isinstance(Product.price, Range))

text

Product('Deluxe Widget', price=10.50, rating=4.2, stock=3)
10.50
3
None
ServicePlan('Team', monthly_fee=12.50, users=50)
True

Product('Deluxe Widget', price=10.50, rating=4.2, stock=3)
10.50
3
None
ServicePlan('Team', monthly_fee=12.50, users=50)
True

Python

    try:
        p.price = -1
    except Exception as e:
        print(str(e))

    try:
        p.rating = 6
    except Exception as e:
        print(type(e).__name__)

    try:
        sp.users = 0
    except Exception as e:
        print(str(e))

    try:
        p.price = -1
    except Exception as e:
        print(str(e))

    try:
        p.rating = 6
    except Exception as e:
        print(type(e).__name__)

    try:
        sp.users = 0
    except Exception as e:
        print(str(e))

text

price must be >= 0.0
ValueError
users must be >= 1

price must be >= 0.0
ValueError
users must be >= 1

Python

from typing import Any, Callable

class Range:
    """
    Reusable validating descriptor.
    - coerce: callable to convert incoming value (e.g., float, int, Decimal)
    - min/max: inclusive numeric bounds (in coerced type)
    """
    def __init__(
        self,
        *,
        min: Any | None = None,
        max: Any | None = None,
        coerce: Callable[[Any], Any] = float,
    ) -> None:
        self._coerce = coerce
        self._min = None if min is None else coerce(min)
        self._max = None if max is None else coerce(max)
        self._name = ""
        self._storage = ""

Python

    def __set_name__(self, owner: type, name: str) -> None:
        self._name = name
        self._storage = f"_{name}"

Python

    def __get__(self, instance: Any, owner: type | None = None) -> Any:
        if instance is None:
            return self
        return getattr(instance, self._storage, None)

Python

    def __set__(self, instance: Any, value: Any) -> None:
        v = self._coerce(value)
        if self._min is not None and v < self._min:
            raise ValueError(f"{self._name} must be >= {self._min}")
        if self._max is not None and v > self._max:
            raise ValueError(f"{self._name} must be <= {self._max}")
        object.__setattr__(instance, self._storage, v)

Python

    def __delete__(self, instance: Any) -> None:
        try:
            object.__delattr__(instance, self._storage)
        except AttributeError:
            raise AttributeError(f"{self._name} is not set") from None

Python

class Product:
    price = Range(min=0, coerce=float)
    rating = Range(min=0, max=5, coerce=float)
    stock = Range(min=0, coerce=int)

    def __init__(self, name: str, price: Any, rating: Any, stock: Any) -> None:
        self.name = " ".join(str(name).split())  # Normalize whitespace
        self.price = price
        self.rating = rating
        self.stock = stock

    def __repr__(self) -> str:
        return (
            f"Product({self.name!r}, price={self.price:.2f}, "
            f"rating={self.rating:.1f}, stock={self.stock})"
        )

Python

from decimal import Decimal, ROUND_HALF_EVEN

class ServicePlan:
    monthly_fee = Range(min=0, coerce=Decimal)
    users = Range(min=1, max=1000, coerce=int)

    def __init__(self, name: str, monthly_fee: Any, users: Any) -> None:
        self.name = " ".join(str(name).split())
        self.monthly_fee = monthly_fee
        self.users = users

    def __repr__(self) -> str:
        fee = self.monthly_fee.quantize(Decimal("0.01"), rounding=ROUND_HALF_EVEN)
        return f"ServicePlan({self.name!r}, monthly_fee={fee}, users={self.users})"

Python

if __name__ == "__main__":
    p = Product("  Deluxe   Widget ", "10.50", 4.25, 3)
    print(repr(p))
    print(f"{p.price:.2f}")
    print(p.stock)
    del p.stock
    print(p.stock)

    sp = ServicePlan("Team", "12.499", 50)
    print(repr(sp))
    print(isinstance(Product.price, Range))

text

Product('Deluxe Widget', price=10.50, rating=4.2, stock=3)
10.50
3
None
ServicePlan('Team', monthly_fee=12.50, users=50)
True

Python

    try:
        p.price = -1
    except Exception as e:
        print(str(e))

    try:
        p.rating = 6
    except Exception as e:
        print(type(e).__name__)

    try:
        sp.users = 0
    except Exception as e:
        print(str(e))

text

price must be >= 0.0
ValueError
users must be >= 1

Introduction

Understanding the Descriptor Protocol

Join the 1M+ learners on CodeSignal

Building the Range Descriptor Foundation

Implementing Automatic Naming with __set_name__

Implementing Value Storage and Retrieval

Implementing Validation and Assignment

Supporting Deletion with delete

Applying Range to Product Classes

Advanced Descriptor Usage with Decimal Types

Demonstrating Descriptor Functionality

Testing Validation and Error Handling

Conclusion and Next Steps

Descriptors Behind the Scenes

Introduction

Understanding the Descriptor Protocol

Join the 1M+ learners on CodeSignal

Building the Range Descriptor Foundation

Implementing Automatic Naming with __set_name__

Implementing Value Storage and Retrieval

Implementing Validation and Assignment

Supporting Deletion with __delete__

Applying Range to Product Classes

Advanced Descriptor Usage with Decimal Types

Demonstrating Descriptor Functionality

Testing Validation and Error Handling

Conclusion and Next Steps

Supporting Deletion with delete