So, what exactly is that property object doing? Think of the property function as returning an object that proxies any requests to set or access the attribute value through the methods we have specified. The property keyword is like a constructor for such an object.

This property constructor can actually accept two additional arguments, a deletion function and a docstring for the property. The delete function is rarely supplied in practice, but it can be useful for logging that a value has been deleted, or possibly to veto deleting if we have reason to do so. The docstring is just a string describing what the property does, no different from the docstrings we discussed in Chapter 2. If we do not supply this parameter, the docstring will instead be copied from the docstring for the first argument: the getter method.

Here is a silly example that simply states whenever any of the methods are called:

	class Silly:
		def _get_silly(self):
			print("You are getting silly")
			return self._silly
		def _set_silly(self, value):
			print("You are making silly {}".format(value))
			self._silly = value
		def _del_silly(self):
			print("Whoah, you killed silly!")
			del self._silly	
		
		silly = property(_get_silly, _set_silly,
				_del_silly, "This is a silly property")

If we actually use this class, it does indeed print out the correct strings when we ask it to:

>>> s = Silly()
>>> s.silly = "funny"
You are making silly funny
>>> s.silly
You are getting silly
'funny'
>>> del s.silly
Whoah, you killed silly!

Further, if we look at the help file for the Silly class (by issuing help(silly) at the interpreter prompt), it shows us the custom docstring for our silly attribute:

	Help on class Silly in module __main__:

	class Silly(builtins.object)
	| Data descriptors defined here:
	|
	| __dict__
	|		 dictionary for instance variables (if defined)
	|
	| __weakref__
	| 		list of weak references to the object (if defined)
	|
	| silly
	| 		This is a silly property

Once again, everything is working as we planned. In practice, properties are normally only defined with the first two parameters; the getter and setter functions. The docstring is defined as a normal docstring on the getter and copied into the property, while the deletion function is left empty because object attributes are rarely deleted. If a coder does try to delete one that doesn't have a deletion function specified, however, it will raise an exception, so if there is any chance of a legitimate reason to delete our property, we should supply that function.

(If you've never used Python decorators before, you might want to skip this section and come back to it after we've discussed the decorator pattern in Chapter 8.)

Decorators were introduced in Python 2.4 as a way to modify functions dynamically by passing them as arguments to other functions, which eventually return a new function. We won't be covering decorators in-depth at this time, but the basic syntax is easy to grasp. If you've never used them before, you can still follow along.

Applying a decorator can be as simple as prefixing the function name with an @ symbol, and placing the result just before the definition of the function that is being decorated. The property function itself can be used with decorator syntax to turn a get function into a property:

	class Foo:
		@property
		def foo(self):
			return "bar"

This applies property as a decorator, and is equivalent to applying it as foo = property(foo). The main difference, from a readability perspective, is that we get to mark the foo function as a property at the top of the method, instead of after it is defined, where it can be easily overlooked.

Going one step further, we can specify a setter function for the new property as follows:

	class Foo:
		@property
			def foo(self):
			return self._foo
	
		@foo.setter
		def foo(self, value):
			self._foo = value

This syntax looks a little odd. First we decorate the foo method as a getter. Then we decorate a new method with exactly the same name with the setter attribute of the original decorated foo method! Remember, the property function returns an object; this object is automatically set up to have a setter attribute, and this attribute can be applied as a decorator to other functions. Using the same name for the get and set methods is not required, but it does help group the multiple methods that create one property together.

We can, of course, also specify a deletion function with @foo.deleter. We cannot specify a docstring using property decorators, so we need to rely on the property copying the docstring from the initial getter method.

Here's our previous Silly class rewritten to use property as a decorator:

	class Silly:
		@property
		def silly(self):
			"This is a silly property"
			print("You are getting silly")
			return self._silly

		@silly.setter
		def silly(self, value):
			print("You are making silly {}".format(value))
			self._silly = value
		
		@silly.deleter
		def silly(self):
			print("Whoah, you killed silly!")
			del self._silly

This class operates exactly the same as our earlier version, including the help text. You can use whichever syntax you feel is more readable and elegant.

With the property keyword smearing the division between behavior and data, it can be confusing to know which one to choose. The example use case we saw earlier is one of the most common uses of properties: we have some data on a class that we later want to add behavior to. There are also other factors to take into account when deciding to use a property.

Technically, in Python, data, properties, and methods are all attributes on a class. The fact that a method is callable does not distinguish it from other types of attributes; indeed, we'll see in Chapter 7 that it is possible to create normal objects that are callable, and also that functions and methods are themselves normal objects.

The fact that methods are just callable attributes, and properties are just customizable attributes can help us in our decision. Methods should only represent actions; things that can be done to or performed by the object. When you call a method, even with only one argument, it should do something. Methods are generally verbs.

That leaves us to decide between standard data attributes and properties. In general, always use a standard attribute until you need to control access to that property in some way. In either case, your attribute should be a noun. The only difference between an attribute and a property is that we can invoke custom actions automatically when a property is retrieved, set, or deleted.

Let's try a more realistic example. A common need for custom behavior is caching a value that is difficult to calculate or expensive to look up (requiring, for example, a network request or database query). The goal is to store the value locally to avoid repeated calls to the expensive calculation.

We can do this with a custom getter on the property. The first time the value is retrieved, we perform the lookup or calculation. Then we could locally cache the value as a private attribute on our object (or in dedicated caching software), and the next time the value is requested, we return the stored data. Here's how we might cache a webpage:

	from urllib.request import urlopen
	
	class WebPage:
		def __init__(self, url):
			self.url = url
			self._content = None
	
		@property
		def content(self):
			if not self._content:
				print("Retrieving New Page...")
				self._content = urlopen(self.url).read()
			return self._content

We can test this code to see that the page is only retrieved once:

>>> import time
>>> webpage = WebPage("http://ccphillips.net/")
>>> now = time.time()
>>> content1 = webpage.content
Retrieving New Page...
>>> time.time() - now
22.43316888809204
>>> now = time.time()
>>> content2 = webpage.content
>>> time.time() - now
1.9266459941864014
>>> content2 == content1
True

On my awful satellite connection it takes twenty seconds the first time I load the content, but the second time, I get the result in two seconds (which is really just the amount of time it took to type the lines into the interpreter).

Custom getters are also useful for attributes that need to be calculated on the fly, based on other object attributes. For example, we might want to calculate the average for a list of integers:

	class AverageList(list):
		@property
		def average(self):	
			return sum(self) / len(self)

This very simple class inherits from list, so we get list-like behavior for free. We just add a property to the class, and presto, our list can have an average:

>>> a = AverageList([1,2,3,4])
>>> a.average
2.5

Of course, we could have made this a method instead, but then we should call it calculate_average(), since methods represent actions. But a property called average is more suitable; both easier to type, and easier to read.

Custom setters are useful for validation, as we've already seen, but they can also be used to proxy a value to another location. For example, we could add a content setter to the WebPage class that automatically logs into our web server and uploads a new page whenever the value is set.