The Getter and Setter Approach in Python

Technically, there’s nothing that stops you from using getter and settermethods in Python. Here’s a quick example that shows how this approach would look:

classPoint:def__init__(self,x,y):self._x=xself._y=ydefget_x(self):returnself._xdefset_x(self,value):self._x=valuedefget_y(self):returnself._ydefset_y(self,value):self._y=value

In this example, you create aPoint class with twonon-public attributes._x and._y to hold theCartesian coordinates of the point at hand.

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 ofPoint in a Pythonmodule andimport the class into aninteractive session. Then run the following code:

>>>frompoint_v1importPoint>>>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._x42>>>point._y5

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 rewritePoint in a more concise and Pythonic way:

>>>classPoint:...def__init__(self,x,y):...self.x=x...self.y=y...>>>point=Point(12,5)>>>point.x12>>>point.y5>>>point.x=42>>>point.x42

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 intoproperties.

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.

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.

Creating Attributes Withproperty()

You can create a property by callingproperty() with an appropriate set of arguments and assigning its return value to a class attribute. All the arguments toproperty() are optional. However, you typically provide at least agetter function.

The following example shows how to create aCircle class with a property that manages its radius:

classCircle:def__init__(self,radius):self._radius=radiusdef_get_radius(self):print("Get radius")returnself._radiusdef_set_radius(self,value):print("Set radius")self._radius=valuedef_del_radius(self):print("Delete radius")delself._radiusradius=property(fget=_get_radius,fset=_set_radius,fdel=_del_radius,doc="The radius property.")

In this code snippet, you createCircle. The class initializer,.__init__(), takesradius as an argument and stores it in a non-public attribute called._radius. Then, you define three non-public methods:

1. ._get_radius() returns the current value of._radius
2. ._set_radius() takesvalue as an argument and assigns it to._radius
3. ._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 toproperty(). You also pass a suitable docstring for your property.

In this example, you usekeyword arguments to improve readability and prevent confusion. That way, you know exactly which method goes into each argument.

To giveCircle a try, run the following code in your PythonREPL:

>>>fromcircle_v1importCircle>>>circle=Circle(42.0)>>>circle.radiusGet radius42.0>>>circle.radius=100.0Set radius>>>circle.radiusGet radius100.0>>>delcircle.radiusDelete radius>>>circle.radiusGet radiusTraceback (most recent call last):...AttributeError:'Circle' object has no attribute '_radius'>>>help(circle)Help on Circle in module __main__ 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 executedel circle.radius, Python calls._del_radius(), which deletes the underlying._radius.

>>>classCircle:...def__init__(self,radius):...self._radius=radius...radius=property(lambdaself:self._radius)...>>>circle=Circle(42.0)>>>circle.radius42.0

Properties areclass attributes that manageinstance 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 thefget,fset, andfdel 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 alsodescriptors. If you usedir() 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 thedescriptor protocol.

The default implementation of.__set__(), for example, runs when you don’t provide a custom setter method. This implementation gives you anAttributeError when you try to set the attribute.

Usingproperty() 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.

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:

@decoratordeffunction():...

In this code,@decorator can be a function or class intended to decoratefunction(). This syntax is equivalent to the following:

deffunction():...function=decorator(function)

The final line of code reassigns the namefunction to hold the result of callingdecorator(function). Note that this is the same syntax you used to create a property in the previous section.

Python’sproperty() can work as a decorator, so you can use the@property syntax to create your properties quickly:

 1classCircle: 2def__init__(self,radius): 3self._radius=radius 4 5@property 6defradius(self): 7"""The radius property.""" 8print("Get radius") 9returnself._radius1011@radius.setter12defradius(self,value):13print("Set radius")14self._radius=value1516@radius.deleter17defradius(self):18print("Delete radius")19delself._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 thedir() output:

>>>fromcircle_v2importCircle>>>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 checkCircle again, you’ll notice that you already did so by adding a docstring to the getter method on line 7.

The newCircle implementation works the same as the example in the section above:

>>>fromcircle_v2importCircle>>>circle=Circle(42.0)>>>circle.radiusGet radius42.0>>>circle.radius=100.0Set radius>>>circle.radiusGet radius100.0>>>delcircle.radiusDelete radius>>>circle.radiusGet radiusTraceback (most recent call last):...AttributeError:'Circle' object has no attribute '_radius'>>>help(circle)Help on Circle in module __main__ 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 thegetter method.
• The docstring must go in thegetter method.
• Thesetter 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 usingproperty() as a function and a decorator. It’s time to think about when you should use properties.

Validating Input Values

Validating input is one of the most common use cases ofproperty() 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’sproperty() provides a quick and reliable tool for dealing with input validation.

For example, getting back to thePoint class, you may require the values of.x and.y to be validnumbers. 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 ofPoint that manages this requirement:

classPoint:def__init__(self,x,y):self.x=xself.y=y@propertydefx(self):returnself._x@x.setterdefx(self,value):try:self._x=float(value)print("Validated!")exceptValueError:raiseValueError('"x" must be a number')fromNone@propertydefy(self):returnself._y@y.setterdefy(self,value):try:self._y=float(value)print("Validated!")exceptValueError:raiseValueError('"y" must be a number')fromNone

The setter methods of.x and.y usetry …except blocks that validate input data using the PythonEAFP (easier to ask forgiveness than permission) style. If the call tofloat() succeeds, then the input data is valid, and you getValidated! on your screen. Iffloat() raises aValueError, then the user gets aValueError with a more specific message.

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 usingproperty() for data validation.

Here’s how yourPoint class works now:

>>>frompoint_v4importPoint>>>point=Point(12,5)Validated!Validated!>>>point.x12.0>>>point.y5.0>>>point.x=42Validated!>>>point.x42.0>>>point.y=100.0Validated!>>>point.y100.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 thatfloat() can turn into floating-point numbers, then the validation is successful, and the value is accepted. Otherwise, you get aValueError.

This implementation ofPoint uncovers a fundamental weakness ofproperty(). Did you spot it? That’s it! You have repetitive code that follows specific patterns. This repetition breaks theDRY (Don’t Repeat Yourself) principle, so you would want torefactor this code to avoid it. To do so, you can abstract out the repetitive logic using adescriptor that you can callCoordinate:

classCoordinate:def__set_name__(self,owner,name):self._name=namedef__get__(self,instance,owner):returninstance.__dict__[self._name]def__set__(self,instance,value):try:instance.__dict__[self._name]=float(value)print("Validated!")exceptValueError:raiseValueError(f'"{self._name}" must be a number')fromNoneclassPoint:x=Coordinate()y=Coordinate()def__init__(self,x,y):self.x=xself.y=y

Now your code is a bit shorter and way less repetitive. You definedCoordinate 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 ascomputed attributes. They’re handy when you need something that works like aneager attribute, but you want it to belazy.

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 useproperty() to create a computed attribute called.area in aRectangle class:

classRectangle:def__init__(self,width,height):self.width=widthself.height=height@propertydefarea(self):returnself.width*self.height

In this example, theRectangle initializer takeswidth andheight 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 aformatted value for a given attribute:

classProduct:def__init__(self,name,price):self._name=nameself._price=float(price)@propertydefprice(self):returnf"${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 anf-string with an appropriateformat specifier.

As a final example of computed attributes, say you have aPoint class that uses.x and.y as Cartesian coordinates. You want to providepolar 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 coordinatesPoint class that also provides computed polar coordinates:

importmathclassPoint:def__init__(self,x,y):self.x=xself.y=y@propertydefdistance(self):returnmath.dist((0,0),(self.x,self.y))@propertydefangle(self):returnmath.degrees(math.atan2(self.y,self.x))defas_cartesian(self):returnself.x,self.ydefas_polar(self):returnself.distance,self.angle

In this example, you define two properties to compute the polar coordinates—distance and angle—of a givenPoint 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:

>>>frompoint_v6importPoint>>>point=Point(12,5)>>>point.x12>>>point.y5>>>point.distance13.0>>>point.angle22.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 tocache 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:

fromtimeimportsleepclassCircle:def__init__(self,radius):self.radius=radiusself._diameter=None@propertydefdiameter(self):ifself._diameterisNone:sleep(0.5)# Simulate a costly computationself._diameter=self.radius*2returnself._diameter

This implementation ofCircle 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:

>>>fromcircle_v4importCircle>>>circle=Circle(42.0)>>>circle.radius42.0>>>circle.diameter# With delay84.0>>>circle.diameter# Without delay84.0>>>circle.radius=100.0>>>circle.diameter# Wrong diameter84.0

In these examples, you create a circle with a radius equal to42.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:

fromtimeimportsleepclassCircle:def__init__(self,radius):self.radius=radius@propertydefradius(self):returnself._radius@radius.setterdefradius(self,value):self._diameter=Noneself._radius=value@propertydefdiameter(self):ifself._diameterisNone:sleep(0.5)# Simulate a costly computationself._diameter=self._radius*2returnself._diameter

The setter method of the.radius property resets._diameter toNone 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:

>>>fromcircle_v5importCircle>>>circle=Circle(42.0)>>>circle.radius42.0>>>circle.diameter# With delay84.0>>>circle.diameter# Without delay84.0>>>circle.radius=100.0>>>circle.diameter# With delay200.0>>>circle.diameter# Without delay200.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 usefunctools.cached_property() from thestandard 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:

fromfunctoolsimportcached_propertyfromtimeimportsleepclassCircle:def__init__(self,radius):self.radius=radius@cached_propertydefdiameter(self):sleep(0.5)# Simulate a costly computationreturnself.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:

>>>fromcircle_v6importCircle>>>circle=Circle(42.0)>>>circle.diameter# With delay84.0>>>circle.diameter# Without delay84.0>>>circle.radius=100>>>circle.diameter# Wrong diameter84.0>>># Allow direct assignment>>>circle.diameter=200>>>circle.diameter# Cached value200

When you access.diameter, you get its computed value. That value remains the same from this point on. However, unlikeproperty(),cached_property() doesn’t block attribute updates unless you provide a setter method. That’s why you can update the diameter to200 in the last couple of lines.

If you want to create a cached property that doesn’t allow modifications, then you can useproperty() andfunctools.cache() like in the following example:

fromfunctoolsimportcachefromtimeimportsleepclassCircle:def__init__(self,radius):self.radius=radius@property@cachedefdiameter(self):sleep(0.5)# Simulate a costly computationreturnself.radius*2

This code stacks@property on top of@cache. The combination of both decorators builds a cached property that prevents changes:

>>>fromcircle_v7importCircle>>>circle=Circle(42.0)>>>circle.diameter# With delay84.0>>>circle.diameter# Without delay84.0>>>circle.radius=100>>>circle.diameter# Wrong diameter84.0>>>circle.diameter=200Traceback (most recent call last):...AttributeError:can't set attribute

In these examples, when you try to assign a new value to.diameter, you get anAttributeError 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 uselogging. 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 ofproperty() for that, too:

importlogginglogging.basicConfig(format="%(asctime)s:%(message)s",level=logging.INFO,datefmt="%H:%M:%S")classCircle:def__init__(self,radius):self._msg='"radius" was%s. Current value:%s'self.radius=radius@propertydefradius(self):logging.info(self._msg%("accessed",str(self._radius)))returnself._radius@radius.setterdefradius(self,value):try:self._radius=float(value)logging.info(self._msg%("mutated",str(self._radius)))exceptValueError:logging.info('validation error while mutating "radius"')

Here, you first importlogging and define a basic configuration. Then you implementCircle 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 useCircle in your code:

>>>fromcircle_v8importCircle>>>circle=Circle(42.0)>>>circle.radius14:48:59: "radius" was accessed. Current value: 42.042.0>>>circle.radius=10014:49:15: "radius" was mutated. Current value: 100>>>circle.radius14:49:24: "radius" was accessed. Current value: 100100>>>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 ofproperty(), but having a way to delete an attribute can be handy in some situations.

Say you’re implementing your owntree data type. A tree is anabstract data type that stores elements in a hierarchy. The tree components are commonly known asnodes. 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 usesproperty() to provide most of its functionality, including the ability to clear the node’s list of children:

classTreeNode:def__init__(self,data):self._data=dataself._children=[]@propertydefchildren(self):returnself._children@children.setterdefchildren(self,value):ifisinstance(value,list):self._children=valueelse:delself.childrenself._children.append(value)@children.deleterdefchildren(self):self._children.clear()def__repr__(self):returnf'{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 Pythonlist. 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:

>>>fromtreeimportTreeNode>>>root=TreeNode("root")>>>child1=TreeNode("child 1")>>>child2=TreeNode("child 2")>>>root.children=[child1,child2]>>>root.children[TreeNode("child 1"), TreeNode("child 2")]>>>delroot.children>>>root.children[]

In this example, you first create aroot node to initialize the tree. Then, you create two new nodes and assign them to.children using a list. Thedel 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 aCurrency class that exposes two attributes,.units and.cents:

classCurrency:def__init__(self,units,cents):self.units=unitsself.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:

CENTS_PER_UNIT=100classCurrency:def__init__(self,units,cents):self._total_cents=units*CENTS_PER_UNIT+cents@propertydefunits(self):returnself._total_cents//CENTS_PER_UNIT@units.setterdefunits(self,value):self._total_cents=self.cents+value*CENTS_PER_UNIT@propertydefcents(self):returnself._total_cents%CENTS_PER_UNIT@cents.setterdefcents(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.