Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Property Deleter: Syntax and Practical Usage

python property deleter: Learn how to implement a Python property deleter to control attribute removal, handle edge cases, and maintain clean object state.

~4 min readPython
#property#deleter#attribute deletion#descriptors
A visual metaphor for a Python property deleter controlling attribute removal in an object.

When you use the @property decorator in Python, you can define getter, setter, and deleter methods. A property deleter in Python lets you control what happens when code attempts to delete an attribute that is backed by a property. This is useful for invalidating cached values, releasing resources, or blocking deletion entirely.

The Syntax of a Property Deleter

A property deleter is defined with the @<property_name>.deleter decorator. The method must have the same name as the property and accept only self (no extra arguments). Here is a minimal example:

python
class Temperature: def __init__(self, celsius): self._celsius = celsius @property def celsius(self): return self._celsius @celsius.setter def celsius(self, value): self._celsius = value @celsius.deleter def celsius(self): del self._celsius

The deleter is invoked when you run del obj.celsius. If you omit the deleter, attempting to delete the attribute raises an AttributeError. The deleter gives you a hook to run cleanup logic before the underlying attribute is removed.

What Happens When You Delete an Attribute

When you write del obj.celsius, Python looks up the property descriptor and calls its __delete__ method, which corresponds to the deleter you defined. The deleter runs exactly like a regular method, so you can access other instance state, perform validation, or raise exceptions.

Consider this behavior:

python
temp = Temperature(25) del temp.celsius print(hasattr(temp, '_celsius')) # False

If the deleter simply does del self._celsius, the backing attribute is removed. Subsequent access to temp.celsius will raise AttributeError because the getter tries to return self._celsius, which no longer exists. This is often the desired outcome when you want to make the attribute unavailable after deletion.

Common Use Cases for a Deleter

One common use is invalidating a cached value. Suppose you have a property that computes a value and caches it. Deleting the property should clear the cache so the next access recomputes it:

python
class Report: def __init__(self, data): self._data = data self._summary = None @property def summary(self): if self._summary is None: self._summary = self._compute_summary() return self._summary @summary.deleter def summary(self): self._summary = None

Here, del report.summary resets the cache, forcing a recomputation on the next read. This pattern is useful when the underlying data changes and you need to invalidate derived state without removing the attribute entirely.

Another use is releasing external resources. If a property represents a database connection or a file handle, the deleter can close it cleanly. The example below assumes a helper named open_connection; the same pattern applies to files and sockets:

python
class Connection: def __init__(self, url): self._conn = open_connection(url) # hypothetical helper @property def conn(self): return self._conn @conn.deleter def conn(self): if hasattr(self, '_conn'): self._conn.close() del self._conn

The hasattr guard makes repeated deletion safe. You can also prevent deletion entirely by raising an exception in the deleter, which is useful for attributes that must never be removed from an object's public interface.

Handling Deletion of Attributes That Were Never Set

If the backing attribute was never assigned, the deleter may fail with an AttributeError when it tries to del self._celsius. This can happen when a class allows instances without an initial value. Guard the deleter so it only removes the backing attribute when it exists:

python
class Temperature: @property def celsius(self): return self._celsius @celsius.setter def celsius(self, value): self._celsius = value @celsius.deleter def celsius(self): if hasattr(self, '_celsius'): del self._celsius

Now del temp.celsius on an instance that was never assigned a _celsius backing value completes without raising. Reading the getter before a value is set still raises AttributeError, but the deletion itself no longer fails with a misleading exception.

Deleting Properties on Subclasses and Inheritance

Like other methods, a property deleter is inherited when the subclass does not override the property. If a subclass overrides the property, it can also override the deleter. The override must use the same property name and the @<name>.deleter decorator:

python
class Base: @property def value(self): return self._value @value.deleter def value(self): del self._value class Child(Base): @property def value(self): return self._value * 2 @value.deleter def value(self): print("Deleting child value") Base.value.__delete__(self)

Use the parent property object directly to call the parent deleter, as in Base.value.__delete__(self). Do not try super().value.__delete__(self): super().value invokes the parent getter and returns its result, not the property descriptor. Accessing the property object directly lets you extend the parent's deletion logic without duplicating it.

When to Use a Deleter vs. Direct Attribute Deletion

If an attribute is truly internal and you never expect external code to delete it, a deleter may be unnecessary. However, when you expose a property as part of your class's public API, a deleter gives you control over the deletion contract. Use a deleter when:

  • You need to run cleanup logic before removing a value.
  • You want to prevent deletion entirely for invariant preservation.
  • You want to invalidate caches or recomputed state.

Directly deleting the backing attribute (del obj._celsius) bypasses the property logic and removes the underlying value immediately. That is fine for private attributes inside the class, but it breaks encapsulation when code outside the class reaches into the implementation. If you find yourself using del obj._celsius outside the class, consider exposing a proper deleter or a method instead.

Maintainability and Runtime Considerations

A deleter adds a method call overhead, but this is negligible compared to the actual deletion operation. The bigger concern is maintainability: a deleter that silently swallows errors or performs unexpected side effects can confuse future maintainers. Keep the deleter's behavior predictable and documented. For example, if deletion is not allowed, raise a clear AttributeError or PermissionError with a message explaining why.

Debugging can also become trickier because del obj.attribute no longer has a trivial effect. Use a debugger or logging inside the deleter when you need to trace when and why an attribute is removed. In production, ensure that the deleter does not raise exceptions that leave the object in an inconsistent state. If the deleter is meant to release external resources, make sure it is idempotent so calling it twice does not cause errors.

Finally, remember that the deleter is only invoked when you use the del statement on the property. If you assign None to the attribute, the setter is called instead, not the deleter. This distinction matters when designing your class's interface: choose deletion semantics that match the intended usage pattern.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.