{"id":2728,"date":"2021-10-28T15:48:09","date_gmt":"2021-10-28T15:48:09","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=2728"},"modified":"2025-03-28T03:27:20","modified_gmt":"2025-03-28T03:27:20","slug":"python-descriptors","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/python-oop\/python-descriptors\/","title":{"rendered":"Python Descriptors"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about Python descriptors, how descriptors work, and how to apply them more effectively.<\/p>\n\n\n\n

Introduction to the Python descriptors #<\/a><\/h2>\n\n\n\n

Suppose you have a class<\/a> Person<\/code> with two instance attributes<\/a> first_name<\/code> and last_name<\/code>:<\/p>\n\n\n

class<\/span> Person<\/span>:<\/span>\n    def<\/span> __init__<\/span>(self, first_name, last_name)<\/span>:<\/span>\n        self.first_name = first_name\n        self.last_name = last_name<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And you want the first_name<\/code> and last_name<\/code> attributes to be non-empty strings. These plain attributes cannot guarantee this.<\/p>\n\n\n\n
class<\/span> Person<\/span>:<\/span>\n    def<\/span> __init__<\/span>(self, first_name, last_name)<\/span>:<\/span>\n        self.first_name = first_name\n        self.last_name = last_name\n\n    @property<\/span>\n    def<\/span> first_name<\/span>(self)<\/span>:<\/span>\n        return<\/span> self._first_name\n\n    @first_name.setter<\/span>\n    def<\/span> first_name<\/span>(self, value)<\/span>:<\/span>\n        if<\/span> not<\/span> isinstance(value, str):\n            raise<\/span> ValueError('The first name must a string'<\/span>)\n\n        if<\/span> len(value) == 0<\/span>:\n            raise<\/span> ValueError('The first name cannot be empty'<\/span>)\n\n        self._first_name = value\n\n    @property<\/span>\n    def<\/span> last_name<\/span>(self)<\/span>:<\/span>\n        return<\/span> self._last_name\n\n    @last_name.setter<\/span>\n    def<\/span> last_name<\/span>(self, value)<\/span>:<\/span>\n        if<\/span> not<\/span> isinstance(value, str):\n            raise<\/span> ValueError('The last name must a string'<\/span>)\n\n        if<\/span> len(value) == 0<\/span>:\n            raise<\/span> ValueError('The last name cannot be empty'<\/span>)\n\n        self._last_name = value<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
In this Person<\/code> class, the getter returns the attribute value while the setter validates it before assigning it to the attribute.<\/p>\n\n\n\n
This code works perfectly fine. However, it is redundant because the validation logic validates the first and last names is the same.<\/p>\n\n\n\n
Also, if the class has more attributes that require a non-empty string, you need to duplicate this logic in other properties. In other words, this validation logic is not reusable.<\/p>\n\n\n\n
To avoid duplicating the logic, you may have a method that validates data and reuse this method in other properties. This approach will enable reusability. However, Python has a better way to solve this by using descriptors.<\/p>\n\n\n\n
First, define a descriptor class that implements three methods __set_name__<\/code>, __get__<\/code>, and __set__<\/code>:<\/p>\n\n\n
class<\/span> RequiredString<\/span>:<\/span>\n    def<\/span> __set_name__<\/span>(self, owner, name)<\/span>:<\/span>\n        self.property_name = name\n\n    def<\/span> __get__<\/span>(self, instance, owner)<\/span>:<\/span>\n        if<\/span> instance is<\/span> None<\/span>:\n            return<\/span> self\n\n        return<\/span> instance.__dict__[self.property_name] or<\/span> None<\/span>\n\n    def<\/span> __set__<\/span>(self, instance, value)<\/span>:<\/span>\n        if<\/span> not<\/span> isinstance(value, str):\n            raise<\/span> ValueError(f'The {self.property_name}<\/span> must be a string'<\/span>)\n\n        if<\/span> len(value) == 0<\/span>:\n            raise<\/span> ValueError(f'The {self.property_name}<\/span> cannot be empty'<\/span>)\n\n        instance.__dict__[self.property_name] = value<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Second, use the RequiredString<\/code> class in the Person<\/code> class:<\/p>\n\n\n
class<\/span> Person<\/span>:<\/span>\n    first_name = RequiredString()\n    last_name = RequiredString()<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
If you assign an empty string or a non-string value to the first_name<\/code> or last_name<\/code> attribute of the Person<\/code> class, you’ll get an error.<\/p>\n\n\n\n
For example, the following attempts to assign an empty string to the first_name<\/code> attribute:<\/p>\n\n\n
try<\/span>:\n    person = Person()\n    person.first_name = ''<\/span>\nexcept<\/span> ValueError as<\/span> e:\n    print(e)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Error:<\/p>\n\n\n
The first_name must be a string<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Also, you can use the RequiredString<\/code> class in any class with attributes that require a non-empty string value.<\/p>\n\n\n\n
Besides the RequiredString<\/code>, you can define other descriptors to enforce other data types like age, email, and phone. And this is just a simple application of the descriptors.<\/p>\n\n\n\n
Let’s understand how descriptors work.<\/p>\n\n\n\n
Descriptor protocol #<\/a><\/h2>\n\n\n\n
In Python, the descriptor protocol consists of three methods:<\/p>\n\n\n\n
To enforce the data validity, you can use property<\/a> with a getter and setter methods, like this:<\/p>\n\n\n