Python Descriptors: Control Attribute Access Simply

Python Descriptors: How to Control Attribute Access Without Losing Your Mind

You've probably been using descriptors without even knowing it. Every time you access a property, a classmethod, or even a staticmethod in Python, you're interacting with the descriptor protocol. It's one of those features that runs quietly in the background, making everything work smoothly.

Let me show you what descriptors actually are and how you can use them to write cleaner, more powerful Python code.

What Makes a Descriptor?

A descriptor is simply an object that implements one or more of these special methods: __get__, __set__, or __delete__. When you access an attribute on a class, Python checks if the attribute's value has these methods. If it does, Python calls them instead of just returning the value.

Here's the simplest descriptor you can write:

class VerboseAttribute:
    def __get__(self, obj, objtype=None):
        print(f"Getting attribute from {obj}")
        return 42

    def __set__(self, obj, value):
        print(f"Setting attribute on {obj} to {value}")

class MyClass:
    name = VerboseAttribute()

obj = MyClass()
obj.name  # Prints: Getting attribute from <__main__.MyClass object at 0x...>
obj.name = 100  # Prints: Setting attribute on <__main__.MyClass object at 0x...>

Why Descriptors Matter in Real Code

At PythonSkillset.com, we've seen developers struggle with validation and caching logic scattered across their codebases. Descriptors solve this elegantly by letting you centralize the logic.

Think about validation. Instead of writing getter/setter methods for every attribute, you can create a reusable descriptor:

class PositiveNumber:
    def __init__(self, default=0):
        self.default = default

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return obj.__dict__.get(self.attr_name, self.default)

    def __set__(self, obj, value):
        if value <= 0:
            raise ValueError(f"{self.attr_name} must be positive")
        obj.__dict__[self.attr_name] = value

    def __set_name__(self, owner, name):
        self.attr_name = name

class Product:
    price = PositiveNumber()
    quantity = PositiveNumber()

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

# This works fine
laptop = Product(999, 10)

# This raises ValueError
# tablet = Product(-50, 5)  # Would raise ValueError

The __set_name__ Hook Nobody Talks About

Notice the __set_name__ method in the example above? That's a relatively modern addition to the descriptor protocol. When Python creates the class, it calls __set_name__ on each descriptor, passing the class and attribute name. This means descriptors can automatically know their own attribute name without you having to specify it manually.

Before __set_name__, you had to do this ugly pattern:

# Old way - requiring explicit name
class PositiveNumber:
    def __init__(self, name, default=0):
        self.attr_name = name
        self.default = default

class Product:
    price = PositiveNumber("price")
    quantity = PositiveNumber("quantity")

Now descriptors are self-aware and cleaner.

Data Descriptors vs Non-Data Descriptors

Here's where things get subtle. If a descriptor implements __set__ or __delete__, it's a data descriptor. If it only implements __get__, it's a non-data descriptor.

The distinction matters for attribute lookup order. Data descriptors take priority over instance attributes, while non-data descriptors don't:

class DataDescriptor:
    def __get__(self, obj, objtype=None):
        return "from data descriptor"
    def __set__(self, obj, value):
        pass  # Makes it a data descriptor

class NonDataDescriptor:
    def __get__(self, obj, objtype=None):
        return "from non-data descriptor"

class Demo:
    data = DataDescriptor()
    non_data = NonDataDescriptor()

d = Demo()
d.data = "instance value"
d.non_data = "instance value"

print(d.data)      # Prints: "from data descriptor" (data descriptor wins)
print(d.non_data)  # Prints: "instance value" (instance attribute wins)

This is exactly how property works in Python. It's a data descriptor, which is why you can't override it with an instance attribute.

Real-World Use Case: Lazy Loading

Let's look at something practical. Lazy loading is incredibly useful when you have expensive operations that might never be needed:

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

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self

        value = self.func(obj)
        obj.__dict__[self.attr_name] = value  # Cache it
        return value

class DatabaseConnection:
    def __init__(self, config):
        self.config = config

    @LazyProperty
    def expensive_connection(self):
        print("Creating database connection...")
        return f"Connected to {self.config['host']}"

# Connection isn't made until we access it
db = DatabaseConnection({"host": "localhost"})
print("Object created, connection not yet made")

# First access triggers creation
print(db.expensive_connection)  # Prints: Creating database connection...

# Second access uses cached value
print(db.expensive_connection)  # Just returns cached value

The Pitfall Most Developers Miss

When building descriptors, one mistake consistently trips people up. If you store state on the descriptor itself instead of the instance, all instances share the same value:

class BadDescriptor:
    def __init__(self):
        self.value = {}  # Shared state - BAD!

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return self.value

Always store instance-specific data in the instance's __dict__, not in the descriptor.

When to Use Descriptors vs Other Tools

Python gives you several ways to control attribute access. Here's when I reach for descriptors:

• Multiple classes need the same validation or transformation logic: Descriptor all the way
• One-off property with custom logic: Use @property decorator
• Need to intercept attribute access on existing classes: Use __getattr__ on the class
• Performance is critical: Descriptors are implemented in C (like property) and are faster than Python-level alternatives

What You Can Build Next

Descriptors unlock a whole world of clean, reusable code. You can build validators, type checkers, computed properties, caching layers, and even ORM-like field definitions. At PythonSkillset, we've seen teams reduce their codebase by 40% just by properly using descriptors for validation logic.

Start small. Look for repeated patterns in your code where you're writing the same getter/setter logic across multiple classes. That's your cue to reach for a descriptor.