Property Deleter

The @property.deleter decorator is a component of Python’s descriptor protocol that defines the method invoked when an instance attribute managed by a @property is targeted by the del statement. It allows developers to intercept attribute deletion to execute custom logic, modify internal state, or manage memory explicitly, rather than allowing Python to attempt a standard dictionary key deletion.

Mechanics and Syntax

To use a property deleter, a base property (the getter) must first be established using the @property decorator. The deleter is then defined by applying the @<property_name>.deleter decorator to a method sharing the exact same name as the property.

The decorated method must accept exactly one argument: self.

class Entity:
    def __init__(self):
        self._internal_state = "active"

    @property
    def state(self):
        return self._internal_state

    @state.deleter
    def state(self):
        # Logic executed when 'del obj.state' is called
        del self._internal_state

Execution

The deleter method is triggered exclusively by the del keyword acting on the property of an instance.

instance = Entity()


# Triggers the @state.deleter method
del instance.state 


# Attempting to access instance.state now will raise an AttributeError 

# (assuming the getter relies on _internal_state)

Underlying Implementation

In Python, @property is a built-in class that implements the descriptor protocol (__get__, __set__, and __delete__). The property constructor accepts four optional arguments: fget, fset, fdel, and doc.

When you use the @<property_name>.deleter decorator, you are invoking a method on the existing property object. This method returns a new copy of the property object with the fdel attribute assigned to the decorated function, while inheriting the fget (and potentially fset) from the original property.

The decorator syntax is syntactic sugar for the following functional equivalent:

class Entity:
    def __init__(self):
        self._internal_state = "active"

    def _get_state(self):
        return self._internal_state

    def _del_state(self):
        del self._internal_state

    # Explicitly passing the deleter function to the fdel parameter
    state = property(fget=_get_state, fset=None, fdel=_del_state)

Behavior Constraints

• Name Matching: The function decorated with @<property_name>.deleter must have the exact same identifier as the original property.
• Missing Deleter: If a property is defined without a deleter and a del operation is attempted on it, Python will raise an AttributeError: can't delete attribute.
• Class-Level Deletion: The deleter only intercepts del operations on instances of the class. Executing del Entity.state will delete the property descriptor object from the class namespace entirely, bypassing the fdel method.

Master Python with Deep Grasping Methodology!

Learn More