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.

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:
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._celsiusThe 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:
temp = Temperature(25)
del temp.celsius
print(hasattr(temp, '_celsius')) # FalseIf 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:
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 = NoneHere, 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:
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._connThe 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:
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._celsiusNow 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:
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.