The @property
decorator simplifies the management of attributes in your Python classes. It allows you to control attribute access, enabling features such as data validation, lazy evaluation, and the creation of backward-compatible APIs without modifying the class’s public interface. By using @property
, you can avoid the clutter of getter and setter methods, keeping your code clean and Pythonic.
By the end of this tutorial, you’ll understand that:
- A property in Python is a tool for creating managed attributes in classes.
- The
@property
decorator allows you to define getter, setter, and deleter methods for attributes. - You use properties when you need controlled access or want to encapsulate logic without changing the API.
- Properties are useful for validating data, computing attributes, and creating read-only or read-write attributes.
- You should avoid
@property
when direct access is sufficient or performance is critical.
First, you’ll learn how to use property()
as a function through practical examples. These examples will demonstrate how to validate input data, compute attribute values dynamically, log your code, and more. Then you’ll explore the @property
decorator, the most common syntax for working with properties. To get the most out of this tutorial, you should know the basics of object-oriented programming, classes, and decorators in Python.
Get Your Code: Click here to download the free sample code that shows you how to use Python’s property() to add managed attributes to your classes.
Take the Quiz: Test your knowledge with our interactive “Python's property(): Add Managed Attributes to Your Classes” quiz. You’ll receive a score upon completion to help you track your learning progress:
Interactive Quiz
Python's property(): Add Managed Attributes to Your ClassesIn this quiz, you'll test your understanding of Python's property(). With this knowledge, you'll be able to create managed attributes in your classes, perform lazy attribute evaluation, provide computed attributes, and more.
Object-Oriented Python Live Course: Want to practice using @property
to protect your class invariants in a real project? In Real Python’s Object-Oriented Python live course, you build a complete simulator with an instructor, adding properties, alternative constructors, and other OOP tools only when the design needs them. Join the waitlist to hear about the next dates.
Managing Attributes in Your Classes
When you define a class in an object-oriented programming language, you’ll probably end up with some instance and class attributes. In other words, you’ll end up with variables that are accessible through the instance, class, or even both, depending on the language. Attributes represent and hold the internal state of a given object, which you’ll often need to access and mutate.
Typically, you have at least two ways to access and mutate an attribute. Either you can access and mutate the attribute directly or you can use methods. Methods are functions attached to a given class. They provide the behaviors and actions that an object can perform with its internal data and attributes.
If you expose attributes to the user, then they become part of the class’s public API. This means that your users will access and mutate them directly in their code. The problem comes when you need to change the internal implementation of a given attribute.
Say you’re working on a Circle
class and add an attribute called .radius
, making it public. You finish coding the class and ship it to your end users. They start using Circle
in their code to create a lot of awesome projects and applications. Good job!
Now suppose that you have an important user that comes to you with a new requirement. They don’t want Circle
to store the radius any longer. Instead, they want a public .diameter
attribute.
At this point, removing .radius
to start using .diameter
could break the code of some of your other users. You need to manage this situation in a way other than removing .radius
.
Programming languages such as Java and C++ encourage you to never expose your attributes to avoid this kind of problem. Instead, you should provide getter and setter methods, also known as accessors and mutators, respectively. These methods offer a way to change the internal implementation of your attributes without changing your public API.
Note: Getter and setter methods are often considered an anti-pattern and a signal of poor object-oriented design. The main argument behind this proposition is that these methods break encapsulation. They allow you to access and mutate the components of your objects from the outside.
These programming languages need getter and setter methods because they don’t have a suitable way to change an attribute’s internal implementation when a given requirement changes. Changing the internal implementation would require an API modification, which can break your end users’ code.
The Getter and Setter Approach in Python
Technically, there’s nothing that stops you from using getter and setter methods in Python. Here’s a quick example that shows how this approach would look:
point_v1.py
class Point:
def __init__(self, x, y):
self._x = x
self._y = y
def get_x(self):
return self._x
def set_x(self, value):
self._x = value
def get_y(self):
return self._y
def set_y(self, value):
self._y = value
In this example, you create a Point
class with two non-public attributes ._x
and ._y
to hold the Cartesian coordinates of the point at hand.
Note: Python doesn’t have the notion of access modifiers, such as private
, protected
, and public
, to restrict access to attributes and methods. In Python, the distinction is between public and non-public class members.
If you want to signal that a given attribute or method is non-public, then you have to use the well-known Python convention of prefixing the name with an underscore (_
). That’s the reason behind the naming of the attributes ._x
and ._y
.
Note that this is just a convention. It doesn’t stop you and other programmers from accessing the attributes using dot notation, as in obj._attr
. However, it’s bad practice to violate this convention.
To access and mutate the value of either ._x
or ._y
, you can use the corresponding getter and setter methods. Go ahead and save the above definition of Point
in a Python module and import the class into an interactive session. Then run the following code:
>>> from point_v1 import Point
>>> point = Point(12, 5)
>>> point.get_x()
12
>>> point.get_y()
5
>>> point.set_x(42)
>>> point.get_x()
42
>>> # Non-public attributes are still accessible
>>> point._x
42
>>> point._y
5
With .get_x()
and .get_y()
, you can access the current values of ._x
and ._y
. You can use the setter method to store a new value in the corresponding managed attribute. From the two final examples, you can confirm that Python doesn’t restrict access to non-public attributes. Whether or not you access them directly is up to you.
The Pythonic Approach
Even though the example you just saw uses the Python coding style, it isn’t Pythonic. In the example, the getter and setter methods don’t perform any further processing with the values of ._x
and ._y
, so you could just have plain attributes instead of methods.
You can rewrite Point
in a more concise and Pythonic way:
>>> class Point:
... def __init__(self, x, y):
... self.x = x
... self.y = y
...
>>> point = Point(12, 5)
>>> point.x
12
>>> point.y
5
>>> point.x = 42
>>> point.x
42
This code uncovers a fundamental Python principle: exposing attributes to the end user is normal and common. This is cool because you don’t need to clutter your classes with getter and setter methods all the time.
The question is, how do you handle requirement changes that would imply modifying the implementation of attributes without changing your APIs? For example, say that you need to add validation functionality on top of a given attribute. How would you do that if your attribute doesn’t have setter and getter methods where you can put that functionality?
Unlike Java and C++, Python provides handy tools that allow you to change the underlying implementation of your attributes without changing your public API. The most popular approach is to turn your attributes into properties.
Note: Another common approach to providing managed attributes is to use descriptors. In this tutorial, however, you’ll learn about properties only. If you want to dig into descriptors, check out the Python Descriptors: An Introduction tutorial.
Properties represent an intermediate functionality between a plain attribute, or field, and a method. In other words, they allow you to create methods that behave like attributes. With properties, you can change how you compute the target attribute whenever you need to.
For example, you can turn both .x
and .y
into properties. With this change, you can continue to access them as attributes while having them perform actions when your users access and mutate them.
Note: Properties aren’t exclusive to Python. Languages such as JavaScript, C#, Kotlin, and others also provide tools and techniques for creating properties as class members.
Python properties allow you to expose attributes as part of your classes’ public APIs. If you ever need to change an attribute’s underlying implementation, then you can conveniently turn it into a property at any time. In the following sections, you’ll learn how to create properties in Python.
Getting Started With Python’s property()
Using Python’s property()
is the Pythonic way to avoid getter and setter methods in your classes. This built-in function allows you to turn class attributes into properties or managed attributes. Because property()
is a built-in function, you can use it without importing anything. Additionally, property()
is implemented in C, which ensures optimized performance.
Note: It’s common to refer to property()
as a built-in function. However, property
is a class with a function-like name. That’s why most Python developers call it a function.
In this tutorial, you’ll follow the common practice of calling property()
a function rather than a class. However, in some sections, you’ll see it called a class to facilitate the explanation.
With property()
, you can attach implicit getter and setter methods to given class attributes. You can also specify a way to handle attribute deletion and provide an appropriate docstring for your properties.
Here’s the full signature of property()
:
property([fget=None, fset=None, fdel=None, doc=None])
The first two arguments take function objects that will play the role of getter (fget
) and setter (fset
) methods. Python automatically calls these function objects when you access or mutate the attribute at hand.
Here’s a summary of what each argument does:
Argument | Description |
---|---|
fget |
A function object that returns the value of the managed attribute |
fset |
A function object that allows you to set the value of the managed attribute |
fdel |
A function object that defines how the managed attribute handles deletion |
doc |
A string representing the property’s docstring |
The return value of property()
is the managed attribute itself. If you access the managed attribute with something like obj.attr
, then Python automatically calls fget()
. If you assign a new value to the attribute with something like obj.attr = value
, then Python calls fset()
using the input value
as an argument. Finally, if you run a del obj.attr
statement, then Python automatically calls fdel()
.
Note: The first three arguments to property()
take function objects. You can think of a function object as the function name without the calling pair of parentheses.
You can use doc
to provide an appropriate docstring for your properties. You and your fellow programmers will be able to read that docstring using Python’s help()
. The doc
argument is also useful when you’re working with code editors and IDEs that support docstring access.
You can use property()
either as a function or decorator to build your properties. In the following two sections, you’ll learn how to use both approaches. However, the decorator approach is more popular in the Python community.
Creating Attributes With property()
You can create a property by calling property()
with an appropriate set of arguments and assigning its return value to a class attribute. All the arguments to property()
are optional. However, you typically provide at least a getter function.
The following example shows how to create a Circle
class with a property that manages its radius:
circle_v1.py
class Circle:
def __init__(self, radius):
self._radius = radius
def _get_radius(self):
print("Get radius")
return self._radius
def _set_radius(self, value):
print("Set radius")
self._radius = value
def _del_radius(self):
print("Delete radius")
del self._radius
radius = property(
fget=_get_radius,
fset=_set_radius,
fdel=_del_radius,
doc="The radius property."
)
In this code snippet, you create Circle
. The class initializer, .__init__()
, takes radius
as an argument and stores it in a non-public attribute called ._radius
. Then, you define three non-public methods:
._get_radius()
returns the current value of._radius
._set_radius()
takesvalue
as an argument and assigns it to._radius
._del_radius()
deletes the instance attribute._radius
Once you have these three methods in place, you create a class attribute called .radius
to store the property object. To initialize the property, you pass the three methods as arguments to property()
. You also pass a suitable docstring for your property.
In this example, you use keyword arguments to improve readability and prevent confusion. That way, you know exactly which method goes into each argument.
To give Circle
a try, run the following code in your Python REPL:
>>> from circle_v1 import Circle
>>> circle = Circle(42.0)
>>> circle.radius
Get radius
42.0
>>> circle.radius = 100.0
Set radius
>>> circle.radius
Get radius
100.0
>>> del circle.radius
Delete radius
>>> circle.radius
Get radius
Traceback (most recent call last):
...
AttributeError: 'Circle' object has no attribute '_radius'.
⮑ Did you mean: 'radius'?
>>> help(circle)
Help on Circle in module circle_v1 object:
class Circle(builtins.object)
...
| radius
| The radius property.
The .radius
property hides the non-public instance attribute ._radius
, which is now your managed attribute in this example. You can access and assign .radius
directly. Internally, Python automatically calls ._get_radius()
and ._set_radius()
when needed. When you execute del circle.radius
, Python calls ._del_radius()
, which deletes the underlying ._radius
.
Besides using regular named functions to provide getter methods in your properties, you can also use lambda
functions.
Here’s a version of Circle
in which the .radius
property uses a lambda
function as its getter method:
>>> class Circle:
... def __init__(self, radius):
... self._radius = radius
... radius = property(lambda self: self._radius)
...
>>> circle = Circle(42.0)
>>> circle.radius
42.0
If your getter method’s functionality is limited to returning the current value of the managed attribute, then using a lambda
function can be the solution.
Properties are class attributes that manage instance attributes. You can think of a property as a collection of methods bundled together. If you inspect .radius
carefully, then you’ll find the raw methods you provided as the fget
, fset
, and fdel
arguments:
>>> Circle.radius.fget
<function Circle._get_radius at 0x7fba7e1d7d30>
>>> Circle.radius.fset
<function Circle._set_radius at 0x7fba7e1d78b0>
>>> Circle.radius.fdel
<function Circle._del_radius at 0x7fba7e1d7040>
>>> dir(Circle.radius)
[..., '__get__', ..., '__set__', ...]
You can access the getter, setter, and deleter methods in a given property through the corresponding .fget
, .fset
, and .fdel
attributes.
Properties are also descriptors. If you use dir()
to check the internal members of a given property, then you’ll find .__set__()
and .__get__()
in the list. These methods provide a default implementation of the descriptor protocol.
Note: If you want to better understand the internal implementation of property
as a class, then check out the pure Python Property
class described in the documentation.
The default implementation of .__set__()
, for example, runs when you don’t provide a custom setter method. This implementation gives you an AttributeError
when you try to set the attribute.
Using property()
as a Decorator
Decorators are frequently used in Python. They’re typically functions that take another function as an argument and return a new function with added functionality. With a decorator, you can attach pre- and post-processing operations to an existing function.
Note: In Python, you can define decorators using either a function or a class. So, you can have both function-based and class-based decorators.
The decorator syntax consists of placing the name of the decorator function with a leading @
symbol right before the definition of the function you want to decorate:
@decorator
def function():
...
In this code, @decorator
can be a function or class intended to decorate function()
. This syntax is equivalent to the following:
def function():
...
function = decorator(function)
The final line of code reassigns the name function
to hold the result of calling decorator(function)
. Note that this is the same syntax you used to create a property in the previous section.
Python’s property()
can work as a decorator, so you can use the @property
syntax to create your properties quickly:
circle_v2.py
1class Circle:
2 def __init__(self, radius):
3 self._radius = radius
4
5 @property
6 def radius(self):
7 """The radius property."""
8 print("Get radius")
9 return self._radius
10
11 @radius.setter
12 def radius(self, value):
13 print("Set radius")
14 self._radius = value
15
16 @radius.deleter
17 def radius(self):
18 print("Delete radius")
19 del self._radius
Circle
now is more Pythonic and clean. You don’t need to use method names such as ._get_radius()
, ._set_radius()
, and ._del_radius()
anymore. Now you have three methods with the same descriptive attribute-like name. How’s that possible?
The decorator approach for creating properties requires defining a first method using the public name for the underlying managed attribute, which is .radius
in this example. This method should implement the getter logic. In the above example, lines 5 to 9 implement that method.
Lines 11 to 14 define the setter method for .radius
. The syntax is different. Instead of using @property
again, you use @radius.setter
. Why do you need to do that? Take a look at the dir()
output:
>>> from circle_v2 import Circle
>>> dir(Circle.radius)
[..., 'deleter', ..., 'getter', 'setter']
Besides .fget
, .fset
, .fdel
, and a bunch of other special attributes and methods, property
also provides .deleter()
, .getter()
, and .setter()
. These three methods each return a new property.
When you decorate the second .radius()
method with @radius.setter
on line 11, you create a new property and reassign the class-level name .radius
from line 6 to hold it. This new property contains the same set of methods of the initial property on line 6 with the addition of the new setter method provided on line 12. Finally, the decorator syntax reassigns the new property to the .radius
class-level name.
The mechanism to define the deleter method is similar. This time, you need to use the @radius.deleter
decorator. At the end of the process, you get a full-fledged property with the getter, setter, and deleter methods.
Now, how can you provide suitable docstrings for your properties when you use the decorator approach? If you check Circle
again, you’ll notice that you already did so by adding a docstring to the getter method on line 7.
The new Circle
implementation works the same as the example in the section above:
>>> from circle_v2 import Circle
>>> circle = Circle(42.0)
>>> circle.radius
Get radius
42.0
>>> circle.radius = 100.0
Set radius
>>> circle.radius
Get radius
100.0
>>> del circle.radius
Delete radius
>>> circle.radius
Get radius
Traceback (most recent call last):
...
AttributeError: 'Circle' object has no attribute '_radius'.
⮑ Did you mean: 'radius'?
>>> help(circle)
Help on Circle in module circle_v2 object:
class Circle(builtins.object)
...
| radius
| The radius property.
First, note that you don’t need to use a pair of parentheses for calling .radius()
as a method. Instead, you can access .radius
as you would access a regular attribute, which is the primary purpose of properties. They allow you to treat methods as attributes.
Here’s a recap of some important points to remember when you’re creating properties with the decorator approach:
- The
@property
decorator must decorate the getter method. - The docstring must go in the getter method.
- The setter and deleter methods must be decorated with the name of the getter method plus
.setter
and.deleter
, respectively.
Up to this point, you’ve learned how to create managed attributes using property()
as a function and a decorator. It’s time to think about when you should use properties.
Deciding When to Use Properties
If you check the implementation of your Circle
class so far, then you’ll note that its getter and setter methods don’t add extra functionality on top of your attributes.
In general, you should avoid using properties for attributes that don’t require extra functionality or processing. If you do use properties this way, then you’ll make your code:
- Unnecessarily verbose
- Confusing to other developers
- Slower than code based on regular attributes
Unless you need something more than bare attribute access and mutation, don’t use properties. They’ll waste your CPU time and, more importantly, your time.
Finally, you should avoid writing explicit getter and setter methods and then wrapping them in a property. Instead, use the @property
decorator. That’s currently the Pythonic way to go.
Providing Read-Only Attributes
Probably the most elementary use case of property()
is to provide read-only attributes in your classes. Say you need an immutable Point
class that doesn’t allow the user to mutate the original value of its coordinates, x
and y
. To achieve this goal, you can create Point
like in the following example:
point_v2.py
class Point:
def __init__(self, x, y):
self._x = x
self._y = y
@property
def x(self):
return self._x
@property
def y(self):
return self._y
Here, you store the input arguments in the attributes ._x
and ._y
. As you already learned, using the leading underscore (_
) in names tells other developers that they’re non-public attributes and shouldn’t be accessed using dot notation, such as in point._x
. Finally, you define two getter methods and decorate them with @property
.
Now you have two read-only properties, .x
and .y
, as your coordinates:
>>> from point_v2 import Point
>>> point = Point(12, 5)
>>> # Read coordinates
>>> point.x
12
>>> point.y
5
>>> point.x = 42
Traceback (most recent call last):
...
AttributeError: property 'x' of 'Point' object has no setter
Here, .x
and .y
are read-only properties because you can’t assign new values to them. Their behavior relies on the underlying descriptor that property
provides. The default .__set__()
implementation on this descriptor raises an AttributeError
when you don’t define a setter method.
If you need custom behavior on a read-only property, then you can provide an explicit setter method that raises a custom exception with more elaborate and specific messages:
point_v3.py
class WriteCoordinateError(Exception):
pass
class Point:
def __init__(self, x, y):
self._x = x
self._y = y
@property
def x(self):
return self._x
@x.setter
def x(self, value):
raise WriteCoordinateError("x coordinate is read-only")
@property
def y(self):
return self._y
@y.setter
def y(self, value):
raise WriteCoordinateError("y coordinate is read-only")
In this example, you define a custom exception called WriteCoordinateError
. This exception allows you to customize the way you implement your immutable Point
class. Now, both setter methods raise your custom exception with a more explicit message. Go ahead and give your improved Point
a try!
Creating Read-Write Attributes
You can also use property()
to provide managed attributes with read-write capabilities. In practice, you just need to provide the appropriate getter (“read”) and setter (“write”) methods to your properties in order to create read-write managed attributes.
For example, say you want your Circle
class to have a .diameter
attribute. Taking the radius and the diameter in the class initializer seems unnecessary because you can compute the one using the other.
Here’s a Circle
that manages .radius
and .diameter
as read-write attributes but only takes the radius at instance creation time:
circle_v3.py
class Circle:
def __init__(self, radius):
self.radius = radius
@property
def radius(self):
return self._radius
@radius.setter
def radius(self, value):
self._radius = float(value)
@property
def diameter(self):
return self.radius * 2
@diameter.setter
def diameter(self, value):
self.radius = value / 2
Here, you create a Circle
class with a read-write .radius
property. The getter method just returns the radius value. The setter method converts the radius to a floating-point number and assigns it to the non-public ._radius
attribute, which is the variable you use to store the final data.
This new implementation of Circle
has a subtle detail that you should note. In this case, the class initializer assigns the input value to the .radius
property directly instead of storing it in a dedicated non-public attribute, such as ._radius
. Why? Because you must ensure that every radius value—including the initial one—goes through the setter method and gets converted to a floating-point number.
Circle
also implements a .diameter
attribute as a property. The getter method computes the diameter using the radius. The setter method calculates the radius and stores the result in .radius
instead of storing the input diameter in a dedicated attribute. This way of dealing with the diameter makes your class more memory-efficient because you’re only storing the radius.
Here’s how your Circle
works:
>>> from circle_v3 import Circle
>>> circle = Circle(42)
>>> circle.radius
42.0
>>> circle.diameter
84.0
>>> circle.diameter = 100
>>> circle.diameter
100.0
>>> circle.radius
50.0
In this example, both .radius
and .diameter
work as normal attributes, providing a clean and Pythonic public API for your Circle
class.
Providing Write-Only Attributes
You can also create write-only attributes by tweaking the getter method of properties. For example, you can make your getter method raise an exception every time a user accesses the underlying attribute.
Here’s a hypothetical example of handling passwords with a write-only property:
users.py
import hashlib
import os
class User:
def __init__(self, name, password):
self.name = name
self.password = password
@property
def password(self):
raise AttributeError("Password is write-only")
@password.setter
def password(self, plaintext):
salt = os.urandom(32)
self._hashed_password = hashlib.pbkdf2_hmac(
"sha256", plaintext.encode("utf-8"), salt, 100_000
)
The initializer of User
takes the username and password as arguments and stores them in .name
and .password
, respectively.
Note: The above example is only for educational purposes. It’s not a recipe for securely handling passwords in your code.
You use a property to manage how your class processes the input password. The getter method raises an AttributeError
whenever a user tries to retrieve the current password. This turns .password
into a write-only attribute:
>>> from users import User
>>> john = User("John", "secret")
>>> john._hashed_password
b'b\xc7^ai\x9f3\xd2g ... \x89^-\x92\xbe\xe6'
>>> john.password
Traceback (most recent call last):
...
AttributeError: Password is write-only
>>> john.password = "supersecret"
>>> john._hashed_password
b'\xe9l$\x9f\xaf\x9d ... b\xe8\xc8\xfcaU\r_'
In this example, you create john
as a User
instance with an initial password. The setter method hashes the password and stores it in ._hashed_password
. Note that when you try to access .password
directly, you get an AttributeError
. Finally, assigning a new value to .password
triggers the setter method and creates a new hashed password.
In the setter method of .password
, you use os.urandom()
to generate a 32-byte random string as your hashing function’s salt. To generate the hashed password, you use hashlib.pbkdf2_hmac()
. Then you store the resulting hashed password in the non-public attribute ._hashed_password
. Doing so ensures that you never save the plaintext password in any retrievable attribute.
Putting Python’s property()
Into Action
So far, you’ve learned how to use Python’s property()
to create managed attributes in your classes. You’ve used property()
as a function and as a decorator and learned about the differences between these two approaches. You also learned how to create read-only, read-write, and write-only attributes.
In the following sections, you’ll code a few examples that will help you get a better practical understanding of common use cases of property()
.
Validating Input Values
Validating input is one of the most common use cases of property()
and managed attributes. Data validation is a common requirement in code that takes input from users or other sources that you could consider untrusted. Python’s property()
provides a quick and reliable tool for dealing with input validation.
For example, getting back to the Point
class, you may require the values of .x
and .y
to be valid numbers. Since your users are free to enter any type of data, you need to make sure that your points only accept numbers.
Here’s an implementation of Point
that manages this requirement:
point_v4.py
class Point:
def __init__(self, x, y):
self.x = x
self.y = y
@property
def x(self):
return self._x
@x.setter
def x(self, value):
try:
self._x = float(value)
print("Validated!")
except ValueError:
raise ValueError('"x" must be a number') from None
@property
def y(self):
return self._y
@y.setter
def y(self, value):
try:
self._y = float(value)
print("Validated!")
except ValueError:
raise ValueError('"y" must be a number') from None
The setter methods of .x
and .y
use try
… except
blocks that validate input data using the Python EAFP (easier to ask forgiveness than permission) style. If the call to float()
succeeds, then the input data is valid, and you get Validated!
on your screen. If float()
raises a ValueError
, then the user gets a ValueError
with a more specific message.
Note: In the example above, you use the syntax raise
… from None
to hide internal details related to the context in which you’re raising the exception. From the end user’s viewpoint, these details can be confusing and make your class look unpolished.
Check out the section on the raise
statement in the documentation for more information about this topic. You can also learn more about raise
in Python’s raise
: Effectively Raising Exceptions in Your Code.
It’s important to note that assigning the .x
and .y
properties directly in .__init__()
ensures that the validation also occurs during object initialization. Not doing so can lead to issues when using property()
for data validation.
Here’s how your Point
class works now:
>>> from point_v4 import Point
>>> point = Point(12, 5)
Validated!
Validated!
>>> point.x
12.0
>>> point.y
5.0
>>> point.x = 42
Validated!
>>> point.x
42.0
>>> point.y = 100.0
Validated!
>>> point.y
100.0
>>> point.x = "one"
Traceback (most recent call last):
...
ValueError: "x" must be a number
>>> point.y = "1o"
Traceback (most recent call last):
...
ValueError: "y" must be a number
If you assign .x
and .y
values that float()
can turn into floating-point numbers, then the validation is successful, and the value is accepted. Otherwise, you get a ValueError
.
This implementation of Point
uncovers a fundamental weakness of property()
. Did you spot it? That’s it! You have repetitive code that follows specific patterns. This repetition breaks the DRY (Don’t Repeat Yourself) principle, so you would want to refactor this code to avoid it. To do so, you can abstract out the repetitive logic using a descriptor that you can call Coordinate
:
point_v5.py
class Coordinate:
def __set_name__(self, owner, name):
self._name = name
def __get__(self, instance, owner):
return instance.__dict__[self._name]
def __set__(self, instance, value):
try:
instance.__dict__[self._name] = float(value)
print("Validated!")
except ValueError:
raise ValueError(f'"{self._name}" must be a number') from None
class Point:
x = Coordinate()
y = Coordinate()
def __init__(self, x, y):
self.x = x
self.y = y
Now your code is a bit shorter and way less repetitive. You defined Coordinate
as a descriptor to manage the data validation in a single place. Then, you create .x
and .y
as class attributes holding instances of the target descriptor. The code works just like its earlier implementation. Go ahead and give it a try!
In general, if you find yourself copying and pasting property definitions throughout your code or if you spot repetitive code, like in the example above, then you should consider using descriptors.
Providing Computed Attributes
If you need an attribute that builds its value dynamically whenever you access it, then using a property can be a great choice. These kinds of attributes are commonly known as computed attributes. They’re handy when you need something that works like an eager attribute, but you want it to be lazy.
The main reason for creating lazy attributes is to postpone their computation until the attributes are needed, which can make your code more efficient.
Here’s an example of how to use property()
to create a computed attribute called .area
in a Rectangle
class:
rectangle.py
class Rectangle:
def __init__(self, width, height):
self.width = width
self.height = height
@property
def area(self):
return self.width * self.height
In this example, the Rectangle
initializer takes width
and height
as arguments and stores them in the corresponding instance attributes. The read-only property, .area
, computes and returns the area of the current rectangle every time you access it.
Another cool use case of properties is to provide a formatted value for a given attribute:
product.py
class Product:
def __init__(self, name, price):
self._name = name
self._price = float(price)
@property
def price(self):
return f"${self._price:,.2f}"
In this example, .price
is a property that formats and returns the price of a particular product. To provide a currency-like format, you use an f-string with an appropriate format specifier.
Note: This example uses floating-point numbers to represent currencies, which is bad practice. Instead, you should use decimal.Decimal
from the standard library.
As a final example of computed attributes, say you have a Point
class that uses .x
and .y
as Cartesian coordinates. You want to provide polar coordinates for your point so that you can use them in a few computations. The polar coordinate system represents each point using the distance to the origin and the angle with the horizontal coordinate axis.
Here’s a Cartesian coordinates Point
class that also provides computed polar coordinates:
point_v6.py
import math
class Point:
def __init__(self, x, y):
self.x = x
self.y = y
@property
def distance(self):
return math.dist((0, 0), (self.x, self.y))
@property
def angle(self):
return math.degrees(math.atan2(self.y, self.x))
def as_cartesian(self):
return self.x, self.y
def as_polar(self):
return self.distance, self.angle
In this example, you define two properties to compute the polar coordinates—distance and angle—of a given Point
object using its .x
and .y
Cartesian coordinates. You also add two instance methods that return the Cartesian and polar coordinates as tuples.
Here’s how this class works in practice:
>>> from point_v6 import Point
>>> point = Point(12, 5)
>>> point.x
12
>>> point.y
5
>>> point.distance
13.0
>>> point.angle
22.619864948040426
>>> point.as_cartesian()
(12, 5)
>>> point.as_polar()
(13.0, 22.619864948040426)
Properties are handy tools for providing computed attributes. However, if you’re creating an attribute that you use frequently, then computing it every time can be costly and wasteful. A good strategy to avoid this additional cost is to cache the computed value once the computation is done. That’s what you’ll do in the following section.
Caching Computed Attributes
Sometimes you have a given computed attribute that you use frequently. Constantly running the same computation may be unnecessary and expensive. To work around this problem, you can cache the computed value for later reuse.
If you have a property that computes its value from constant input values, then the result will never change. In that case, you can compute the value just once:
circle_v4.py
from time import sleep
class Circle:
def __init__(self, radius):
self.radius = radius
self._diameter = None
@property
def diameter(self):
if self._diameter is None:
sleep(0.5) # Simulate a costly computation
self._diameter = self.radius * 2
return self._diameter
This implementation of Circle
caches the computed diameter using a dedicated non-public attribute. The code works, but it has the drawback that if you ever change the value of .radius
, then .diameter
won’t return a correct value:
>>> from circle_v4 import Circle
>>> circle = Circle(42.0)
>>> circle.radius
42.0
>>> circle.diameter # With delay
84.0
>>> circle.diameter # Without delay
84.0
>>> circle.radius = 100.0
>>> circle.diameter # Wrong diameter
84.0
In these examples, you create a circle with a radius equal to 42.0
. The .diameter
property computes its value only the first time you access it. That’s why you see a delay in the first execution and no delay in the second. When you change the value of the radius, the diameter stays the same, which is a problem.
If the input data for a computed attribute changes, then you need to recalculate its value:
circle_v5.py
from time import sleep
class Circle:
def __init__(self, radius):
self.radius = radius
@property
def radius(self):
return self._radius
@radius.setter
def radius(self, value):
self._diameter = None
self._radius = value
@property
def diameter(self):
if self._diameter is None:
sleep(0.5) # Simulate a costly computation
self._diameter = self._radius * 2
return self._diameter
The setter method of the .radius
property resets ._diameter
to None
every time you change the radius. With this little update, .diameter
recalculates its value the first time you access it after every mutation of .radius
:
>>> from circle_v5 import Circle
>>> circle = Circle(42.0)
>>> circle.radius
42.0
>>> circle.diameter # With delay
84.0
>>> circle.diameter # Without delay
84.0
>>> circle.radius = 100.0
>>> circle.diameter # With delay
200.0
>>> circle.diameter # Without delay
200.0
Cool! Circle
works correctly now! It computes the diameter the first time you access it and also every time you change the radius.
Another way to create cached properties is to use functools.cached_property()
from the standard library. This function works as a decorator and allows you to transform a method into a cached property. The property computes its value only once and caches it as a normal attribute during the lifetime of the instance:
circle_v6.py
from functools import cached_property
from time import sleep
class Circle:
def __init__(self, radius):
self.radius = radius
@cached_property
def diameter(self):
sleep(0.5) # Simulate a costly computation
return self.radius * 2
Here, .diameter
computes and caches its value the first time you access it. This kind of implementation is suitable for input values that don’t change. Here’s how it works:
>>> from circle_v6 import Circle
>>> circle = Circle(42.0)
>>> circle.diameter # With delay
84.0
>>> circle.diameter # Without delay
84.0
>>> circle.radius = 100
>>> circle.diameter # Wrong diameter
84.0
>>> # Allow direct assignment
>>> circle.diameter = 200
>>> circle.diameter # Cached value
200
When you access .diameter
, you get its computed value. That value remains the same from this point on. However, unlike property()
, cached_property()
doesn’t block attribute updates unless you provide a setter method. That’s why you can update the diameter to 200
in the last couple of lines.
Pick a version of Circle
below to compare the three approaches. Each one opens after the REPL steps above, so v4 and v6 both show a stale 84.0
while v5 recomputes 200.0
, and .diameter = 200
shows which versions allow assignment:
If you want to create a cached property that doesn’t allow modifications, then you can use property()
and functools.cache()
like in the following example:
circle_v7.py
from functools import cache
from time import sleep
class Circle:
def __init__(self, radius):
self.radius = radius
@property
@cache
def diameter(self):
sleep(0.5) # Simulate a costly computation
return self.radius * 2
This code stacks @property
on top of @cache
. The combination of both decorators builds a cached property that prevents changes:
>>> from circle_v7 import Circle
>>> circle = Circle(42.0)
>>> circle.diameter # With delay
84.0
>>> circle.diameter # Without delay
84.0
>>> circle.radius = 100
>>> circle.diameter # Wrong diameter
84.0
>>> circle.diameter = 200
Traceback (most recent call last):
...
AttributeError: property 'diameter' of 'Circle' object has no setter
In these examples, when you try to assign a new value to .diameter
, you get an AttributeError
because the setter functionality comes from the property’s internal descriptor.
Logging Attribute Access and Mutation
Sometimes, you need to keep track of what your code does and how your programs flow. A way to do that in Python is to use logging
. This module provides all the functionality you require for logging your code. It allows you to constantly watch the code and generate useful information about how it works.
If you ever need to keep track of how and when you access and mutate a given attribute, then you can take advantage of property()
for that, too:
circle_v8.py
import logging
logging.basicConfig(
format="%(asctime)s: %(message)s",
level=logging.INFO,
datefmt="%H:%M:%S"
)
class Circle:
def __init__(self, radius):
self._msg = '"radius" was %s. Current value: %s'
self.radius = radius
@property
def radius(self):
logging.info(self._msg % ("accessed", str(self._radius)))
return self._radius
@radius.setter
def radius(self, value):
try:
self._radius = float(value)
logging.info(self._msg % ("mutated", str(self._radius)))
except ValueError:
logging.info('validation error while mutating "radius"')
Here, you first import logging
and define a basic configuration. Then you implement Circle
with a managed attribute .radius
. The getter method generates log information every time you access .radius
in your code. The setter method logs each mutation that you perform on .radius
. It also logs those situations in which you get an error because of bad input data.
Here’s how you can use Circle
in your code:
>>> from circle_v8 import Circle
>>> circle = Circle(42.0)
>>> circle.radius
14:48:59: "radius" was accessed. Current value: 42.0
42.0
>>> circle.radius = 100
14:49:15: "radius" was mutated. Current value: 100
>>> circle.radius
14:49:24: "radius" was accessed. Current value: 100
100
>>> circle.radius = "value"
15:04:51: validation error while mutating "radius"
Logging data from attribute access and mutation can help you debug your code. Logging can also help you identify sources of problematic data input, analyze the performance of your code, spot usage patterns, and more.
Managing Attribute Deletion
You can create properties that implement deletion functionality. This might be a rare use case of property()
, but having a way to delete an attribute can be handy in some situations.
Say you’re implementing your own tree data type. A tree is an abstract data type that stores elements in a hierarchy. The tree components are commonly known as nodes. Each node in a tree has a parent node, except for the root node. Nodes can have zero or more children.
Now, suppose you need to delete or clear the list of children of a given node. Here’s an example that implements a tree node that uses property()
to provide most of its functionality, including the ability to clear the node’s list of children:
tree.py
class TreeNode:
def __init__(self, data):
self._data = data
self._children = []
@property
def children(self):
return self._children
@children.setter
def children(self, value):
if isinstance(value, list):
self._children = value
else:
del self.children
self._children.append(value)
@children.deleter
def children(self):
self._children.clear()
def __repr__(self):
return f'{self.__class__.__name__}("{self._data}")'
In this example, TreeNode
represents a node in your custom tree data type. Each node stores its children in a Python list
. Then, you implement .children
as a property to manage the underlying list of children. The deleter method calls .clear()
on the list of children to remove them all.
Here’s how your class works:
>>> from tree import TreeNode
>>> root = TreeNode("root")
>>> child1 = TreeNode("child 1")
>>> child2 = TreeNode("child 2")
>>> root.children = [child1, child2]
>>> root.children
[TreeNode("child 1"), TreeNode("child 2")]
>>> del root.children
>>> root.children
[]
In this example, you first create a root
node to initialize the tree. Then, you create two new nodes and assign them to .children
using a list. The del
statement triggers the internal deleter method of .children
and clears the list of nodes.
Creating Backward-Compatible Class APIs
As you already know, properties turn direct attribute lookups into method calls. This feature allows you to create clean and Pythonic APIs for your classes. You can expose your attributes publicly without using getter and setter methods.
If you ever need to modify how you compute a given public attribute, then you can turn it into a property. Properties allow you to perform extra processing, such as data validation, without having to modify your public APIs.
Suppose you’re creating an accounting application and need a base class to manage currencies. To this end, you create a Currency
class that exposes two attributes, .units
and .cents
:
currency_v1.py
class Currency:
def __init__(self, units, cents):
self.units = units
self.cents = cents
# Currency implementation...
This class looks clean and Pythonic. Now, say that your requirements change, and you decide to store the total number of cents instead of the units and cents. Removing .units
and .cents
from your public API to use something like .total_cents
could break the code of more than one user.
In this situation, property()
can be an excellent option to keep your current API unchanged. Here’s how you can work around the problem and avoid breaking your users’ code:
currency_v2.py
CENTS_PER_UNIT = 100
class Currency:
def __init__(self, units, cents):
self._total_cents = units * CENTS_PER_UNIT + cents
@property
def units(self):
return self._total_cents // CENTS_PER_UNIT
@units.setter
def units(self, value):
self._total_cents = self.cents + value * CENTS_PER_UNIT
@property
def cents(self):
return self._total_cents % CENTS_PER_UNIT
@cents.setter
def cents(self, value):
self._total_cents = self.units * CENTS_PER_UNIT + value
# Currency implementation...
Now your class stores the total number of cents instead of independent units and cents. Because of the new properties, your users can still access and mutate .units
and .cents
in their code and get the same result as before. Go ahead and give it a try!
When you write code that others will build upon, you need to guarantee that modifications to your code’s internal implementation don’t affect how end users work with it.
Overriding Properties in Subclasses
When you create Python classes that include properties and distribute them in a package or library, you should expect your users to do unexpected things with them. One of those things could be subclassing them to customize their functionalities. In these cases, your users should be aware of a subtle gotcha. If you partially override a property, then you lose the non-overridden functionality.
For example, suppose you need an Employee
class to manage employee information. You already have another class called Person
, and you think of subclassing it to reuse its functionalities.
Person
has a .name
attribute implemented as a property. The current implementation of .name
doesn’t work for Employee
because you want the employee’s name to be in uppercase letters. Here’s how you may end up writing Employee
using inheritance:
persons.py
class Person:
def __init__(self, name):
self._name = name
@property
def name(self):
return self._name
@name.setter
def name(self, value):
self._name = value
# Person implementation...
class Employee(Person):
@property
def name(self):
return super().name.upper()
# Employee implementation...
In Employee
, you override .name
to make sure that when you access the attribute, you get the employee name in uppercase:
>>> from persons import Employee, Person
>>> person = Person("John")
>>> person.name
'John'
>>> person.name = "John Doe"
>>> person.name
'John Doe'
>>> employee = Employee("John")
>>> employee.name
'JOHN'
Great! Employee
works as you need and returns the name in uppercase letters. However, subsequent tests uncover an unexpected issue:
>>> employee.name = "John Doe"
Traceback (most recent call last):
...
AttributeError: property 'name' of 'Employee' object has no setter
What happened? When you override an existing property from a parent class, you override the whole functionality of that property. In this example, you reimplemented the getter method only. Because of that, .name
lost the rest of its inherited functionality. You don’t have a setter method any longer.
The takeaway here is that if you ever need to override a property in a subclass, then you must provide all the functionality you need in the new version of the property.
Conclusion
A property is a special type of class member that provides functionality that’s somewhere in between regular attributes and methods. Properties allow you to modify the implementation of instance attributes without changing the class’s public API. Being able to keep your APIs unchanged helps you avoid breaking code that your users have written on top of older versions of your classes.
Properties are the Pythonic way to create managed attributes in your classes. They have several use cases in real-world programming, making them a great addition to your skill set as a Python developer.
In this tutorial, you learned how to:
- Create managed attributes with Python’s
property()
- Perform lazy attribute evaluation and provide computed attributes
- Make your classes Pythonic using properties instead of setter and getter methods
- Create read-only and read-write properties
- Create consistent and backward-compatible APIs for your classes
You also wrote several practical examples that walked you through the most common use cases of property()
. Those examples include input data validation, computed attributes, logging your code, and more.
Get Your Code: Click here to download the free sample code that shows you how to use Python’s property() to add managed attributes to your classes.
Frequently Asked Questions
Now that you have some experience with Python’s property()
, you can use the questions and answers below to check your understanding and recap what you’ve learned.
These FAQs are related to the most important concepts you’ve covered in this tutorial. Click the Show/Hide toggle beside each question to reveal the answer.
In Python, a property is a language construct that allows you to define methods in a class, which can be accessed like attributes. It provides a way to add custom behavior to attributes without changing the class’s public API.
The @property
decorator turns a method into a getter for a managed attribute. You can also define setter and deleter methods using @property_name.setter
and @property_name.deleter
to control attribute assignment and deletion.
You should use a property when you need to add logic to attribute access, such as validation or transformation, without changing the class’s public API. Properties are useful for computed attributes and managing read-only or write-only access.
Avoid using the @property
decorator when the attribute doesn’t require additional logic for access or mutation, as it can make the code unnecessarily complex and slower than using regular attributes.
To create read-only attributes, define a getter method with @property
and omit the setter. For read-write attributes, define both getter and setter methods using @property
and @property_name.setter
.
Take the Quiz: Test your knowledge with our interactive “Python's property(): Add Managed Attributes to Your Classes” quiz. You’ll receive a score upon completion to help you track your learning progress:
Interactive Quiz
Python's property(): Add Managed Attributes to Your ClassesIn this quiz, you'll test your understanding of Python's property(). With this knowledge, you'll be able to create managed attributes in your classes, perform lazy attribute evaluation, provide computed attributes, and more.